用 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 推荐仓库落点

建议把本文保存为：

text 复制代码

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 能力对齐：

项目	是否建议使用	说明
`AGENTS.md`	是	Codex 会自动发现并注入上下文。保持简短，避免超过上下文预算。
`.codex/config.toml`	是	支持项目级配置。项目需要被信任后才会加载。
`.codex/agents/*.toml`	是	支持项目级 custom agents。每个 agent 至少包含 `name`、`description`、`developer_instructions`。
`.agents/skills/*/SKILL.md`	是	支持 repo skills。适合沉淀可复用流程。
`.agents/skills/*/agents/openai.yaml`	是	可配置 skill 是否允许 implicit invocation。
`docs/blackboard/state.yaml`	可用但非原生	只是约定文件。Codex 不会自动读写，必须由父线程显式维护。
`[agents] max_threads = 8`	可用	控制 subagents 并发上限。建议从 4 到 8 开始，不要盲目拉满。
`[agents] max_depth = 1`	可用	建议保持 1，避免 subagents 再派生 subagents。
`[mcp_servers.openaiDeveloperDocs] url = "https://developers.openai.com/mcp"`	可用	适合 OpenAI/Codex/API 文档查询。需要项目信任和网络/MCP 可用。
"并行 spawn fe 和 be"	可用但需显式	只有用户明确要求并行或 delegation 时才应 spawn。并行任务要拆分清楚写入范围。
per-agent `sandbox_mode`	可用但不是安全边界	custom agent 可声明默认 sandbox，但运行时仍受父线程和会话权限影响。

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

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

3. 推荐工作流

3.1 父线程职责

父线程就是 Orchestrator。它负责：

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

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

3.2 角色分工

角色	主要职责	不应负责
PM	PRD、用户故事、验收标准、UAT、业务验收	API 设计、数据模型、代码实现
Architect	API contract、数据模型、集成方案、目录计划、技术裁决	业务验收、具体功能实现
Designer	UI prompt、design tokens、组件状态、交互说明	直接实现功能
FE	前端实现、前端测试、前端缺陷修复	后端实现、静默修改 API 契约
BE	后端实现、迁移、后端测试、后端缺陷修复	前端实现、静默修改 UI 行为
QA	lint、unit/integration/e2e、回归报告、缺陷归属	黑板更新、无授权大范围重构
General	README、部署文档、CI/CD 交接、环境说明、调研	接管已有明确 owner 的工作

3.3 状态机

推荐状态：

text 复制代码

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

阶段说明：

阶段	进入条件	退出条件	可跳过条件
intake	用户提出需求	范围、目标、风险基本明确	小任务可以合并到 implementation
prd	需求不够明确或影响业务流程	PRD/UAT 草案完成	小 bug、纯技术债可跳过
architecture	涉及 API、数据、集成、跨模块行为	API/data/folder plan 明确	纯文案、纯样式小改可跳过
design	涉及 UI/交互/视觉规范	tokens、states、interaction notes 明确	后端任务或 CLI 工具可跳过
implementation	契约和范围足够明确	FE/BE 或相关实现完成	只做文档/调研可跳过
qa	有实现产物需要验证	QA report 明确 pass/fail	只做 PRD/调研可跳过
uat	QA 通过且需要业务验收	PM 给出业务验收结论	内部技术任务可跳过
release	准备合入、部署或交接	README/deploy/release notes 完成	实验性本地任务可跳过

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

建议默认：

yaml 复制代码

max_retries:
  fe: 3
  be: 3
  qa: 2

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

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

4. 推荐文件结构

text 复制代码

AGENTS.md
.codex/
  config.toml
  agents/
    pm.toml
    architect.toml
    designer.toml
    fe.toml
    be.toml
    qa.toml
    general.toml
.agents/
  skills/
    prd-writer/
      SKILL.md
    api-contract/
      SKILL.md
    design-system/
      SKILL.md
    qa-regression/
      SKILL.md
      agents/openai.yaml
    release-docs/
      SKILL.md
      agents/openai.yaml
docs/
  blackboard/state.yaml
  prd/PRD.md
  qa/UAT.md
  qa/report.md
  architecture/api.yaml
  architecture/schema.md
  architecture/change-requests/
  design/tokens.json
  design/interaction-notes.md
  release/README.md
  release/deploy.md
  codex/

5. 初始化项目用

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

text 复制代码

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. pm
  2. architect
  3. designer
  4. fe
  5. be
  6. qa
  7. 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 files

Then 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 automations

Create docs/blackboard/state.yaml with a machine-readable schema including:
- phase
- goal
- ready_for
- blocked_by
- artifacts
- contract_status
- retries:
    fe
    be
    qa
- max_retries:
    fe
    be
    qa
- last_actor
- last_updated
- history

Create 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 tasks

3. 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 expectations
Use 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 notes

7. 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.toml

Every custom agent file must include:
- name
- description
- developer_instructions

Optional fields may include:
- sandbox_mode
- approval_policy
- model
- reasoning_effort

Do 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 code

Architect:
- 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 mode

Designer:
- 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 features

FE:
- 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 contract

BE:
- 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 contract

QA:
- 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 directly

General:
- 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 it

Create these repository skills under .agents/skills/:
1. prd-writer
2. api-contract
3. design-system
4. qa-regression
5. release-docs

For 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 useful

For qa-regression and release-docs:
- add agents/openai.yaml
- set allow_implicit_invocation: false

