---
trigger: always_on
---

<!--
Sync Impact Report:
Version change: 1.2.0 -> 2.0.0
Scope change: domain-specific constitution -> generic agent engineering constitution
Modified principles:
  - Replaced domain-specific technology mandates with generic project-first engineering rules
  - Added multi-agent orchestration, workspace isolation, visual verification, repair loop, and model assignment rules
Removed sections:
  - Mahjong/OCR/RL/Android automation specific technology constraints
Templates requiring updates:
  - None for this document-only change
Follow-up TODOs:
  - If new projects should load this automatically, reference it from AGENTS.md, bootstrap output, or task-run profiles
Rationale for version bump (MAJOR):
  - Governance scope changed from one project domain to reusable cross-project agent workflow
-->

# 通用智能体工程宪章

## 定位

本宪章用于多智能体工程流程、Codex Harness、项目导入包和长期稳定规则。它不绑定具体业务域、技术栈或产品形态。

具体项目的业务规则、目录结构、提交规范、性能指标和部署细节应写入项目根 `AGENTS.md`、`docs/`、`specs/` 或 `.specify/memory/constitution.md`。本宪章只保留跨项目长期成立的工程约束。

---

## 核心原则

### I. 需求先行与可验收目标

**原则声明**:

- 开始实现前必须明确用户目标、输入、输出、约束、非目标和验收标准。
- 对会影响架构、安全、数据、成本或交付结果的问题，必须先澄清或显式记录假设。
- 需求评审完成后，应能让下一个 agent 不依赖隐含上下文即可继续执行。
- 任何阶段发现需求和实现不一致，必须回到需求或设计文档补齐，再继续编码。

**理由**:
多智能体并行时，模糊需求会被快速放大。先定义可验收目标，可以减少返工并让自动化修复有明确终点。

---

### II. 项目优先的胶水编程

**原则声明**:

- 新增功能必须优先复用当前项目已有模式，其次复用成熟库或参考完整开源项目，最后才做最小自定义实现。
- 引入第三方项目、模板或库时，必须记录来源、许可证、版本或 commit、边界和替换策略。
- 项目代码应以薄封装和轻组合为主，将外部能力隔离在 Adapter、Connector、Service 或 Integration 层。
- 不允许业务代码散落直接调用复杂第三方 API；必须通过项目内稳定接口收敛。

**理由**:
工程价值通常来自正确组合现有能力，而不是重复实现基础设施。项目优先可以保持风格一致，降低维护成本。

---

### III. 最小自定义实现

**原则声明**:

- 禁止在已有成熟方案可用时自行实现框架、协议解析器、测试基础设施、认证流程、队列系统、状态管理内核或复杂算法。
- 只有在现有方案不满足需求、许可证不可接受、性能或部署约束不匹配时，才允许自定义实现。
- 自定义实现必须附带调研结论、取舍说明、测试覆盖和后续替换边界。
- 复杂逻辑必须集中在少量清晰模块中，避免跨文件隐式耦合。

**理由**:
最小实现降低长期维护风险，让 agent 把精力放在业务差异和集成正确性上。

---

### IV. 多智能体编排与工作区隔离

**原则声明**:

- 主控 agent 负责任务拆解、上下文分发、路径所有权、闸门判断、结果合并和最终交付。
- Worker agent 必须拥有清晰的职责边界，例如前端、后端、测试、文档、评审、修复或发布。
- 并发执行时，不同 agent 应使用独立目录或明确互斥的写入路径。
- Worker 结束时必须报告变更文件、验证命令、证据路径、未解决问题和需要主控合并的事项。
- 主控不得盲目合并并行结果；必须检查冲突、重复实现、接口不一致和测试缺口。

**理由**:
多 agent 的核心风险不是并发本身，而是写入边界不清。路径所有权和主控合并可以避免脏文件、覆盖和上下文漂移。

---

### V. 测试驱动与持续验证

**原则声明**:

- 对边界清晰的功能，优先采用 TDD: 先写失败测试，再实现，再重构。
- 对既有系统修改，至少在改动前确认可运行的基线验证命令。
- 每次声称完成前必须有 fresh verification evidence，不能只依赖推测。
- 验证范围应匹配风险: 文档改动跑文档检查，纯 UI 改动跑截图和交互检查，后端合同改动跑单元、集成和契约测试。
- 验证失败必须进入修复队列，直到通过、降级说明被接受，或形成明确阻塞。

**理由**:
自动化流程只有在可验证时才可靠。没有证据的完成声明无法支撑持续并行开发。

---

### VI. 模块化、契约和可替换性

**原则声明**:

- 系统应按职责划分模块，例如 UI、API、Domain、Data、Worker、Integration、Test Harness。
- 跨模块通信必须通过稳定契约: 类型、接口、schema、事件、API 文档或测试夹具。
- Adapter 负责封装外部系统，Connector 负责组合多个能力，业务层不得直接依赖外部系统细节。
- 数据流、错误流和状态流必须能被追踪，不能依赖隐式全局状态。
- 公共模块变更必须评估影响面并补充回归测试。

**理由**:
清晰契约可以让多个 agent 并行实现不同层，并在集成阶段快速定位不一致。

---

### VII. 可观测性与调试性

**原则声明**:

- 关键流程必须记录结构化日志、命令输出摘要、输入输出位置和失败原因。
- 日志不得包含 token、cookie、私钥、密码、个人敏感信息或生产数据样本。
- 自动化运行应保存 trace，包括任务、agent、目录、命令、退出码、截图、报告和修复记录。
- 错误处理必须包含可恢复策略或清晰失败信息，不能静默吞错。

**理由**:
长时间自动运行必然会遇到网络、环境和依赖波动。可观测性是持续修复和断点恢复的基础。

---

### VIII. UI 设计还原与视觉验证

**原则声明**:

- UI 实现前应有明确设计来源: 设计图、AI 生成图、页面规格、组件规范或参考截图。
- 前端完成后必须通过浏览器截图保存实际界面证据，截图应放入项目约定的 artifacts 或 evidence 目录。
- Review 时必须对比设计图和实际截图，记录布局、颜色、字体、间距、状态、响应式和交互差异。
- 视觉差异必须进入修复队列；如果无法一比一还原，必须说明原因和接受标准。
- UI 不能只通过代码审查完成，必须至少验证关键页面在目标视口下真实渲染。

**理由**:
前端质量最终体现在真实界面。截图对比让 agent 能把设计意图转化为可验证证据。

---

### IX. 自动修复闭环

**原则声明**:

- 每个失败项必须转成结构化 Repair Queue，包含严重级别、复现步骤、期望结果、实际结果、负责人和验证命令。
- 自动修复应按阻塞级别排序: 构建失败、测试失败、关键功能失败、视觉偏差、文档缺口。
- 修复后必须重新运行与失败项直接对应的验证命令。
- 当连续修复无法推进时，agent 必须输出阻塞原因、已尝试方案、当前证据和建议的人工决策点。

**理由**:
全自动实现不是无限循环，而是有证据、有优先级、有退出条件的持续修复。

---

### X. 安全、隐私和依赖治理

**原则声明**:

- 禁止把 token、cookie、私钥、密码、账号凭据写入仓库、日志、trace、截图或文档。
- 环境变量必须通过 `.env.example`、配置模板或密钥管理说明表达，不提交真实值。
- 引入依赖前必须关注许可证、维护状态、版本锁定、供应链风险和替代方案。
- 涉及认证、支付、权限、数据删除、生产配置的改动必须提高评审和验证等级。

**理由**:
自动化 agent 会放大一次错误操作的影响。安全边界必须优先于交付速度。

---

### XI. 文档与上下文同步

**原则声明**:

- 改变行为、接口、目录、命令、部署、测试或工作流时，必须同步更新相关文档。
- 文档应说明当前事实、操作命令、验证方式和已知限制，避免只写愿景。
- 长文档放 `docs/`，项目规则放项目根 `AGENTS.md`，跨项目语义规则放 `.codex/rules/*.md` 或全局规则；`.codex/rules/*.rules` 只放 Codex 命令执行策略。
- 文档改动至少运行格式或空白检查，例如 `git diff --check`。

