一、为什么长任务不能只靠一个智能体从头做到尾

很多人刚开始用 Codex 时，会把它当成一个很强的“超级程序员”：把需求一次性塞进去，然后等它自己读代码、写方案、改文件、跑测试、修 bug、最后交付。对于小任务，这样确实很爽。比如修一个拼写错误、补一个单元测试、解释一段函数逻辑，一个主对话就足够。

但当任务变长之后，问题会逐渐出现。

第一，主线程上下文会变脏。长任务里会出现大量中间信息：搜索日志、失败命令、临时推测、无关代码片段、测试输出、被否定的方案。如果所有信息都堆在同一个对话里，主智能体后面做决策时就容易被噪声干扰。

第二，任务之间本来可以并行，却被迫串行。比如一次重构需要同时完成“理解旧行为”“设计类型”“补测试”“审查风险”“查官方文档”。这些工作互相有关，但不一定必须按顺序等待。如果只让一个智能体做，它会在多个角色之间来回切换，效率低，也容易漏掉某些角度。

第三，验证容易被弱化。AI 很擅长给出一个看起来完整的结论，但真实工程里，“看起来做完”和“真的可交付”不是一回事。你需要测试命令、构建结果、接口响应、截图、diff、覆盖率、日志证据，甚至还要让另一个视角审查前一个实现有没有回归风险。

第四，复杂任务需要角色分工。一个人类团队做重构时，也不会让同一个人同时扮演产品、架构、实现、测试、审查和发布负责人。AI 协作也一样。主智能体更适合做统筹和最终判断，子智能体更适合处理边界清晰的专项工作。

这就是 Codex 里使用主智能体和多个子智能体的价值：不是让很多 AI 同时“乱改代码”，而是让主智能体把复杂任务拆成可验证的小闭环，再让多个子智能体并行产生证据、方案、补丁或审查意见，最后由主智能体汇总、合并、验证并交付。

本文会详细讲：

• 主智能体和子智能体分别应该负责什么。
• 什么样的任务适合拆给多个子智能体。
• 如何写提示词，让 Codex 明确启动并管理子智能体。
• 如何用一个完整案例跑通“调研、实现、测试、审查、验证”。
• 如何避免并行修改冲突。
• 如何把子智能体的结果验证到可交付，而不是停留在“它说已经完成了”。

文末还附了可直接复制的提示词模板和 checklist。

二、先把概念说清楚：主智能体和子智能体分别是什么

在 Codex 里，你当前正在对话、理解总目标、最终给你交付结果的那个智能体，可以理解为“主智能体”。当你明确要求它“启动多个子智能体”“并行委派”“一个 agent 负责一个方向”时，它可以把某些子任务委派给子智能体。子智能体会在自己的上下文里完成专项工作，然后把摘要、证据、修改结果或审查意见返回给主智能体。

这个机制最重要的点是：子智能体通常不会自动出现。你需要在提示词里明确表达“请使用多个子智能体”“请并行派出 3 个 agent 分别做 A/B/C”“请让一个 agent 只做审查，不修改代码”。否则 Codex 很可能会继续用单智能体方式完成任务。

可以把职责边界概括成一句话：

主智能体负责“拆、控、收、判”，子智能体负责“查、跑、验、报”。

主智能体的职责包括：

• 理解用户真正要达成的目标，而不是只执行字面命令。
• 判断任务是否值得拆分，拆成哪些子任务。
• 为每个子智能体写清楚任务边界、输入、输出和禁止事项。
• 控制哪些子任务可以并行，哪些必须串行。
• 汇总子智能体结果，发现冲突，要求补证据。
• 合并代码或文档产物，统一风格和接口。
• 运行最终验证命令。
• 对最终交付负责。

子智能体的职责包括：

• 阅读指定目录或文件，回答具体问题。
• 在指定范围内实现局部功能。
• 补充测试用例或设计验证方案。
• 运行某组命令并汇报结果。
• 对某个补丁做独立代码审查。
• 对官方文档、错误日志、接口响应做专项核验。
• 把结论整理成结构化摘要返回给主智能体。

请注意，子智能体不是最终裁判。它可以给你证据、建议、补丁、测试结果，但最后是否合并、是否发布、是否满足业务目标，还是应该由主智能体汇总后交给你确认。主智能体也不应该盲信某个子智能体的一句“我已经验证通过”，而要看它跑了什么命令、改了哪些文件、覆盖了哪些场景、还有什么风险。

三、什么时候应该使用多个子智能体

并不是所有任务都适合多智能体。判断标准不是“任务看起来很高级”，而是看它是否满足下面几个条件：

