executing-tickets-with-subagents

使用子 Agent 执行工单

概述

主对话只负责协调。所有编辑、评审和 QA 检查都由派遣的子 Agent 执行。持久状态保存在磁盘和 GitHub 上。压缩无法影响这两个位置，因此运行可以在压缩后继续。

选择运行分支

• 无人值守。 当用户明确表示要暂时离开并要求工作继续时，在首次派遣前完整阅读 ${CLAUDE_SKILL_DIR}/references/unattended-scheduler.md。其中的调度、转换、更新和交接约定即使只有一项任务也适用。只有当工作同时属于打包的 GitHub 工单时，才使用以下阶段。
• 打包工单。 对工单的接收、任务波次和收尾使用以下阶段。

派遣工作前，先在台账中记录所选分支。这是必经关卡。

阶段 0：接收

1. 恢复检查。 如果此工单已有台账，先阅读台账，并执行其中的下一步操作。台账是运行状态的唯一来源，而非对话记忆。下一波开始前，核对全部四项跟踪记录：待办列表、检查清单评论、harness 任务和台账。
2. 获取完整的问题讨论串。 完整阅读 ${CLAUDE_SKILL_DIR}/../audit-ticket/references/ticket-evidence.md 和 ${CLAUDE_SKILL_DIR}/../audit-ticket/SKILL.md 中经身份验证且遇到失败即停止的图片下载指南，然后使用 gh issue view <n> --json number,title,body,author,createdAt,updatedAt,state,assignees,url,comments 获取结构化的问题 JSON。根据问题正文和每条评论的 body、author、createdAt 及 url 建立来源映射。对所有附加图片进行身份验证下载，并在 HTTP 错误时退出；打开文件前先检查退出状态，并实际读取每张成功下载的图片。将下载失败记录为 image <i> unavailable。切勿将错误响应正文作为图片证据打开或计算哈希。评论经常会覆盖或补充原始正文；未读评论意味着你还没有完整的规格说明。
3. 研究代码库。 在向用户提问前，先对照代码验证相关说法。

阶段 1：锁定、规划、跟踪

1. 探索。 派遣并行的只读 Agent 检查代码。为每个子问题给出已完成、部分完成或尚未开始的判定，并附上文件和行号证据。
2. 向用户逐项确认。 针对任务顺序、PR 策略、每项任务的完成标准、跟踪方式以及迁移和提交策略等用户负责的事项，运行 grill-me。只有当上述每项都已得到锁定答案并写入台账时，确认流程才算结束。后续每次派遣都必须遵守这些锁定答案。
3. 先定规格，再做计划。 为每个子问题编写一份简要说明，涵盖所有子问题，并列出精确的代码位置和 2-3 项评审者必须检查的具名风险。通过符号定位，而非行号，因为任务落地时行号会发生变化。然后，在任务 1 开始前，针对整套简要说明运行 grill-me 验证流程。
4. 在任务 1 开始前设置跟踪：
   • 维护台账，例如 docs/<ticket>-progress.md。它是恢复路线图，具体约定如下。
   • 维护 tasks/todo.md 检查清单。
   • 在问题中维护一条可编辑的 GitHub 检查清单评论。每项都要注明状态和根本原因。将其评论 ID 保存在台账中，并使用 gh api ... -X PATCH -F body=@file 更新。将完整的初始评论写入文件，并固定其 SHA-256。创建前立即刷新问题的 URL、updatedAt、正文、状态、指派对象和评论。确认目标检查清单仍不存在，然后使用这些检查条件、精确固定的文件及其摘要、锁定的跟踪决策、预期的最终评论正文和权威评论回读，调用 preflight-mutations。继续之前，按其结果约定处理。按 ID 读回已创建的评论，并要求其完整正文与固定内容一致。仅当权威回读证明操作未生效时才重试。标准输出为空不代表失败。
   • 使用 TodoWrite 维护 harness 待办列表。

Ledger 合约

为完全不了解上下文的读者编写 ledger。假设下一位写作者什么都不记得。每一轮结束后都要更新。内容必须包括每项任务的状态及 commit SHA、以祈使句表述的当前 NEXT ACTION、等待分诊的累计 Moderate 和 Minor 发现、常驻流程规则，以及简报和产物的位置与 ticket 来源映射。常驻规则涵盖已授予的权限、环境特性与备用方案，以及 QA 凭证和数据说明。

Phase 2：一轮（每项任务一轮）

1. 从简报到暂存笔记。 如果自规划以来 HEAD 已移动，运行 Explore 漂移检查并编写补充说明。以补充说明为准。

2. 全新实现 Agent。 编排者负责派遣，Agent 负责编辑。Bug 修复采用 TDD。先编写会失败的测试，并观察其失败。格式化并运行该任务的类型检查循环，然后保留未提交的任务差异，以供独立审查。派遣提示必须完整自洽：包含路径、环境、已锁定的决策、验证命令、预期的 commit 格式、报告格式，以及环境特性对应的备用方案。Agent 不掌握其他上下文。

3. 两阶段审查，使用不同的子 Agent。 组合审查者会受其起始视角影响。两个全新的审查者则不会。审查包含两份报告，每个阶段一份：

   • Stage 1，规范符合性。 审查者会收到任务简报和差异，以及需要核实的指定风险。输入恰好只有这两项。审查者针对 ticket 要求返回判定，类别为 Missing、Extra 或 Misunderstood，并提供 file:line 证据。
   • Stage 2，代码质量。 独立审查者检查正确性、错误处理、能验证真实行为的测试，以及代码结构。发现分为 Critical、Serious、Moderate 或 Minor。parallel-review 会并行运行，检查风格与惯例。Stage 1 负责发现规范违规。

