Codex 多 Agent 模板仓库

这是一个适合放在 GitHub 上作为 Template Repository 使用的 Codex 多 agent 协作模板。

它提供：

• 项目级协作规范 AGENTS.md
• 多角色 skills 定义 .codex/skills/
• 总控提示词 .codex/prompts/orchestrator.md
• 面向需求、架构、设计、测试、部署的文档骨架 docs/

本模板适用于以下场景：

• 你想为一个新项目建立稳定的 Codex 协作方式
• 你想让需求、架构、设计、实现、测试、运维按统一流程推进
• 你希望把 agent 行为、项目文档、实现边界拆分清楚

仓库结构

.
├─ AGENTS.md
├─ .codex/
│  ├─ config.toml
│  ├─ prompts/
│  │  └─ orchestrator.md
│  └─ skills/
│     ├─ requirements-analyst/
│     ├─ architect/
│     ├─ ui-ux-designer/
│     ├─ frontend-engineer/
│     ├─ backend-engineer/
│     ├─ qa-engineer/
│     └─ devops-engineer/
└─ 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

目录边界说明

AGENTS.md

项目级规则入口。 用于约束总控代理与各角色子代理的职责、流程、冲突处理和最终输出格式。

.codex/

只放给 Codex 使用的内容：

• skills/：角色能力包
• prompts/：常用总控 prompt
• config.toml：项目级配置

如果后续有“只给 agent 参考、不作为正式项目文档”的材料，可以新增：

• .codex/references/

docs/

放项目正式文档和中间分析产物。 这些文档不仅给 agent 使用，也应作为团队协作与评审材料。

如何作为 GitHub 模板仓库使用

方式一：创建新项目

1. 将本仓库推到 GitHub。
2. 在 GitHub 仓库设置中启用 Template Repository。
3. 创建新项目时使用 Use this template。
4. 新项目创建后，根据实际项目技术栈补充源码目录，例如 src/、app/、server/。
5. 按项目实际需求修改 AGENTS.md、.codex/config.toml 和 docs/ 模板内容。

方式二：接入已有项目

1. 将本仓库中的以下内容复制到现有项目根目录：
   • AGENTS.md
   • .codex/
   • docs/
2. 删除与你现有项目冲突或重复的文档模板。
3. 在 AGENTS.md 中把“源码目录约定”改成你项目的实际结构。
4. 根据项目真实技术栈调整 .codex/config.toml。

推荐使用方式

1. 总控模式

把 .codex/prompts/orchestrator.md 作为总控提示词，再附加当前真实需求。

示例：

[读取 .codex/prompts/orchestrator.md 的内容]

用户需求：
请基于当前仓库，实现移动端工具工作台的图片压缩功能，包括：首页入口、压缩参数、结果预览、导出保存和错误处理。

2. 分阶段模式

如果你只想先做方案，可以要求总控先停在文档阶段，例如：

本次仅执行需求、架构和 UI/UX 阶段，不修改业务实现代码。

角色说明

当前模板内置 7 个角色：

• requirements-analyst：需求拆解、用户故事、验收标准
• architect：系统设计、接口规格、数据设计
• ui-ux-designer：信息架构、流程、设计规范
• frontend-engineer：前端实现与前端测试
• backend-engineer：后端实现与后端测试
• qa-engineer：测试用例、验证与缺陷报告
• devops-engineer：部署、环境、CI/CD、回滚与观测

建议的维护方式

• 将本仓库作为独立模板仓库维护，而不是发成 npm 包。
• 模板更新通过 GitHub PR 管理。
• 为关键版本打 Tag，方便不同项目固定模板版本。
• 当某个项目需要定制时，优先在项目内覆盖，不要反向污染模板主线。

不建议的做法

• 不建议把所有项目文档都塞进 .codex/
• 不建议为了模板预创建 apps/、services/、infra/ 等目录
• 不建议把这类协作模板当作运行时依赖发布到包管理器

后续可选增强

你可以在此模板基础上继续增加：

• .github/workflows/：模板自身的检查流程
• LICENSE：开源或团队内部协议
• CHANGELOG.md：模板版本变更记录
• .codex/references/：角色共享参考材料
• 更多角色 skills，例如数据分析、安全审计、产品运营