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
commit 776874b4f9
24 changed files with 1434 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,136 @@
+# 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，例如数据分析、安全审计、产品运营