企业官网建设流程全解析

• AI 技能
• AI 插件

在 AAS（agentic-awesome-skills）仓库的codex-delegate技能中，编排者（orchestrator）把有界编码任务委派给独立的 OpenAI Codex CLI 实现者（implementer），再自行审查并提交。整个闭环的前提是一份高质量 brief——它是 Codex 唯一能看到的任务输入。本指南以 writing-the-brief.md 为骨架，结合同技能下的 SKILL.md、dispatch-and-poll.md 与 review-and-land.md 展开。读完你将掌握：Codex 的"盲执行"上下文模型、四块 XML 骨架的写法、按任务类型选配扩展块、真实门禁（gate）命令的发现方法，以及一份可直接套用的完整 brief 示例。

认识盲执行的 Codex：brief 就是全部上下文

编写 brief 的第一个前提是理解 Codex 的执行环境。根据 writing-the-brief.md 的描述：Codex 运行在一个全新的进程中，没有你对话的记忆、没有你此前笔记的访问权、没有任何共享上下文——它只能看到你发送的文本，以及它能从工作树（working tree）中读取的内容，包括仓库自带的AGENTS.md（Codex 会自动读取它）。

由此推出一个核心结论："如果某个约束没有写进 brief，也不在仓库里可发现，那对 Codex 而言它就不存在。"文档明确指出，委派失败最常见的原因就是 "brief 假定了 Codex 并不拥有的上下文"（a brief that assumes context Codex doesn't have）。因此在撰写时，目标、当前状态、要改什么、不要碰什么、用什么命令验证，都必须完整落进文本。

这一定位也解释了为什么本技能把编排闭环设计成 "brief → dispatch → poll → review → commit"：实现者只负责在隔离沙箱里打字，验证与落地责任始终属于编排者。技能在 SKILL.md 的 Limitations 中明确写着 "Relay never commits — it only returns structured result JSON; you review and land the commit"，即 relay 只返回结构化的result.json，提交动作由编排者完成——brief 中的action_safety块正是为此服务的。

有效的形状：紧凑的分块 XML 结构

Codex 对紧凑、块状结构的提示词响应最佳——使用 XML 标签而非长段落散文。文档给出的核心原则是：陈述任务、定义"完成"的样子、规定默认行为方式，以及列出真正要紧的少数约束；只有当任务确实需要时才增加块，不要为了仪式感堆砌空块（"don't ship empty ceremony"）。

四块骨架：覆盖绝大多数实现类任务

文档提供了以下可直接复制的骨架模板：

<task> One or two sentences: the concrete job and where it lives. Then the specifics — current state, what to change, and explicitly what to leave untouched. The "leave untouched" list is what keeps Codex from wandering into unrelated refactors. </task> <verification_loop> Run these before finishing and fix anything they surface, don't just report it: <the project's real test command> <the project's real lint/format command> <the project's real build/typecheck command> Confirm the working tree shows only the intended changes afterward. </verification_loop> <action_safety> Keep changes scoped to the task. No unrelated refactors, renames, or cleanup unless required for correctness. Do NOT run git add or git commit — you cannot reliably write .git, and the orchestrator commits after reviewing. Leave the work uncommitted in the working tree. </action_safety> <structured_output_contract> End with a report in this exact shape: 1. What changed and why 2. Files touched 3. Gate outcomes (paste the test/lint counts) 4. Anything you deviated on, left open, or want a decision on </structured_output_contract>

四个块各自的职责：

这个骨架之所以有效，是因为它在 prompt 层面把"做什么、怎样算完成、不许做什么、如何汇报"四件事全部显式化，杜绝了 Codex 对隐含约定的猜测。

按任务画像选配的扩展块

四块骨架覆盖大多数实现任务；当任务画像不同时，文档建议按需追加（不是全部都要）：

• 调试 / 开放式修复：追加<completeness_contract>（彻底解决，不要在第一个貌似合理的修复处就停）与<missing_context_gating>（不要猜测缺失的仓库事实；要么找到它们，要么明确说明哪些未知）。
• 审查 / 诊断（只读）：追加<grounding_rules>（每个论断都必须有证据支撑，并标注推断）——配合--read-only运行，使 Codex 无法编辑任何文件。
• 研究 / 建议：追加<research_mode>（把观察到的事实、推断、悬而未决的问题分开呈现）。

