shenjianZ
776874b4f9
- 新增 .codex/skills/ 目录，包含 7 个专业角色定义：
- requirements-analyst（需求分析师）
- architect（架构分析师）
- ui-ux-designer（UI/UX 设计师）
- frontend-engineer（前端工程师）
- backend-engineer（后端工程师）
- qa-engineer（测试工程师）
- devops-engineer（运维工程师）
- 新增总控协调代理配置：
- .codex/prompts/orchestrator.md：总控提示词与工作流定义
- .codex/config.toml：Codex 项目配置
- 新增项目级协作规范：
- AGENTS.md：定义多 agent 协作规则、角色边界与推荐工作流
- 新增完整文档骨架（docs/）：
- prd.md：产品需求文档模板
- user-stories.md：用户故事模板
- acceptance-criteria.md：验收标准模板
- architecture.md：架构设计模板
- api-spec.md：接口规格模板
- db-design.md：数据设计模板
- ui-ia.md：信息架构模板
- ui-flow.md：交互流程模板
- design-system.md：设计系统说明模板
- test-cases.md：测试用例模板
- deployment.md：部署说明模板
- README.md：文档目录说明
- 新增项目说明文档：
- README.md：模板仓库使用说明与推荐方式
- 配置 Git 忽略规则：
- .gitignore：覆盖常见开发环境产物与 Codex 临时文件
172 lines
5.0 KiB
Markdown
172 lines
5.0 KiB
Markdown
# 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. 提供最终整合总结
|
||
|
||
最终整合总结必须包含：
|
||
- 用户请求内容
|
||
- 实际产出内容
|
||
- 尚未解决的问题
|
||
- 文件地图
|
||
- 验证状态
|
||
- 推荐下一步动作
|