# Codex 多 Agent 模板仓库

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

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

本模板适用于以下场景：
- 你想为一个新项目建立稳定的 Codex 协作方式
- 你想让需求、架构、设计、实现、测试、运维按统一流程推进
- 你希望把 agent 行为、项目文档、实现边界拆分清楚

## 仓库结构

```text
.
├─ 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) 作为总控提示词，再附加当前真实需求。

示例：

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

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

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

```text
本次仅执行需求、架构和 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，例如数据分析、安全审计、产品运营