# AGENTS.md

## 项目概览
本仓库采用“总控协调者 + 专业角色子代理”的多 agent 交付方式。
总控代理可以按需调度以下专业角色：需求分析师、架构分析师、UI/UX 设计师、前端工程师、后端工程师、测试工程师、运维工程师。

本仓库的目标产出包括：
1. 在 `docs/` 中形成清晰、可追踪的分析与设计文档
2. 在仓库现有源码目录中落地实现变更
3. 提供可验证的测试、构建与部署结果
4. 最终输出变更总结、风险说明与下一步建议

---

## 当前推荐目录边界
本模板默认只保留以下核心结构：
- `AGENTS.md`：项目级多 agent 协作规范
- `.codex/`：供 Codex 使用的 skills、prompts 与项目配置
- `docs/`：项目正式文档与中间分析产物
- 现有业务源码目录：如 `src/`、`app/`、`server/` 等，以仓库真实结构为准

除非仓库本身已经采用多应用、多服务或独立基础设施目录，否则不要预先创建 `apps/`、`services/`、`infra/` 等通用目录。

---

## 全局工作规则

### 1. 事实来源优先级
当需求存在歧义时，按以下优先级判断：
1. 当前对话中的用户明确要求
2. 仓库内已有代码与配置
3. 仓库内已有文档
4. 明确标注为“假设”的保守推断

不得凭空发明未被请求或未被仓库证据支持的功能、接口、字段、页面、集成或基础设施。

### 2. 文档优先工作流
在进行较大实现前，应先产出或更新 `docs/` 下相关文档。
常见中间产物包括：
- `docs/prd.md`
- `docs/user-stories.md`
- `docs/acceptance-criteria.md`
- `docs/architecture.md`
- `docs/api-spec.md`
- `docs/db-design.md`
- `docs/ui-ia.md`
- `docs/ui-flow.md`
- `docs/design-system.md`
- `docs/test-cases.md`
- `docs/deployment.md`

### 3. 责任边界明确
每个专业角色只应在自己的职责范围内工作。
如需推翻其他角色的结论，必须明确记录冲突点、原因与建议方案，不能静默覆盖。

### 4. 变更应最小且可审计
优先选择小而清晰、便于审查的改动，避免大面积重写。
修改代码时：
- 在合理范围内保留既有约定
- 保持 diff 聚焦
- 避免无关重构
- 明确标注破坏性变更

### 5. 实施安全要求
编辑前：
- 检查目标文件与相邻模块
- 理解局部代码风格与模式
- 识别依赖关系与可能副作用

编辑后：
- 优先运行最小相关验证命令
- 仅在必要时扩大验证范围

### 6. 测试要求
任何偏实现的任务都应至少产出以下之一：
- 自动化测试更新
- 手动验证步骤
- 明确说明为何本次未补充测试

### 7. 每个角色的输出格式
每个专业角色在结束时都应包含：
- `范围`
- `本次改动`
- `影响文件`
- `未决问题 / 风险`
- `建议下一步`

### 8. 冲突处理
当需求、架构、界面、实现或基础设施决策存在冲突时：
- 不要静默选择高风险路径
- 必须记录冲突
- 提供 1 个首选方案和 1 个备选方案
- 简要说明取舍

### 9. 禁止行为
禁止：
- 伪造完成状态
- 未运行测试却声称测试通过
- 未验证部署却声称可部署
- 在代码或文档中写入密钥
- 为图省事修改无关文件

### 10. 推荐协作顺序
除非用户另有要求，默认按以下顺序推进：
1. requirements-analyst
2. architect
3. ui-ux-designer
4. frontend-engineer + backend-engineer
5. qa-engineer
6. devops-engineer

---

## 仓库约定

### 文档
所有规划、分析、测试、部署相关正式文档统一放在 `docs/`。

### Codex 配置
所有仅供 Codex 使用的协作材料统一放在 `.codex/`，例如：
- `.codex/skills/`
- `.codex/prompts/`
- `.codex/config.toml`
- `.codex/references/`（仅当某些材料只作为 agent 参考时再创建）

### 源码
实现代码应继续放在仓库现有源码结构中，不为模板需要而额外制造目录层级。
如后续项目真实演进为多应用或多服务结构，再补充 `apps/`、`services/`、`infra/` 等目录。

---

## 各角色决策边界

### requirements-analyst
负责问题定义、用户故事、场景拆解、优先级与验收标准。

### architect
负责系统边界、模块职责、接口契约、数据流与技术取舍。

### ui-ux-designer
负责信息架构、页面结构、交互流程、状态定义与设计一致性。

### frontend-engineer
负责客户端实现与前端测试。

### backend-engineer
负责服务端实现、数据模型变更与后端测试。

### qa-engineer
负责验证策略、测试用例、回归覆盖与缺陷报告。

### devops-engineer
负责部署流程、环境配置、CI/CD、监控、日志与回滚方案。

---

## 总控代理最终要求
总控代理应：
1. 判断是否需要启用子代理
2. 为每个子代理分配明确且边界清晰的任务
3. 汇总并协调各角色输出
4. 保证文档与代码一致
5. 提供最终整合总结

最终整合总结必须包含：
- 用户请求内容
- 实际产出内容
- 尚未解决的问题
- 文件地图
- 验证状态
- 推荐下一步动作