4. 对每项发现进行分诊。 FIX-NOW 表示由修复 Agent 进行修复，然后两个阶段都重新审查，直到规范检查通过且质量审查认可；任务结项时不得有未解决的 Critical 或 Serious 发现。DISMISS 需要经过验证的理由，因此先检查已锁定的设计或简报，因为审查者可能会重新质疑已确定的决策。DEFER 仅适用于 Moderate 和 Minor，并将其记录在 ledger 中。审查通过后，对未提交的差异运行该任务适用的 done 检查流程。让 done 调用 git-commit，为该任务创建唯一且已验证的 commit，并记录其 SHA。如果已锁定的一轮策略包含推送，则在推送前调用 preflight-mutations，并提供准确的远程分支、本地与上游 SHA、commit 范围、PR base 和 head、依赖项，以及已锁定的推送权限。

   将每份报告都视为未经验证。只有提供证据才能消除疑虑：SHA、数量、file:line 引用，以及实际运行过与仅检查过的内容。

5. UI 任务使用 browser-qa。它会记录原始数据、恢复数据并证明已恢复。其产物仅存放在暂存笔记中。必须在各轮之间运行，且不得有实现者处于活动状态。热重载会在测试过程中污染会话。

6. 记账。 勾选 tasks/todo.md。在每次对清单执行 PATCH 之前，立即调用 preflight-mutations，并提供准确的 issue 和 comment ID、替换后的正文、当前 comment 版本和正文、已锁定的跟踪权限，以及回读结果，然后按照其结果契约执行。更新 harness 待办列表和 ledger，再开始下一项任务。

与其反复提醒卡住的 Agent，不如将其停用。记录其终止状态或成功中断的情况，保留其工作树和差异位置，然后将任务从 active 移至 ready，并派遣新的负责人。如果无法证明 Agent 已不活动，则将任务标记为 blocked，不要再指派第二位负责人。

阶段 3：收尾

1. 从重新计算的合并基点开始对整个分支做最终审查。合并基点会移动，因此要重新计算，并排除生成文件。报告发现的所有跨任务交互，或明确说明没有发现。将所有记录表中的次要问题分类为 FIX-NOW、FOLLOW-UP 或 DROP。
2. 进行修复，然后运行 fix-pr-review，回复并解决每条外部审查线程，同时引用提交 SHA 或说明理由。
3. 将完整的最终 PR 正文渲染到文件，并冻结其 SHA-256。在更新正文或将 PR 标记为可合并前，立即刷新精确的 PR URL、当前标题和正文、基准分支和头部分支 SHA、草稿状态，以及依赖 PR 和工作流。针对这批外部元数据，调用 preflight-mutations，并提供这些目标保护条件、冻结的正文路径和摘要、精确的最终正文和可合并状态、更新和标记可合并操作，以及用户对标记为可合并的批准。遵循其结果约定；每次写入前都重新检查保护条件和摘要，并要求对完整正文和草稿状态进行权威回读。在最终头部分支上监控 CI。草稿和合并冲突会静默跳过 pull_request 工作流，因此“没有失败”可能意味着“根本没有运行”。确认工作流在最终头部分支上运行，然后确认其通过。
4. 手动 QA 交接文档。 这是捆绑式缺陷修复工单的标准收尾文档。对于每个已修复项目，链接到源问题评论，用通俗语言描述修复前的问题以及发生的变化，并提供逐步测试说明，让用户能够验证每项修复。
5. 每个遗留发现都要单独创建工单。 较小的问题合并到一个后续工单中。重大问题各自创建专属 Issue。每个后续工单都必须按照 file-issue 第 6 节添加 --label ai-created。撰写任何改写、拆分或后续 Issue 之前，都要重新阅读 ${CLAUDE_SKILL_DIR}/../audit-ticket/references/ticket-evidence.md。其来源关系图和渲染后的收尾关卡适用于原始 Issue 和每个后续工单。对每个拟议的后续工单应用 file-issue 的双词表重复项搜索，并在暂存之前解决所有匹配项。先渲染每个最终正文，并记录其路径和 SHA-256 摘要。在首次写入前，刷新原始 Issue 的 updatedAt，并针对完整批次调用一次 preflight-mutations：提供准确的仓库、原始 Issue 的当前状态和保护条件、冻结的完整调查更新或评论载荷、每个冻结的后续工单标题、正文路径、摘要、ai-created 标签和创建选项、重复项搜索查询及其处理结果、原始 Issue 与后续工单之间的链接、后续工单与前置工单之间的链接、与依赖关系相关的同级工单链接、来源发现和证据 ID、负责人、授权，以及渲染后的 Issue 和图片回读计划。遵循其结果约定；每次写入前都重新检查保护条件和载荷摘要，然后仅执行该批次中的写入操作。重新获取并重读渲染后的 Issue 集合及图片，并对照来源映射核验，然后再报告工单已完成。创建结果不明确时，应遵循 preflight-mutations 的 reconcile-required 约定，而不是重试。

硬性规则

规则	原因
卡住的 Agent → 退役、保留，然后替换	再次催促会浪费时间；未确认就替换会造成两个负责人
用户拥有的领域，例如迁移、合并或取消草稿状态 → 先询问	一项批准不适用于下一个类别