• 子任务边界清楚。
• 子任务之间可以并行。
• 每个子任务的产物可以被验证。
• 子任务的结果可以被主智能体汇总。
• 并行带来的收益大于协调成本。

最适合拆分的任务通常是“读多写少、证据分散、可独立验证”的任务。

1. 大型代码库探索

比如你接手一个陌生项目，要弄清楚登录流程从前端按钮到后端鉴权再到数据库查询的完整链路。可以让多个子智能体分别探索：

• 子智能体 A：只看前端登录入口和表单提交逻辑。
• 子智能体 B：只看后端认证接口和中间件。
• 子智能体 C：只看用户表、权限表和数据模型。
• 子智能体 D：只看现有测试和 mock 数据。

最后主智能体汇总成一张调用链路图和风险清单。

2. PR 审查或大 diff 审查

一个大 PR 往往包含正确性、安全性、性能、测试覆盖、兼容性等多个维度。你可以让不同子智能体分别审查：

• 是否存在行为回归。
• 是否有安全风险。
• 是否缺少测试。
• 是否有性能退化。
• 是否改动了公共 API。

这样比让一个智能体从头看到尾更容易发现问题。

3. 长重构任务

重构最怕两件事：第一，改着改着忘了旧行为；第二，抽象越改越大，最后测试不够。多智能体很适合把重构拆成：

• 旧行为梳理。
• 新结构设计。
• 局部实现。
• 测试补全。
• 独立审查。

主智能体负责始终守住“不要破坏旧行为”的红线。

4. 调试复杂 bug

比如一个线上接口偶发 500，原因可能在数据、缓存、并发、配置、最近提交、第三方依赖。可以让多个子智能体并行调查：

• 一个看错误日志。
• 一个看最近相关提交。
• 一个看接口调用链。
• 一个看测试和复现脚本。

主智能体拿到多方结论后，再决定最小修复路径。

5. 文档和代码双向核验

当你要升级一个 SDK、迁移一个 API、修改一个框架版本时，不能只看代码，也不能只看文档。可以让一个子智能体查官方文档，一个子智能体读当前项目用法，一个子智能体找 breaking changes。最后主智能体把“文档要求”和“项目现状”对齐。

四、什么时候不应该拆成多个子智能体

多智能体不是越多越好。拆分也有成本：每个子智能体都要消耗上下文和调用成本，也会带来协调和合并风险。

下面这些场景不建议拆：

• 任务很小，一个智能体几分钟可以完成。
• 需求还很模糊，连目标都没说清楚。
• 多个子智能体会同时修改同一个核心文件。
• 需要非常统一的架构判断或文风判断。
• 涉及高风险生产操作，例如数据库删除、支付逻辑、权限策略。
• 子任务之间强依赖，前一步没确定，后一步无法有效推进。
• 只是为了“看起来高级”而拆分。

我的经验是：前期调研可以大胆并行，代码修改要谨慎并行。读代码、查文档、跑测试、做审查，这些任务非常适合并行。多个子智能体同时写代码时，必须先划清文件所有权，最好使用 worktree 或独立分支隔离。

五、推荐工作流：主智能体如何管理一个长任务

一个比较稳的流程可以分成七步。

第 1 步：主智能体先定义任务边界

不要一上来就说“帮我重构一下这个项目”。更好的说法是：

目标：重构销售报表模块，把业务逻辑从 Express 路由中拆出来，保留旧 API 行为，同时新增 JSON 输出。

约束：
1. 不改变旧的 markdown 输出字段和接口路径。
2. 不引入大型新依赖。
3. 必须补核心统计逻辑的单元测试。
4. 最终需要运行 lint、typecheck、test。
5. 如果需要修改 package.json、数据库 schema、全局配置，请先说明，不要直接改。

请先判断这个任务是否适合拆给多个子智能体。如果适合，请给出拆分方案，再开始执行。

这一步的重点是让 Codex 先“想清楚怎么做”，而不是直接开始改文件。

第 2 步：主智能体拆出可独立完成的子任务

例如：

子任务	是否并行	是否允许改文件	产物
旧行为梳理	是	否	行为契约、边界情况
类型设计	是	否或少量	类型建议、接口结构
实现重构	否或谨慎	是	代码补丁
测试补全	可并行但需隔离	是	测试用例
独立审查	是	否	风险清单

注意，不是所有子任务都必须同时开始。通常可以先并行做调研，等行为契约明确后，再做实现和测试。

第 3 步：给每个子智能体写清楚边界

子智能体提示词里一定要写：

• 你是谁。
• 你负责什么。
• 你不负责什么。
• 可以读哪些文件。
• 可以改哪些文件。
• 遇到不确定情况怎么办。
• 输出格式是什么。
• 是否要运行验证命令。