If 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 loss

At 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. 日常开发通用版

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

text 复制代码

按仓库里的 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、小文案、小范围修复，不值得启动完整流程。

text 复制代码

这是一个小范围任务，优先走 fast_path。

先读：
- AGENTS.md

任务：
<你的任务>

要求：
- 尽量由父线程直接完成。
- 只有在确实有价值时，才 spawn 1 到 2 个最相关的 agent。
- 不要启动完整状态机。
- 不要创建不必要的 PRD、架构或设计文档。
- 最小化修改。

输出：
- 是否使用了 agent，以及为什么
- 改了哪些文件
- 跑了哪些验证
- 未跑哪些验证以及原因
- 是否需要 QA 或 PM 补一个最小检查

8. 强制走完整流程版

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

text 复制代码

这次任务必须严格走完整多智能体流程，不允许跳步。

先读：
- AGENTS.md
- docs/blackboard/state.yaml

任务：
<你的需求>

强制流程：
1. PM 明确 PRD / 用户故事 / 验收标准 / 非目标
2. Architect 输出 API contract、数据设计和 folder plan
3. 如果涉及 UI，Designer 输出 design tokens、组件状态和交互说明
4. 父线程检查 contract 是否可冻结
5. FE / BE 在写入范围明确后并行或顺序开发
6. QA 执行 lint / unit / integration / smoke checks
7. PM 在 QA 通过后做业务验收
8. General 更新 README / 部署说明 / 交接文档

要求：
- 每一步都必须先等待上一门禁完成。
- 每一步都要汇总结果、产物、阻塞和门禁状态。
- 子 agent 不得直接更新 docs/blackboard/state.yaml。
- 父线程在每一步结束后更新 blackboard。

9. 只跑 PRD / 架构版

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

text 复制代码

这次先不要进入实现阶段。

先读：
- 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 已经基本确定，只推进实现。

text 复制代码

需求与契约已经基本确定。

先读：
- 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/<short-name>.md，不要直接改。
- 如果并行执行，先声明 FE 和 BE 的写入范围。
- 完成后输出：
  - 改动摘要
  - 涉及文件
  - 验证结果
  - 是否建议进入 QA

11. 强制并行 FE / BE 版

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

text 复制代码

请按并行开发模式处理这次任务。

先读：
- 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 专注验收和打回。

text 复制代码

这次只做质量检查，不做需求拆解。

先读：
- 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

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

text 复制代码

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

用途：只修后端缺陷。

text 复制代码

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 收尾。

text 复制代码

这次只做收尾文档，不做功能实现。

先读：
- 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 调研版

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

text 复制代码

这次是调研任务，不是实现任务。

先读：
- AGENTS.md
- docs/blackboard/state.yaml（如果存在）

只 spawn general，或由父线程直接完成。
如果问题涉及 OpenAI、Codex、ChatGPT、Apps SDK、MCP，优先使用 OpenAI developer docs MCP sources。
如果 MCP 不可用，只使用官方 OpenAI 文档作为替代来源，并说明限制。

调研问题：
<你的问题>

输出要求：
- 结论
- 推荐方案
- 风险点
- 需要验证的假设
- 如果落地到本仓库，需要改哪些文件
- 不要直接开始实现

17. Hotfix 紧急修复版

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

text 复制代码

这是 hotfix 任务，优先恢复正确行为，避免启动完整流程。

先读：
- AGENTS.md
- docs/blackboard/state.yaml（如果存在）
- docs/qa/report.md（如果相关）

问题：
<线上现象、影响范围、复现路径、期望行为>

要求：
- 先复现或定位最小失败点。
- 只修改修复所必需的文件。
- 不做无关重构。
- 如需临时绕过，明确标注风险和回收计划。
- 运行最小但足够的验证。
- 更新 docs/release/hotfix-notes.md 或对应发布记录。

输出：
- 根因判断
- 修复摘要
- 涉及文件
- 验证命令和结果
- 剩余风险
- 是否需要后续正式补测或架构修正

18. Rollback 回滚版

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

text 复制代码

这是 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、实现范围或缺陷归属产生冲突。

text 复制代码

当前出现 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 忘了前文。

text 复制代码

这次先做上下文恢复，不要立即改代码。

请依次读取：
- 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 已返回，需要父线程整合。

text 复制代码

请整合已完成的并行 agent 工作。

先读：
- AGENTS.md
- docs/blackboard/state.yaml
- 每个 agent 的最终汇报
- git status / git diff

要求：
- 不要盲目信任 agent 汇报，抽查关键文件。
- 检查是否有重叠修改或冲突。
- 检查 contract 是否被静默修改。
- 运行必要验证。
- 更新 docs/blackboard/state.yaml。

输出：
- 每个 agent 的贡献
- 冲突或重叠文件
- 需要修正的地方
- 验证结果
- 下一阶段

22. 父线程最短启动句

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

text 复制代码

按仓库里的 Codex 多智能体规则处理这个需求：
<你的需求>

先读 AGENTS.md 和 docs/blackboard/state.yaml。
只 spawn 必要的 agent。
在每个阶段结束后，由父线程汇总当前状态、已更新产物、阻塞项、门禁状态和下一阶段，并更新 blackboard。

23. 推荐使用顺序

最常用三条：

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

标准开发节奏：

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

24. 团队约定建议

建议写入团队协作规范：

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

25. 维护说明

以下情况应更新本文：

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

26. 一句话总结

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