从源码结构看，这些扩展块对应着不同的委派模式：--read-only在 relay 中即--sandbox read-only的快捷方式（见 dispatch-and-poll.md），适用于审查类任务；而只读模式也被 SKILL.md 用于获取"对抗性第二意见"（adversarial second opinion）——列出双方立场，请 Codex 逐点辩护或让步，全程不触碰文件。

发现真实门禁：不要硬编码命令

<verification_loop>只有在写入了项目实际命令时才有价值。文档给出的做法是：先读仓库的CLAUDE.md/AGENTS.md/Makefile/package.json，把真实的命令抄进去——make test、npm run lint、cargo test、pytest -q，项目用什么就写什么。

这是一个容易被低估的失败点：brief 只写 "run the tests" 而不指名命令，得到的往往是 Codex 的猜测——或者干脆跳过。门禁命令是编排者后续审查的验证基准，这一点在 review-and-land.md 中被反复强调：result.json里 Codex 自带的门禁通过声明只能视为"主张"而非"证据"，编排者必须在工作树中亲自重跑这些 test / lint / build 命令并阅读输出。

尊重仓库约定：AGENTS.md 之外的关键禁令要复述

Codex 会自动读取仓库的AGENTS.md，因此其中的家规（代码风格、禁止模式、提交约定）天然生效。但文档特别提醒：如果项目在代码中禁止某些东西——比如注释里的 spec/ticket ID、"MVP"/"for now"/"phase N" 这类过程语言、特定的测试约定，以及仓库自己的约定所禁止的一切——把其中承重（load-bearing）的条款在 brief 里再复述一遍。原因是 Codex 的合规程度只取决于它眼前有什么：只存在于 AGENTS.md 深处的规则，不如 brief 内显式重申的规则可靠。

注意这里有个顺序问题：AGENTS.md 是"自动生效的底线"，brief 复述是"针对本次任务的强化"。两者不冲突，但复述应当只挑承重条款，而不是把整个 AGENTS.md 抄进 brief——否则又违背了"紧凑、无空仪式"的原则。

一个 brief 一个任务：保持边界清晰

文档对任务粒度给出了硬性要求：每个 brief 只装一个单一、有界的任务。像 "Review this, fix what you find, update the docs, and suggest a roadmap" 这种多动词拼盘会产生一团混乱的 run，应当拆分成多次独立派发。

"One brief → one Codex run → one commit" 带来三个可验证的好处：

• 审查与回滚都干净——单个步骤可以独立回退；
• 后续任务可以安全地假设前一个任务已经落地（brief 里可以写 "the X added in the previous step exists"）；
• 每次审查都是诚实的——派发前工作树干净，touchedFiles只会显示本次任务的改动，而不是前面任务的堆积。

这个"串行、每任务一提交"的纪律在 multi-task-queues.md 中被推广为队列运行的标准姿势：按依赖顺序一次跑一个任务，每个任务完成"审查 + 门禁 + 提交"后再派发下一个，并把后续任务依赖的前置事实折进该任务的 brief（Codex 对早先的 run 没有记忆，任务 2 冒出的约束必须写进任务 5 的 brief 才有效）。

派发时冻结前提：中途无法转向

brief 发出后，实现者会从 brief 的事实出发执行，而运行中途不存在转向通道（no steering channel mid-run）。文档因此在派发前给出一个硬性动作：审计事实块——ownership、目标分支、约束，以及任何判断决策所依赖的要素。

如果 run 进行中才发现某个前提是错误的，正确的做法不是事后给输出打折，而是：

1. 停止该 run；
2. 重新派发一份修正过的 brief；
3. 对于可写（write-capable）的 run，先检查工作树，调和任何部分完成或受污染前提影响的编辑——决定保留还是回退——然后再重新派发。

这与此技能的总体定位一致：实现者在沙箱里产出，编排者对工作树拥有最终解释权。事实上 dispatch-and-poll.md 进一步说明，relay 把result.json与事件日志events.jsonl写入临时目录，正是为了让"待审查的仓库"保持干净，使touchedFiles报告只反映 Codex 自身的编辑。