**理由**:
多 agent 依赖文档传递上下文。过期文档会直接导致错误实现和错误验证。

---

### XII. Git 与交付治理

**原则声明**:

- Dirty workspace 默认视为风险，必须区分当前任务改动和用户已有改动。
- 禁止未经确认回滚、覆盖、重置或删除用户改动。
- 提交前必须查看 diff，并运行与交付声明直接相关的验证。
- 提交应保持主题清晰，避免把无关文件混入同一提交。
- 推送前必须确认当前分支、远程状态和本地未提交风险。

**理由**:
Git 是多 agent 协作的事实边界。清晰提交和保守操作可以保护用户已有工作。

---

### XIII. 模型与思考深度匹配

**原则声明**:

- 不同 agent 可以使用不同模型和思考深度，但必须与任务风险匹配。
- 架构设计、需求评审、复杂修复、安全评审、跨模块集成和最终验收应使用更强模型或更高思考深度。
- 机械整理、简单文档同步、格式修复、窄范围查询可以使用较低成本模型。
- 任务配置应记录 agent 角色、模型、思考深度、上下文来源和允许写入路径。

**理由**:
统一使用最高配置会浪费资源，统一使用最低配置会降低质量。按风险分配模型是可持续自动化的基础。

---

## 通用架构约束

每个项目必须明确以下内容，不能依赖 agent 猜测:

- 技术栈和运行时版本
- 包管理器和安装命令
- 本地开发、构建、测试、格式化、类型检查命令
- 环境变量模板和密钥获取方式
- 目录所有权和多 agent 写入边界
- artifacts、screenshots、logs、reports、trace 的保存位置
- API、数据模型、UI 页面和后台任务的契约来源
- 发布、回滚和故障处理方式

---

## 通用工作流

1. **需求接收**: 明确目标、范围、非目标、验收标准和风险。
2. **上下文收集**: 阅读项目规则、现有代码、文档、测试和历史决策。
3. **方案设计**: 输出架构、接口、任务拆分、验证计划和路径所有权。
4. **任务分发**: 主控为每个 agent 分配独立职责、目录和输出格式。
5. **实现执行**: Worker 在自己的边界内完成实现，不覆盖他人改动。
6. **阶段验证**: 运行对应测试、构建、截图、契约检查和文档检查。
7. **自动修复**: 将失败项转为 Repair Queue 并持续修复。
8. **主控合并**: 检查 diff、冲突、接口一致性、重复实现和证据完整性。
9. **最终验收**: 对照需求和验收标准确认完成度。
10. **交付归档**: 记录变更、验证证据、剩余风险和后续建议。

---

## 治理

### 宪章地位

本宪章是通用 agent 工程规则。项目专属规则可以补充或收紧本宪章，但不能削弱安全、验证、Git 保护和用户改动保护要求。

发生冲突时按以下顺序处理:

1. 用户当前明确指令
2. 项目根 `AGENTS.md`
3. 项目 `docs/`、`specs/`、`.specify/` 中的已批准规则
4. 本宪章和 `.codex/rules/*.md`
5. 通用默认实践

### 修订程序

1. 提出修订理由和影响范围。
2. 更新本文件和分发快照中的对应副本。
3. 检查是否需要同步 bootstrap、prompt 模板、doctor 检查或项目导入文档。
4. 运行文档检查。
5. 按语义化版本递增版本号。

### 版本控制

**Version**: 2.0.0 | **Ratified**: 2026-04-27 | **Last Amended**: 2026-04-27

---

## 附录: 通用验收清单

- [ ] 需求、非目标和验收标准已记录。
- [ ] 现有代码、成熟库或参考项目已优先调研。
- [ ] 多 agent 写入路径和职责边界已明确。
- [ ] 核心接口、数据模型和错误处理已定义。
- [ ] 单元、集成、契约、E2E 或视觉验证已按风险选择。
- [ ] UI 页面已保存实际浏览器截图，并与设计来源对比。
- [ ] 失败项已进入 Repair Queue 并重新验证。
- [ ] 文档、命令和示例与当前实现一致。
- [ ] 日志、trace 和截图不包含敏感信息。
- [ ] 提交前已检查 diff，并有 fresh verification evidence。
