用Prompt模板：把Codex多Agent协作做成了“开箱即用”

Codex 多智能体提示词速查表

适用对象：希望在 Codex CLI/App 中，用“父线程 Orchestrator + 专家 subagents/custom agents”协同推进开发的团队。

这份文档不是把 Codex 变成一个自动流程引擎。它的作用是把长期规则、角色边界和常用提示词沉淀到仓库里，让父线程可以显式编排 subagents、检查产物、更新状态文件，并在需要时让人介入。

1. 基本原则

1.1 长期规则放仓库，短期目标放对话

长期规则建议放在：

• AGENTS.md
• .codex/config.toml
• .codex/agents/*.toml
• .agents/skills/*/SKILL.md
• docs/blackboard/state.yaml
• docs/codex/*.md

日常对话只补两件事：

• 这次要做什么
• 这次希望怎么调度

1.2 Codex 能自动做什么，不能自动做什么

Codex 会自动读取仓库中的 AGENTS.md 指令，并可按用户明确要求启动 subagents。项目级 custom agents 和 repo skills 也可以通过仓库文件配置。

Codex 不会自动执行以下事项：

• 自动读取或更新 docs/blackboard/state.yaml
• 自动按状态机推进阶段
• 自动执行 hard gates
• 自动保证 FE/BE 并行任务没有冲突
• 自动把 QA 失败路由回正确 owner

因此，父线程必须在 prompt 中显式要求：

• 读取 AGENTS.md 和 docs/blackboard/state.yaml
• 只 spawn 当前阶段需要的 agent
• 等待相关 agent 返回
• 检查产物和门禁
• 更新 blackboard
• 汇总下一步

1.3 推荐仓库落点

建议把本文保存为：

docs/codex/prompt-cheatsheet.md

也建议补充以下文档：

• docs/codex/agent-responsibilities.md
• docs/codex/blackboard-schema.md
• docs/codex/retry-policy.md
• docs/codex/worktree-playbook.md
• docs/codex/release-checklist.md

2. Codex 能力对齐说明

以下写法与当前 Codex CLI/App 能力对齐：

不要假设以下能力已经自动存在：

• 自动黑板锁
• 自动阶段流转
• 自动审批
• 自动冲突合并
• 自动回滚
• 自动选择最合适的 agent

3. 推荐工作流

3.1 父线程职责

父线程就是 Orchestrator。它负责：

• 读取仓库规则和 blackboard
• 决定是否需要 subagents
• 给每个 agent 分配清晰、独立、可验证的任务
• 等待 agent 返回
• 检查产物、测试结果和门禁
• 更新 docs/blackboard/state.yaml
• 决定下一阶段或请求人工介入

父线程不应该长期把所有工作都外包。紧急阻塞、需要全局判断、会影响多个模块的决策，通常由父线程自己处理。

3.2 角色分工

3.3 状态机

推荐状态：

intake -> prd -> architecture -> design -> implementation -> qa -> uat -> release

阶段说明：

3.4 Hard gates

以下是流程约束，不是 Codex 内建机制。父线程必须主动检查。

• FE/BE 进入实现前，必须已有足够明确的 contract 或父线程明确声明走 mock/prototype。
• 契约冻结后，FE/BE 不得静默修改 API contract。必须走 docs/architecture/change-requests/。
• QA 不能在没有实现产物时开始。
• UAT 不能在 QA 明确失败时开始。
• FE/BE 重试超过上限时，停止并请求人工介入。
• 并行任务必须先声明写入范围，避免多个 agent 改同一批文件。

3.5 Retry guard

建议默认：

max_retries:fe: 3be: 3qa: 2

达到上限后不要继续“再试一次”。父线程应输出：

• 已失败的命令或验收项
• 当前修改过的文件
• 失败归属
• 是否需要改 contract
• 建议的人类决策点

4. 推荐文件结构

AGENTS.md.codex/config.tomlagents/pm.tomlarchitect.tomldesigner.tomlfe.tomlbe.tomlqa.tomlgeneral.toml.agents/skills/prd-writer/SKILL.mdapi-contract/SKILL.mddesign-system/SKILL.mdqa-regression/SKILL.mdagents/openai.yamlrelease-docs/SKILL.mdagents/openai.yamldocs/blackboard/state.yamlprd/PRD.mdqa/UAT.mdqa/report.mdarchitecture/api.yamlarchitecture/schema.mdarchitecture/change-requests/design/tokens.jsondesign/interaction-notes.mdrelease/README.mdrelease/deploy.mdcodex/

5. 初始化项目用

用途：第一次把仓库配置成可协作的 Codex 多智能体项目。对已有生产仓库，建议先让 Codex 输出计划，确认后再写文件。

You are Codex. Configure this repository for a production-usable multi-agent collaborative development workflow.Important:- Do NOT implement product features.- Do NOT modify existing application code.- Only create or update setup/config/docs files needed for the workflow.- Preserve existing files. If a file already exists, inspect it and patch it minimally.- If a change is broad, first print a proposed file-change plan and wait for confirmation.Reality check:- Codex does not automatically execute a state machine.- Codex does not automatically read or write docs/blackboard/state.yaml.- The main Codex parent thread must explicitly orchestrate agents, enforce gates, and update the blackboard.- Subagents/custom agents are helpers, not autonomous workflow owners.Overall design:- The main Codex parent thread acts as the Orchestrator.- Do NOT create a separate orchestrator custom agent.- Create 7 project-scoped custom agents:1. pm2. architect3. designer4. fe5. be6. qa7. general- Create a single-writer blackboard file at docs/blackboard/state.yaml.- The parent thread is the only writer of docs/blackboard/state.yaml.- Child agents may read the blackboard, but they must not write it directly.- Child agents write their own artifacts. The parent thread summarizes results and updates the blackboard.First inspect the repository and infer:- monorepo or single app- package manager and workspace tool- frontend framework and main frontend directory- backend framework and main backend directory- database / ORM / migration tool- test runner(s), linter(s), formatter(s), and build commands- existing architecture, API, design, QA, release, or deployment docs to reuse- whether frontend/backend directories would benefit from nested AGENTS.override.md filesThen propose the exact files you will create or update.If the repo is small and the changes are only docs/config, proceed after printing the plan.If the repo is large or production-critical, stop and ask for confirmation before writing.Create or update these folders if missing:- .codex/- .codex/agents/- .agents/skills/- docs/blackboard/- docs/prd/- docs/architecture/- docs/architecture/change-requests/- docs/design/- docs/qa/- docs/release/- docs/codex/Create or update .codex/config.toml with safe defaults:- model = "gpt-5.5" only if this is the team's desired fixed model. Otherwise preserve the user's current/default model.- approval_policy = "on-request"- sandbox_mode = "workspace-write"- [agents]- max_threads = 6 or 8- max_depth = 1- [mcp_servers.openaiDeveloperDocs]- url = "https://developers.openai.com/mcp"Do not pretend app-only settings are complete in-repo.If a setup item requires manual Codex App action, document it in docs/codex/manual-steps.md.Examples:- trust the project so project-scoped config loads- review worktree usage- review internet allowlist or MCP access- optionally create recurring automationsCreate docs/blackboard/state.yaml with a machine-readable schema including:- phase- goal- ready_for- blocked_by- artifacts- contract_status- retries:febeqa- max_retries:febeqa- last_actor- last_updated- historyCreate or update root AGENTS.md.Keep it concise and policy-oriented.It must define:1. Main thread role- The main Codex thread is the Orchestrator.- It routes work, enforces gates, waits for specialists, and updates docs/blackboard/state.yaml.- It should avoid direct app code edits unless explicitly switching to single-agent mode or handling an emergency.2. State machine- intake- prd- architecture- design- implementation- qa- uat- release- fast_path for small scoped tasks3. Routing rules- PM owns PRD, stories, acceptance criteria, UAT, and final business acceptance.- Architect owns API contract, data design, integration notes, and technical blueprint.- Designer owns UI prompt, design tokens, component states, and interaction notes.- FE owns frontend implementation and frontend-relevant tests.- BE owns backend implementation, migrations, and backend-relevant tests.- QA owns lint, unit/integration verification, defect reports, and regression checks.- General owns docs, deployment notes, CI/CD notes, environment gotchas, and targeted research.4. Hard gates- FE/BE cannot start full implementation until contract artifacts exist or parent explicitly chooses prototype/mock mode.- After contract freeze, FE/BE must not silently edit the contract.- Contract changes after freeze must be proposed under docs/architecture/change-requests/.- QA cannot start until implementation artifacts exist.- UAT cannot start until QA passes.- If FE/BE/QA exceed retry limits, stop and request human intervention.5. Parallelism rules- Spawn subagents only when the user explicitly asks for agent/delegation/parallel work or the repo rules require it.- Parallel agents must have disjoint write scopes.- FE/BE parallel work should use worktrees when the change is large or likely to conflict.- Wait for all relevant agents, review outputs, then integrate.6. Artifact expectationsUse stack-appropriate names, but ensure there is a human-readable artifact for:- PRD- UAT- API contract- schema / data model- design tokens or design notes if UI is involved- QA report- release README / deployment notes7. Operational rules- Only the parent thread writes the blackboard.- Specialists keep changes minimal and avoid unrelated files.- Prefer repo files and artifacts over long conversational memory.- Use OpenAI developer documentation MCP first for OpenAI API, ChatGPT, Codex, Apps SDK, or MCP questions.- Keep internet usage least-privilege and document assumptions.- Close or stop using subagents once their task is done.Create these custom agent files under .codex/agents/:- pm.toml- architect.toml- designer.toml- fe.toml- be.toml- qa.toml- general.tomlEvery custom agent file must include:- name- description- developer_instructionsOptional fields may include:- sandbox_mode- approval_policy- model- reasoning_effortDo not rely on per-agent sandbox as a hard security boundary.Agent requirements:PM:- read-heavy and business-focused- reads PRD-related context first- creates or updates docs/prd/PRD.md and docs/qa/UAT.md- converts vague requests into user stories, acceptance criteria, edge cases, and non-goals- must not design APIs, choose schemas, or write app codeArchitect:- read-heavy and technically opinionated- reads PRD first- outputs docs/architecture/api.yaml or another stack-appropriate API contract- outputs docs/architecture/schema.md and, where appropriate, schema.sql or migration notes- outputs docs/architecture/folder-plan.md- owns contract freeze and change request review- must not implement app features unless explicitly asked during emergency modeDesigner:- read-heavy- reads PRD and architecture outputs- outputs docs/design/ui-prompt.md- outputs docs/design/tokens.json- outputs docs/design/interaction-notes.md- adapts design guidance to the detected frontend stack- must not implement app featuresFE:- implementation-focused- follows API contract and design artifacts- may use mock data only when parent thread allows prototype/mock mode- writes only frontend-relevant code and tests- avoids backend edits except tiny shared-type touchpoints approved by parent- reports contract issues instead of silently changing the contractBE:- implementation-focused- follows schema and API contract- writes only backend-relevant code, migrations, and tests- avoids frontend edits except tiny shared-type touchpoints approved by parent- reports contract issues instead of silently changing the contractQA:- quality gate- reads architecture artifacts before testing- runs lint, unit tests, integration checks, and smoke checks using actual repo tooling- writes docs/qa/report.md- records tests not run and why- when defects are found, reports owner, reproduction steps, failing command, likely files, and suggested next route- must not update the blackboard directlyGeneral:- cross-cutting support- handles README, deployment notes, CI/CD notes, environment gotchas, release docs, and targeted research- uses Docs MCP first for OpenAI/Codex-related questions- documents internet assumptions and sources- does not take over PM/Architect/FE/BE/QA work unless parent explicitly routes itCreate these repository skills under .agents/skills/:1. prd-writer2. api-contract3. design-system4. qa-regression5. release-docsFor each skill:- create a skill folder- add SKILL.md with frontmatter:---name: ...description: ...---- keep the skill focused on one job- use imperative instructions- specify inputs and outputs- prefer instruction-only unless deterministic scripting is truly usefulFor qa-regression and release-docs:- add agents/openai.yaml- set allow_implicit_invocation: falseIf the repo is clearly split by area, create nested AGENTS.override.md files close to specialized work.Use actual detected directories, not guessed names.Also create docs/codex/README.md explaining:- what this setup does- what it does not automate- where agents and skills live- what the blackboard file is- how the state machine works- how to start a new task with the parent Orchestrator- how to use worktrees for FE/BE parallelism- how retry guard works- how contract change requests work- how to recover from context lossAt the end:1. Print a concise repo detection summary.2. Print the file-change list.3. Call out assumptions.4. Call out manual steps.5. Do NOT start implementing product features.

6. 日常开发通用版

用途：正常做一个需求、功能或模块。

按仓库里的 Codex 多智能体规则处理这个需求。先读：- AGENTS.md- docs/blackboard/state.yaml需求：<写清楚目标、范围、预期效果、非目标>要求：- 先判断是否需要 subagents；不要为了流程而强行 spawn。- 只 spawn 当前阶段需要的 custom agent。- 如果需要并行，先声明每个 agent 的写入范围。- 每个阶段结束后，由父线程更新 docs/blackboard/state.yaml。- 每个阶段结束后输出：- 当前阶段- 已更新产物- 阻塞项- 门禁是否通过- 下一阶段- 契约冻结后，如遇 API/schema 问题，不允许 FE/BE 静默修改契约；必须走 architecture change request。- 如 FE/BE/QA 重试次数超过上限，停止并请求人工介入。

7. 小任务快速版

用途：小 bug、小文案、小范围修复，不值得启动完整流程。

这是一个小范围任务，优先走 fast_path。先读：- AGENTS.md任务：<你的任务>要求：- 尽量由父线程直接完成。- 只有在确实有价值时，才 spawn 1 到 2 个最相关的 agent。- 不要启动完整状态机。- 不要创建不必要的 PRD、架构或设计文档。- 最小化修改。输出：- 是否使用了 agent，以及为什么- 改了哪些文件- 跑了哪些验证- 未跑哪些验证以及原因- 是否需要 QA 或 PM 补一个最小检查

8. 强制走完整流程版

用途：重要需求，必须完整经过门禁。

这次任务必须严格走完整多智能体流程，不允许跳步。先读：- AGENTS.md- docs/blackboard/state.yaml任务：<你的需求>强制流程：1. PM 明确 PRD / 用户故事 / 验收标准 / 非目标2. Architect 输出 API contract、数据设计和 folder plan3. 如果涉及 UI，Designer 输出 design tokens、组件状态和交互说明4. 父线程检查 contract 是否可冻结5. FE / BE 在写入范围明确后并行或顺序开发6. QA 执行 lint / unit / integration / smoke checks7. PM 在 QA 通过后做业务验收8. General 更新 README / 部署说明 / 交接文档要求：- 每一步都必须先等待上一门禁完成。- 每一步都要汇总结果、产物、阻塞和门禁状态。- 子 agent 不得直接更新 docs/blackboard/state.yaml。- 父线程在每一步结束后更新 blackboard。

9. 只跑 PRD / 架构版

用途：先把需求和技术蓝图做出来，不写业务代码。

这次先不要进入实现阶段。先读：- AGENTS.md- docs/blackboard/state.yaml任务：<你的需求>只允许 spawn：- pm- architect- 如果涉及 UI，再 spawn designer目标：- 输出或更新 PRD- 输出或更新 UAT 草案- 输出或更新 API contract- 输出或更新 schema / data model- 如果需要，输出 design tokens 和 interaction notes不要启动 FE、BE、QA。最后汇总：- 已产出的文档- 尚缺的决策- 进入 implementation 前的门禁条件

10. 只跑 FE / BE 实现版

用途：PRD 和 contract 已经基本确定，只推进实现。

需求与契约已经基本确定。先读：- AGENTS.md- docs/blackboard/state.yaml- docs/prd/PRD.md- docs/architecture/api.yaml（如果存在）- docs/architecture/schema.md 或 schema.sql（如果存在）- docs/design/tokens.json（如果存在）任务：<你的需求>只 spawn 需要的实现 agent：- fe- be要求：- 严格遵守现有 API contract 和 schema。- 不要擅自改 contract。- 最小化修改。- 如果发现 contract 不合理，提交 docs/architecture/change-requests/.md，不要直接改。- 如果并行执行，先声明 FE 和 BE 的写入范围。- 完成后输出：- 改动摘要- 涉及文件- 验证结果- 是否建议进入 QA

11. 强制并行 FE / BE 版

用途：明确希望前后端并行推进。

请按并行开发模式处理这次任务。先读：- AGENTS.md- docs/blackboard/state.yaml- docs/architecture/api.yaml- docs/architecture/schema.md 或 schema.sql- docs/design/tokens.json（如果存在）任务：<你的需求>要求：- 只有在 contract 已存在或父线程明确允许 prototype/mock mode 时才并行。- 同时 spawn fe 和 be custom agents。- 明确 FE 的写入范围。- 明确 BE 的写入范围。- 二者都必须遵守现有 contract。- 不允许任一方静默修改 contract。- 若发现 contract 问题，提交 change request。- 等待双方都返回后，父线程统一审查、整合和更新 blackboard。输出：- FE 进度- BE 进度- 冲突或重叠文件- contract 是否需要变更- 验证结果- 是否进入 QA

12. 只跑 QA 回归版

用途：代码已经完成，让 QA 专注验收和打回。

这次只做质量检查，不做需求拆解。先读：- AGENTS.md- docs/blackboard/state.yaml- docs/architecture/api.yaml（如果存在）- docs/qa/UAT.md（如果存在）只 spawn qa。任务：请基于当前仓库状态执行：- lint- unit tests- integration checks- 关键路径 smoke checks- 如果是前端应用，必要时做浏览器验证要求：- 输出 docs/qa/report.md。- 如果有命令无法运行，记录原因。- 如果失败，按 owner 分类：- FE- BE- Shared / Architecture- Environment / Tooling- 每个问题给出：- 复现步骤- 失败命令- 可能相关文件- 建议下一跳路由- QA 不要直接修改 docs/blackboard/state.yaml。

13. QA 失败后定向打回 FE

用途：只修前端缺陷，不重新启动全流程。

QA 已发现问题，这次只处理前端相关缺陷。先读：- AGENTS.md- docs/blackboard/state.yaml- docs/qa/report.md只 spawn fe。任务：修复 docs/qa/report.md 中归属于 FE 的问题。要求：- 仅修复 FE owner 的问题。- 不要擅自修改后端或 API contract。- 如果必须改 shared types，先说明原因。- 最小化修改。- 修复后运行前端相关验证。输出：- 修复了哪些问题- 改了哪些文件- 仍被阻塞的问题- 验证结果- 是否建议重新进入 QA

14. QA 失败后定向打回 BE

用途：只修后端缺陷。

QA 已发现问题，这次只处理后端相关缺陷。先读：- AGENTS.md- docs/blackboard/state.yaml- docs/qa/report.md只 spawn be。任务：修复 docs/qa/report.md 中归属于 BE 的问题。要求：- 仅修复 BE owner 的问题。- 不要擅自修改前端或 API contract。- 如果必须改 shared types，先说明原因。- 最小化修改。- 修复后运行后端相关验证。输出：- 修复了哪些问题- 改了哪些文件- 仍被阻塞的问题- 验证结果- 是否建议重新进入 QA

15. 只做 README / 交接 / 部署文档版

用途：开发差不多了，只让 General 收尾。

这次只做收尾文档，不做功能实现。先读：- AGENTS.md- docs/blackboard/state.yaml- docs/prd/PRD.md（如果存在）- docs/architecture/api.yaml（如果存在）- docs/qa/report.md（如果存在）只 spawn general。任务：更新或生成：- README- 部署说明- 环境变量说明- CI/CD 交接说明- 已知限制与排障说明要求：- 以当前项目实际状态为准。- 不要编造不存在的脚本、服务、环境变量或流程。- 如果发现缺信息，写入 manual steps 或 open questions。输出：- 更新了哪些文档- 依据了哪些现有文件- 还缺哪些人工步骤

16. OpenAI / Codex / 第三方 API 调研版

用途：做调研，不顺手改业务代码。

这次是调研任务，不是实现任务。先读：- AGENTS.md- docs/blackboard/state.yaml（如果存在）只 spawn general，或由父线程直接完成。如果问题涉及 OpenAI、Codex、ChatGPT、Apps SDK、MCP，优先使用 OpenAI developer docs MCP sources。如果 MCP 不可用，只使用官方 OpenAI 文档作为替代来源，并说明限制。调研问题：<你的问题>输出要求：- 结论- 推荐方案- 风险点- 需要验证的假设- 如果落地到本仓库，需要改哪些文件- 不要直接开始实现

17. Hotfix 紧急修复版

用途：线上问题、阻塞问题、需要快速修复但仍要可审计。

这是 hotfix 任务，优先恢复正确行为，避免启动完整流程。先读：- AGENTS.md- docs/blackboard/state.yaml（如果存在）- docs/qa/report.md（如果相关）问题：<线上现象、影响范围、复现路径、期望行为>要求：- 先复现或定位最小失败点。- 只修改修复所必需的文件。- 不做无关重构。- 如需临时绕过，明确标注风险和回收计划。- 运行最小但足够的验证。- 更新 docs/release/hotfix-notes.md 或对应发布记录。输出：- 根因判断- 修复摘要- 涉及文件- 验证命令和结果- 剩余风险- 是否需要后续正式补测或架构修正

18. Rollback 回滚版

用途：需要撤回某次改动、版本或迁移。

这是 rollback 任务。目标是安全恢复到指定状态。先读：- AGENTS.md- docs/blackboard/state.yaml（如果存在）- docs/release/README.md 或 release notes（如果存在）回滚目标：<要回滚的 commit / feature / release / migration / config>要求：- 先识别回滚范围和依赖。- 不要使用 destructive git commands，除非用户明确授权。- 如果涉及数据库迁移，先说明数据风险和备份要求。- 如果涉及部署配置，列出人工确认项。- 优先给出可审查的 patch 或步骤。输出：- 回滚范围- 风险点- 执行步骤- 验证步骤- 是否需要人工审批

19. Agent 冲突仲裁版

用途：FE/BE/Architect/QA 对 contract、实现范围或缺陷归属产生冲突。

当前出现 agent 间冲突。先暂停相关实现，不要继续扩大改动。先读：- AGENTS.md- docs/blackboard/state.yaml- 冲突相关产物或 QA report冲突描述：<描述冲突双方、争议点、相关文件或失败命令>要求：- 父线程先整理事实，不直接选边。- 如冲突涉及 API/schema，spawn architect 做技术裁决。- 如冲突涉及业务验收，spawn pm 做业务裁决。- 如冲突涉及 UI 行为，spawn designer 做交互裁决。- 裁决写入 docs/architecture/change-requests/ 或相应决策记录。- 裁决前 FE/BE 不得继续改 contract。输出：- 冲突事实- 决策 owner- 裁决结论- 需要修改的产物- 下一跳 agent

20. 上下文恢复版

用途：上下文压缩、长线程中断、换线程继续、或怀疑 Codex 忘了前文。

这次先做上下文恢复，不要立即改代码。请依次读取：- AGENTS.md- docs/blackboard/state.yaml（如果存在）- 最近更新的 docs/prd、docs/architecture、docs/design、docs/qa、docs/release 产物- git status / git diff（如当前是 git 仓库）要求：- 重建当前阶段、目标、阻塞项和最近改动。- 不要覆盖用户或其他 agent 的未提交修改。- 如果发现 blackboard 过期，先汇报差异，再由父线程更新。输出：- 当前阶段判断- 最近产物- 当前未提交改动摘要- 风险或冲突- 建议下一步

21. 并行结果整合版

用途：FE/BE 或多个 worker 已返回，需要父线程整合。

请整合已完成的并行 agent 工作。先读：- AGENTS.md- docs/blackboard/state.yaml- 每个 agent 的最终汇报- git status / git diff要求：- 不要盲目信任 agent 汇报，抽查关键文件。- 检查是否有重叠修改或冲突。- 检查 contract 是否被静默修改。- 运行必要验证。- 更新 docs/blackboard/state.yaml。输出：- 每个 agent 的贡献- 冲突或重叠文件- 需要修正的地方- 验证结果- 下一阶段

22. 父线程最短启动句

用途：平时最省事的版本。

按仓库里的 Codex 多智能体规则处理这个需求：<你的需求>先读 AGENTS.md 和 docs/blackboard/state.yaml。只 spawn 必要的 agent。在每个阶段结束后，由父线程汇总当前状态、已更新产物、阻塞项、门禁状态和下一阶段，并更新 blackboard。

23. 推荐使用顺序

最常用三条：

1. 日常开发通用版
2. 小任务快速版
3. 只跑 QA 回归版

标准开发节奏：

1. 初始化项目用（首次）
2. 日常开发通用版
3. 如遇到返工，使用定向打回 FE/BE
4. 并行工作完成后，使用并行结果整合版
5. 临近发版，使用 QA 回归版和 release/docs 模板
6. 线上问题，使用 Hotfix 或 Rollback 模板

24. 团队约定建议

建议写入团队协作规范：

1. 大任务默认从本文复制提示词，小任务允许 fast_path。
2. 父线程负责更新 blackboard，子 agent 不直接写。
3. 契约冻结后，变更必须走 docs/architecture/change-requests/。
4. 并行 agent 必须先声明写入范围。
5. QA 失败要按 owner 打回，不要默认重启全流程。
6. retry 超过阈值时停止，交给人判断。
7. 上下文丢失或换线程时，先跑上下文恢复版。
8. 不把 per-agent sandbox 当成安全隔离。

25. 维护说明

以下情况应更新本文：

• Codex subagents/custom agents 能力变化
• Codex config 字段变化
• 团队角色或目录结构变化
• 状态机阶段变化
• blackboard 字段变化
• QA / 发布流程调整
• 某条提示词经常误导 Codex

26. 一句话总结

这份文档的目标不是让 Codex 自动接管整个研发流程，而是让父线程有一套稳定的编排手册：规则放仓库，任务写清楚，agent 少而准，产物可审计，遇到冲突及时停下来让人或 owner 做决定。