不要只写“你去看看测试”。更好的写法是：

你是测试子智能体。

目标：
为 src/services/reportService.ts 的核心统计逻辑补测试。

允许修改：
- tests/reportService.test.ts
- tests/fixtures/report/*.csv

禁止修改：
- src/routes/report.ts
- package.json
- tsconfig.json

请覆盖：
1. 正常 CSV 输入。
2. 缺失可选字段。
3. 缺失必填字段。
4. 空文件。
5. JSON 输出结构。

交付格式：
1. 修改文件清单。
2. 新增测试点列表。
3. 运行过的命令和结果。
4. 未覆盖风险。

第 4 步：主智能体并行等待，但不重复子任务

一个常见错误是：派了子智能体之后，主智能体又自己把同样的事情做一遍。这样会浪费时间，也容易产生两个不同版本的结论。

更好的方式是：子智能体在跑时，主智能体做非重叠工作。比如子智能体 A 在梳理旧行为，子智能体 B 在看测试缺口，主智能体可以先检查项目脚本、确认验证命令、整理验收矩阵。

第 5 步：子智能体交付必须带证据

“我已经完成了”不是证据。合格的子智能体交付应该包含：

• 负责范围。
• 修改文件。
• 关键实现点。
• 运行命令。
• 命令结果。
• 失败项。
• 剩余风险。
• 需要主智能体确认的问题。

例如：

交付摘要：
1. 范围：只修改 tests/reportService.test.ts 和 tests/fixtures/report/basic.csv。
2. 新增测试：正常统计、空文件、缺失 required 字段、JSON 输出结构。
3. 运行命令：npm run test -- reportService。
4. 结果：通过，12 tests passed。
5. 未覆盖：没有覆盖 Express 路由层，需要主智能体跑集成测试。

第 6 步：主智能体汇总、合并、复核

主智能体要做三类复核：

• 看 diff：确认改动是否对应需求。
• 跑命令：确认测试和构建真实通过。
• 对照验收标准：逐条核对是否完成。

如果两个子智能体结论冲突，主智能体不要凭感觉选边，而要要求它们补证据。可以这样追问：

你们两个对子任务结论不一致。请只基于代码和测试证据回答：

1. 你的结论依赖哪个文件、哪段逻辑？
2. 哪个测试或命令能验证你的判断？
3. 对方结论可能在哪个前提下成立？
4. 如果采用保守策略，最小修复方案是什么？

第 7 步：最终输出验证报告

长任务结束时，最好要求 Codex 输出固定格式的验证报告：

最终验证报告：
1. 完成了什么。
2. 修改了哪些文件。
3. 运行了哪些命令。
4. 哪些通过，哪些失败。
5. 是否满足每条验收标准。
6. 仍需人工确认的风险。

这样你后续发 PR、写日报、交接任务时，都能直接复用。

六、完整实战案例：重构一个遗留销售报表模块

下面用一个具体案例贯穿全文。假设我们有一个 Node.js + Express 项目，其中有一个遗留文件：

src/routes/report.js

它负责生成“月度销售分析报告”。问题是：

• 路由、CSV 解析、数据清洗、统计计算、Markdown 渲染混在一个 800 行文件里。
• 缺少单元测试。
• CSV 字段偶尔缺失时会抛异常。
• 新需求要求同时输出 Markdown 和 JSON。
• 报告统计逻辑后续要给前端 Dashboard 复用。

目标是：

将遗留销售报告模块拆成可测试的 TypeScript 服务层，保留原 API 行为，同时新增 JSON 输出和测试覆盖。

1. 给主智能体的总提示词

可以这样开始：

我要重构一个遗留销售报表模块，请你作为主智能体统筹，并使用多个子智能体完成长任务。

背景：
- 旧文件是 src/routes/report.js。
- 它混合了 Express 路由、CSV 解析、数据清洗、统计计算和 Markdown 渲染。
- 现在要把业务逻辑拆到 src/services/reportService.ts。
- 旧的 Markdown API 行为必须保持兼容。
- 新增 JSON 输出，用于前端 Dashboard。
- 必须补测试。

请按下面流程执行：
1. 先启动子智能体 A，只读代码，梳理旧行为契约。
2. 启动子智能体 B，只做类型和数据模型设计。
3. 等 A/B 返回后，你汇总成重构方案。
4. 再启动实现子智能体 C，在明确文件范围内做重构。
5. 启动测试子智能体 D 补测试。
6. 最后启动审查子智能体 E，只看 diff，不修改文件。
7. 你作为主智能体最终合并、运行验证命令并输出验证报告。

验收标准：
1. 原接口 /api/report?month=YYYY-MM&format=markdown 仍可用。
2. 原 Markdown 输出字段不变。
3. 新增 /api/report?month=YYYY-MM&format=json 或等价 format=json 输出。
4. 核心统计函数有单元测试。
5. npm run lint、npm run typecheck、npm test 通过。
6. 没有无关重构。

这个提示词的关键点是：它没有只说“帮我重构”，而是把角色、流程、阶段、验收标准都写清楚了。

2. 子智能体 A：现状侦察

子智能体 A 的任务不是改代码，而是形成“旧行为契约”。重构最怕破坏旧行为，所以第一步必须把旧行为写下来。

提示词：

你是代码侦察子智能体。请只阅读现有实现，不修改文件。

目标：
分析 src/routes/report.js 的现有行为。

请输出：
1. 当前 API 路径、请求参数、响应格式。
2. CSV 输入字段要求。
3. 统计指标计算规则。
4. 已发现的边界情况。
5. 重构时必须保持兼容的行为。

限制：
- 不要重构。
- 不要写代码。
- 请给出文件路径和关键函数名。
- 如果发现行为不明确，请标为“需要主智能体确认”。

理想输出应该像这样：

旧行为契约摘要：
1. 路由：GET /api/report。
2. 参数：month 必填，format 可选，默认 markdown。
3. Markdown 输出包含：总销售额、订单数、客单价、Top 5 商品。
4. CSV 必填字段：order_id、date、amount、product_id。
5. CSV 可选字段：region、channel。
6. amount 为空时当前实现会 NaN，需要重构时改成明确错误。
7. 兼容要求：format 未传时仍返回 Markdown。

3. 子智能体 B：类型和数据模型设计

子智能体 B 的任务是提出类型结构，减少实现时的混乱。

提示词：

你是 TypeScript 类型设计子智能体。

基于旧行为契约，设计新的类型结构。

请输出：
1. SalesRecord 类型。
2. ReportSummary 类型。
3. ReportOptions 类型。
4. MarkdownReport 和 JsonReport 的返回结构。
5. 哪些字段允许为空，哪些必须校验。
6. 哪些错误应该用明确异常表达。

限制：
- 不要修改业务逻辑。
- 不要引入大型依赖。
- 类型设计要贴近现有项目风格。

可能的类型设计：

export interface SalesRecord {
  orderId: string;
  date: string;
  amount: number;
  productId: string;
  region?: string;
  channel?: string;
}

export interface ReportOptions {
  month: string;
  format: "markdown" | "json";
}

export interface ReportSummary {
  month: string;
  totalRevenue: number;
  orderCount: number;
  averageOrderValue: number;
  topProducts: Array<{
    productId: string;
    revenue: number;
    orderCount: number;
  }>;
}

export interface JsonReport {
  format: "json";
  summary: ReportSummary;
}

export interface MarkdownReport {
  format: "markdown";
  content: string;
}

4. 主智能体汇总重构边界

等 A/B 返回后，主智能体应该先汇总，而不是立刻让实现子智能体乱改。一个合理的拆分是：

src/services/reportService.ts
  - parseSalesCsv
  - normalizeSalesRecord
  - calculateReportSummary
  - renderMarkdownReport
  - generateJsonReport
  - generateReport

src/routes/report.ts
  - 只保留 Express 参数读取、错误处理和响应。

tests/reportService.test.ts
  - 测核心统计逻辑。

tests/reportRoute.test.ts
  - 如项目已有集成测试，则测路由兼容。

这一步很重要，因为它决定了后续子智能体的文件所有权。

5. 子智能体 C：重构实现

提示词：

你是重构实现子智能体。

目标：
把 src/routes/report.js 中的业务逻辑迁移到 src/services/reportService.ts。

允许修改：
- src/routes/report.js 或迁移后的 src/routes/report.ts
- src/services/reportService.ts
- src/services/reportTypes.ts

禁止修改：
- package.json
- tsconfig.json
- 数据库 schema
- 其他无关路由

要求：
1. 保持原 Express 路由响应不变。
2. 新增 generateJsonReport 方法。
3. 将 CSV 解析、数据清洗、指标计算、报告渲染拆成独立函数。
4. 不引入大型新依赖。
5. 保持代码可测试。

交付时请输出：
1. 修改文件清单。
2. 主要函数说明。
3. 兼容旧行为的处理点。
4. 运行过的命令和结果。
5. 没有覆盖的风险。

实现子智能体可能会给出类似结构：

export function calculateReportSummary(records: SalesRecord[], month: string): ReportSummary {
  const monthlyRecords = records.filter((record) => record.date.startsWith(month));
  const totalRevenue = monthlyRecords.reduce((sum, record) => sum + record.amount, 0);
  const orderCount = monthlyRecords.length;

  return {
    month,
    totalRevenue,
    orderCount,
    averageOrderValue: orderCount === 0 ? 0 : totalRevenue / orderCount,
    topProducts: calculateTopProducts(monthlyRecords),
  };
}

主智能体要检查这个函数是否真的符合旧统计口径。比如旧逻辑是否按订单去重？退款单是否排除？amount 是否含税？这些都不能让实现子智能体自己猜。

6. 子智能体 D：测试补全

提示词：

你是测试子智能体。

目标：
为销售报告重构补充测试。

允许修改：
- tests/reportService.test.ts
- tests/fixtures/report/*.csv

请覆盖：
1. 正常 CSV 输入。
2. 缺失可选字段。
3. 缺失必填字段。
4. 空文件。
5. Markdown 输出快照或关键字段断言。
6. JSON 输出结构。

请优先使用项目现有测试框架。
如果发现没有测试框架，请说明建议，不要直接引入复杂工具链。

交付格式：
1. 新增测试清单。
2. 修改文件清单。
3. 运行命令。
4. 通过/失败结果。
5. 未覆盖风险。

测试可以像这样设计：

describe("calculateReportSummary", () => {
  it("calculates revenue, order count and average order value", () => {
    const summary = calculateReportSummary(
      [
        { orderId: "A001", date: "2026-06-01", amount: 100, productId: "P1" },
        { orderId: "A002", date: "2026-06-03", amount: 300, productId: "P2" },
      ],
      "2026-06",
    );

    expect(summary.totalRevenue).toBe(400);
    expect(summary.orderCount).toBe(2);
    expect(summary.averageOrderValue).toBe(200);
  });
});

测试子智能体的产物不一定完美，但它能把验证面铺开。主智能体还要检查测试是否只是在适配新实现，而不是保护真实业务行为。

7. 子智能体 E：独立审查

最后让一个子智能体只看 diff，不改文件。

提示词：

你是代码审查子智能体。

请审查本次销售报告模块重构。

重点关注：
1. 是否破坏旧 API 行为。
2. 是否存在统计口径变化。
3. 是否有异常未处理。
4. 是否有过度抽象。
5. 测试是否覆盖关键风险。
6. 是否有无关改动。

要求：
- 不要修改文件。
- 按严重程度输出问题列表。
- 每个问题尽量给出文件路径、函数名、验证方式。
- 如果没有发现问题，也要说明剩余测试缺口。

一个好的审查输出应该像这样：

P1：可能改变空数据行为
文件：src/services/reportService.ts
问题：旧接口在没有记录时返回空 Markdown 表格，新实现直接抛出 EmptyReportError。
验证：添加 month=2026-01 且无记录的集成测试。
建议：保持旧 Markdown 行为；JSON 输出可返回 orderCount=0。

P2：缺少路由层兼容测试
文件：tests/reportService.test.ts
问题：只测了 service，没有测 GET /api/report 默认 format 行为。
建议：补一个路由集成测试，确认未传 format 时仍返回 Markdown。

主智能体拿到审查意见后，再决定哪些必须修，哪些可以记录为风险。

七、验证方法：不要相信“完成了”，要相信证据

多智能体做长任务时，验证比实现更重要。下面是我建议的验证层级。

1. 文件级验证：看 diff

先看改了哪些文件：

git status --short
git diff --stat
git diff

你要确认：

• 是否只改了任务相关文件。
• 是否有无关格式化。
• 是否修改了高风险文件，例如 package.json、迁移脚本、权限模块。
• 是否删除了旧逻辑但没有测试保护。
• 是否有临时代码、console、调试开关。

对于长任务，主智能体最好在最终报告里列出修改文件清单。

2. 静态验证：lint 和类型检查

常见命令：

npm run lint
npm run typecheck
pnpm lint
pnpm typecheck
yarn lint
yarn tsc --noEmit

如果是 Python：

ruff check .
mypy .
pytest

如果是 Go：

go test ./...
go vet ./...

静态验证的价值是快速发现低级错误，例如导入路径错、类型不匹配、未使用变量、格式问题。

3. 单元测试：保护核心逻辑

对于销售报表案例，最重要的是保护统计函数：

npm run test -- reportService

建议至少覆盖：

• 正常输入。
• 空输入。
• 缺失可选字段。
• 缺失必填字段。
• 金额为 0。
• 金额为非法字符串。
• 月份过滤。
• Top 商品排序。
• Markdown 输出关键字段。
• JSON 输出结构。

单元测试要尽量测纯函数，不要依赖 Express、数据库或外部服务。这样测试快，也适合子智能体反复运行。

4. 集成测试：保护旧 API 行为

重构时最容易出问题的是“内部实现变了，外部行为也跟着变了”。所以要测路由层：

npm run test -- reportRoute

如果项目没有集成测试，也可以用 curl 做冒烟验证：

npm run dev
curl "http://localhost:3000/api/report?month=2026-06&format=markdown"
curl "http://localhost:3000/api/report?month=2026-06&format=json"
curl "http://localhost:3000/api/report?month=2026-06"

要验证：

• 不传 format 时仍然返回 Markdown。
• format=markdown 行为不变。
• format=json 返回结构正确。
• 缺失 month 时错误明确。
• 非法 CSV 不会让服务崩掉。

5. 快照或黄金样例：保护输出格式

对于报告类功能，输出格式也很重要。可以准备一个固定 CSV：

tests/fixtures/report/sales-june.csv

然后生成黄金输出：

node scripts/generate-report.js ./tests/fixtures/report/sales-june.csv --format markdown
node scripts/generate-report.js ./tests/fixtures/report/sales-june.csv --format json

如果项目适合 snapshot，可以用 snapshot。如果输出格式经常变化，也可以只断言关键字段，避免快照过于脆弱。

6. 交叉验证：实现、测试、审查分离

多智能体真正好用的地方在于交叉验证：

• 实现子智能体负责改代码。
• 测试子智能体负责补测试。
• 审查子智能体负责找风险。
• 主智能体负责最终运行完整验证。

这比“一个智能体写完后自己说没问题”要可靠得多。

7. 最终验收矩阵

建议把验收标准做成矩阵：

验收项	验证方式	结果	证据
旧 Markdown API 保持兼容	curl 或集成测试	通过/失败	命令输出
JSON 输出新增成功	单元测试 + curl	通过/失败	响应示例
核心统计逻辑有测试	npm run test – reportService	通过/失败	测试日志
类型检查通过	npm run typecheck	通过/失败	命令输出
无无关改动	git diff --stat	通过/失败	diff 摘要
审查无 P1/P2 问题	审查子智能体报告	通过/失败	问题清单

主智能体最终输出时，可以直接按这张表汇报。

八、如何避免多个子智能体互相踩文件

并行最大的风险是冲突。尤其是代码修改任务，如果多个子智能体同时改同一个文件，最后主智能体会很痛苦。

1. 先分配文件所有权

例如：

文件或目录	负责人	说明
src/services/reportService.ts	实现子智能体 C	核心业务逻辑
src/routes/report.ts	主智能体	保持 API 兼容
tests/reportService.test.ts	测试子智能体 D	单元测试
package.json	主智能体	原则上不改
tsconfig.json	主智能体	原则上不改

提示词里可以写：

如果你发现必须修改未分配给你的文件，请停止并回报原因，不要直接修改。

这句话非常有用，可以阻止子智能体越界。

2. 公共文件由主智能体统一处理

这些文件尽量不要让多个子智能体同时改：

• package.json
• pnpm-lock.yaml
• tsconfig.json
• vite.config.ts
• 路由总表
• 数据库 schema
• 权限策略
• 公共类型定义
• CI 配置

如果必须改，也应该由主智能体统一改，或者先让子智能体提出建议，主智能体再实施。

3. 使用 worktree 或独立分支隔离

如果是多个子智能体同时写代码，建议使用 Git worktree 或独立分支。worktree 的好处是每个任务有自己的工作目录，互不污染，最后再由主智能体合并。

概念上可以这样理解：

主工作区：负责最终集成和验证
worktree-a：子智能体 A 做后端重构
worktree-b：子智能体 B 做前端改造
worktree-c：子智能体 C 做测试补全

Codex 官方文档也把 worktree 作为并行工作的一个重要方式。对于真实项目，尤其是多人协作项目，不要让多个智能体在同一个脏工作区里随意改文件。

4. 小步合并，小步验证

不要等所有子智能体堆出巨大 diff 后一次性合并。更好的做法：

1. 合并旧行为梳理结果。
2. 合并类型设计。
3. 合并最小服务层实现。
4. 跑单元测试。
5. 合并路由层改造。
6. 跑集成测试。
7. 合并测试补全。
8. 跑完整验证。
9. 做最终审查。

这样每一步出问题都容易定位。

九、提示词模板：可直接复制使用

1. 通用长任务启动模板

请你作为主智能体处理这个长任务，并在合适时启动多个子智能体并行工作。

任务目标：
[写清楚最终要交付什么]

背景：
[写清楚项目、文件、业务约束]

验收标准：
1. [功能标准]
2. [回归标准]
3. [测试标准]
4. [质量标准]
5. [交付标准]

约束：
1. 不要修改无关文件。
2. 公共配置文件需要先说明再修改。
3. 每个子智能体必须说明自己的范围和输出证据。
4. 主智能体最终负责汇总、合并和验证。

请先给出拆分方案，然后开始执行。

2. 只读探索子智能体模板

你是只读探索子智能体。

目标：
[说明要探索的问题]

范围：
- 允许阅读：[目录或文件]
- 禁止修改任何文件

请输出：
1. 相关文件和函数。
2. 当前行为。
3. 关键数据流。
4. 边界情况。
5. 风险点。
6. 需要主智能体确认的问题。

3. 实现子智能体模板

你是实现子智能体。

目标：
[说明要实现的局部功能]

允许修改：
- [文件 1]
- [文件 2]

禁止修改：
- [共享文件]
- [高风险文件]

要求：
1. 保持现有公开 API 兼容。
2. 不做无关重构。
3. 不引入新依赖，除非先说明必要性。
4. 遇到范围外修改需求时停止并回报。

交付格式：
1. 修改文件清单。
2. 实现说明。
3. 运行命令和结果。
4. 未覆盖风险。

4. 测试子智能体模板

你是测试子智能体。

目标：
[说明要保护的行为]

请补充或设计测试，覆盖：
1. 正常路径。
2. 关键边界。
3. 错误输入。
4. 回归场景。

优先使用项目现有测试框架。
不要为了测试引入复杂工具链。

交付格式：
1. 新增测试点。
2. 修改文件。
3. 运行命令。
4. 测试结果。
5. 仍未覆盖的风险。

5. 审查子智能体模板

你是审查子智能体。

请只审查当前改动，不要修改文件。

重点关注：
1. 行为回归。
2. 安全风险。
3. 错误处理。
4. 测试缺口。
5. 过度抽象。
6. 无关改动。

输出格式：
- P1：必须修复的问题。
- P2：建议修复的问题。
- P3：可选优化。
- 测试缺口。
- 最终风险判断。

6. 最终验证报告模板

最终验证报告：

一、完成内容
- [完成了什么]

二、修改文件
- [文件列表]

三、验证命令
- [命令 1]：[结果]
- [命令 2]：[结果]

四、验收标准对照
1. [验收项]：[通过/失败]，证据：[说明]
2. [验收项]：[通过/失败]，证据：[说明]

五、剩余风险
- [风险 1]
- [风险 2]

六、建议后续动作
- [建议]

十、一个更真实的执行节奏

很多文章会把流程写得很理想，但真实项目经常会发生变化。下面是一个更接近实际的节奏。

第一个回合，你告诉 Codex 总目标，并要求它先拆分任务。Codex 可能会派出两个只读子智能体：一个读旧代码，一个读测试。此时主智能体不急着改代码，而是等待关键行为契约。

第二个回合，子智能体 A 返回旧行为，子智能体 B 返回测试缺口。主智能体发现旧逻辑里有一个“金额为空时默认为 0”的历史行为。这个行为看起来不合理，但已经被前端依赖。主智能体应该把它写进验收标准，而不是让实现子智能体随手改成抛异常。

第三个回合，主智能体让实现子智能体只拆 service，不改路由行为。实现完成后，测试子智能体补核心测试。主智能体运行 npm run test -- reportService，发现一个 Top 商品排序测试失败。此时不要让所有子智能体继续乱动，而是让主智能体定位失败原因，必要时只派一个子智能体检查排序口径。

第四个回合，路由层接入 service。主智能体跑集成测试，发现不传 format 时返回 JSON，而旧行为默认 Markdown。这个问题属于 P1 回归，必须修。

第五个回合，审查子智能体看 diff，指出 package.json 被格式化了但没有必要。主智能体还原无关格式化，只保留业务相关修改。

第六个回合，主智能体跑完整命令：

npm run lint
npm run typecheck
npm test

最终输出验证报告。这个过程比“一个智能体一口气改完”慢一点，但可靠性高很多。对于真正要合进主分支的代码，这是值得的。

十一、常见误区

误区 1：子智能体越多越好

不是。子智能体越多，协调成本越高，token 成本也越高。一般来说，3 到 5 个已经足够覆盖调研、实现、测试、审查几个关键角色。除非是批量任务，不要轻易开很多。

误区 2：让多个子智能体同时改同一批文件

这是最容易翻车的用法。并行读代码很安全，并行写代码要谨慎。如果必须并行写，请用 worktree、分支或明确文件所有权。

误区 3：把子智能体当成人类同事一样完全放权

AI 子智能体很强，但它没有你的业务责任。它可能会为了让测试通过而改变业务口径，也可能会做无关重构。主智能体必须保留最终判断，你也要保留人工确认权。

误区 4：只看总结，不看证据

“测试通过了”这句话不够。你要看跑了什么测试、在哪个目录跑的、是否跳过了失败项、是否只跑了局部命令。最终验证最好由主智能体重新跑关键命令。

误区 5：没有验收标准就开始拆分

没有验收标准，多智能体只会更混乱。你需要先定义“什么叫完成”，再让子智能体围绕这个目标工作。

误区 6：把新线程和子智能体混为一谈

为了当前任务内部的分工，应该使用子智能体。新建 Codex 线程更适合长期、独立、用户需要单独管理的任务。两者不是一回事。简单说：子智能体是当前任务里的临时工作分工；新线程是用户侧可持续跟进的独立任务容器。

十二、可复用 checklist

子智能体启动前

• 子任务边界是否清楚？
• 是否说明允许读哪些目录？
• 是否说明允许改哪些文件？
• 是否指定了禁止修改的共享文件？
• 是否要求返回验证命令和证据？
• 是否说明遇到不确定性要停止回报？
• 是否有明确输出格式？

子智能体交付时

• 是否列出修改文件？
• 是否说明实现思路？
• 是否运行测试、构建、lint 或类型检查？
• 是否提供失败项和未覆盖风险？
• 是否有无关改动？
• 是否影响公共接口、配置、依赖或数据库？
• 是否需要主智能体进一步确认？

主智能体验收时

• 是否逐条对照验收标准？
• 是否重新查看关键 diff？
• 是否重新运行关键命令？
• 是否检查多个子智能体结论是否冲突？
• 是否处理共享文件和合并冲突？
• 是否保留最终验证记录？
• 是否说明剩余风险和人工复核点？

并行修改防冲突

• 是否使用 worktree 或独立分支？
• 是否有文件所有权分配表？
• 是否避免多个智能体同时改同一文件？
• 是否把公共接口先定下来？
• 是否由主智能体统一合并？
• 是否小步合并、小步测试？

十三、我自己的使用建议

如果你是刚开始尝试多智能体协作，我建议从“只读并行”开始。比如让三个子智能体分别读前端、后端、测试，然后主智能体汇总方案。这个阶段风险很低，但能立刻感受到并行调研的好处。

第二阶段，再尝试“一个实现，一个测试，一个审查”。实现子智能体改代码，测试子智能体补测试，审查子智能体找问题。主智能体最终合并和验证。这是最实用的生产级模式。

第三阶段，才考虑多个子智能体并行写代码。这个阶段一定要配合 worktree、文件所有权、阶段验收和小步合并。否则很容易把一个长任务变成一堆互相冲突的 diff。

另外，要养成一个习惯：每次长任务开始前，把验证命令写进提示词。很多失败不是 Codex 不会改，而是它不知道你的项目到底应该怎么验证。你写清楚 pnpm test、npm run build、pytest tests/user、go test ./...，它就更容易把任务收敛到可交付状态。

还有一个非常有用的技巧：让 Codex 先输出“验收矩阵”，再开始执行。只要验收矩阵写得好，后面的子智能体就不会跑偏太多。

十四、总结

用 Codex 做长任务，关键不是“让 AI 一次性变得无所不能”，而是把复杂工作拆成可验证的小闭环。

主智能体应该像项目负责人一样工作：理解目标、拆分任务、控制边界、汇总结果、运行验证、做最终判断。子智能体应该像专项执行者一样工作：读代码、查资料、补测试、做审查、跑命令、给证据。

最稳的模式是：

1. 主智能体定义目标和验收标准。
2. 多个子智能体并行调研。
3. 主智能体汇总方案。
4. 边界清楚后再局部实现。
5. 测试子智能体补验证。
6. 审查子智能体找风险。
7. 主智能体最终跑完整检查并输出验证报告。

记住一句话：

多子智能体不是为了同时让很多 AI 改代码，而是为了让复杂任务的每一步都有边界、有证据、有复核。

当你把“任务拆分”和“结果验证”这两件事做好，Codex 就不只是一个会写代码的聊天窗口，而会变成一个可以协作完成长任务的工程伙伴。

参考资料

• OpenAI Codex: Subagents
• OpenAI Codex: Best practices
• OpenAI Codex app: Worktrees
• OpenAI Codex: Skills
• OpenAI Codex: Building an AI-Native Engineering Team