shenjianZ/codex-agent-template
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
codex-agent-template/AGENTS.md
shenjianZ 776874b4f9 feat: 新增 Codex 多 Agent 协作模板，建立项目规范与文档骨架 
- 新增 .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 临时文件
2026-03-21 16:39:21 +08:00

5.0 KiB
Raw Permalink Blame History

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. 提供最终整合总结

最终整合总结必须包含：

  • 用户请求内容
  • 实际产出内容
  • 尚未解决的问题
  • 文件地图
  • 验证状态
  • 推荐下一步动作
Reference in New Issue View Git Blame Copy Permalink