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 临时文件
137 lines
4.5 KiB
Markdown
137 lines
4.5 KiB
Markdown
# 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，例如数据分析、安全审计、产品运营
|