预期回复中的环境前缀噪音

Codex 的最终消息可能在你要的报告之上携带环境噪音——比如仓库AGENTS.md注入的横幅、你配置的 MCP 工具或扩展追加的文本等。文档明确指出：这些来自你自己的 Codex 配置，不是 relay 的缺陷。

应对手段正是<structured_output_contract>：要求一个清晰分隔的报告区段，这样无论外面包裹了什么，你都能定位到真正的输出。这与 relay 的行为衔接良好——dispatch-and-poll.md 说明result.json的finalMessage字段承载的就是 Codex 的最终报告（即你在<structured_output_contract>里要求的那份），并且会完整打印在 stdout 的报告标记之间。

完整工作示例：退款幂等性修复

文档末尾给出了一份可直接发送的完整 brief，这里完整保留，并附上每块的落地说明：

<task> In the payments service at services/billing/, the refund path double-charges when a refund is retried after a network timeout (the idempotency key isn't checked before re-submitting). Make the refund submission idempotent: check for an existing refund by idempotency key before creating a new one. Touch only services/billing/refund.py and its tests. Leave the charge path, the API routes, and the data models untouched. </task> <verification_loop> Run and make green before finishing: pytest tests/billing/ -q ruff check services/billing/ Confirm git status shows only refund.py and its test file changed. </verification_loop> <action_safety> Scope strictly to the refund idempotency fix. No unrelated refactors. Do NOT git add or commit; leave changes in the working tree for review. </action_safety> <structured_output_contract> Report: (1) the root cause and your fix, (2) files touched, (3) pytest + ruff outcomes with counts, (4) anything you left open or want decided. </structured_output_contract>

这份示例值得逐块拆解其设计意图：

• <task>第一句给出问题场景与位置（services/billing/退款路径、网络超时重试导致重复扣费、缺少幂等键检查），第二句给出具体修复方向（提交前按幂等键查重）；"Touch only ... Leave ... untouched" 两句把边界钉死，明确排除了 charge 路径、API 路由与数据模型。
• <verification_loop>不是空话，而是指名了pytest tests/billing/ -q与ruff check services/billing/两个真实命令，并附带"git status 只显示两个文件改动"的完成判据——这正是"发现真实门禁，不要硬编码"原则的落地。
• <action_safety>重申范围纪律与"不提交"禁令。
• <structured_output_contract>的四项输出与 review 阶段直接衔接：根因与修复、触碰文件、门禁计数、遗留问题，恰好是 review-and-land.md 中"读 diff 对照 brief"所需的全部信息。

发送时使用 relay 助手（见 dispatch-and-poll.md），典型命令形如：

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo

其中<skill-dir>是codex-delegate技能的安装目录（包含其SKILL.md的目录）；在 Claude Code 中即加载技能时打印的 "Base directory for this skill"。派发后审查结果、自行提交（见 review-and-land.md）。

小结：brief 是委派闭环的第一道质量关卡

把本技能的全部材料连起来看，brief 写作处在闭环的源头：brief 的质量决定了 Codex 产出的上限，也决定了编排者审查成本的下限。核心要点可以收敛为七条：

1. 默认无上下文——Codex 是全新进程，所有任务信息必须显式进 brief；
2. 分块 XML 优于长散文——task/verification_loop/action_safety/structured_output_contract四块打底，按任务类型追加扩展块；
3. 门禁必须是真实的——从仓库的CLAUDE.md/AGENTS.md/Makefile/package.json里抄真实命令；
4. 复述承重禁令——AGENTS.md 之外，把最关键的约束在 brief 里再说一遍；
5. 一任务一 brief——边界清晰，审查与回滚干净；
6. 派发即冻结前提——运行中无法转向，错了就停、修、重派；
7. 用输出契约对抗噪音——固定四段式报告，保证从任何环境包裹中都能提取真结果。

撰写本文所依据的完整资料均位于仓库内：核心指南 writing-the-brief.md、技能总览 SKILL.md、派发与轮询 dispatch-and-poll.md、审查与落地 review-and-land.md、以及多任务队列 multi-task-queues.md。

• AI 技能
• AI 插件