to-tickets

拆分为工单

将计划、规格说明或对话拆分为一组工单——追踪弹药式的垂直切片，每个工单都声明阻塞它的其他工单。这些工单会由 epic-runner 接手：它一次处理一个前沿工单，因此你在此设置的阻塞关系，就是实际执行工作的顺序。

跟踪工具。 阅读工程师技能目录中、与仓库并列的 TRACKER.md；它会说明跟踪工具、列出其命令，并将各类含义映射到此仓库的标签字符串。如果没有该文件，就根据用户提供的信息、git 远程仓库，以及已安装且已通过身份验证的 CLI，确定本次运行使用的跟踪工具；如果都无法确定，则默认使用本地 Markdown 文件目录。

工程师技能目录因运行环境而异，因此请使用 glob 查找：

ls */skills/*-engineer/TRACKER.md .*/skills/*-engineer/TRACKER.md 2>/dev/null

流程

1. 收集上下文

根据对话上下文中已有的信息开展工作。如果用户将某个引用（规格说明路径、问题编号或 URL）作为参数传入，请获取该内容并阅读其完整正文和评论。

2. 探索代码库（可选）

如果你尚未探索代码库，请先了解代码的当前状态。工单标题和描述应使用项目领域术语表中的词汇，并遵循你要修改区域的 ADR。

寻找预先重构代码的机会，让实现更容易。“先让改动变简单，再做简单的改动。”

3. 起草垂直切片

将工作拆分为追踪弹药式工单。

• 每个切片都应贯穿各层（架构、API、UI、测试），形成一条范围狭窄但完整的路径——要做垂直切片，而不是只覆盖某一层的水平切片
• 每个切片完成后，都应能独立演示或验证
• 每个切片的规模都应能在一个全新的上下文窗口内完成
• 任何预先重构都应先完成

为每个工单设置其阻塞关系——也就是必须先完成的其他工单。没有阻塞项的工单可以立即开始。

大范围重构是垂直切片的例外。 大范围重构指的是一种机械性改动——例如重命名列或更改共享符号的类型——其影响范围波及整个代码库，因此一次编辑就会同时破坏数千个调用点，无法通过任何垂直切片保持构建通过。不要强行将其拆成追踪弹药式工单；应按扩展–收缩顺序安排。首先扩展：在旧形式旁边添加新形式，确保不会破坏任何内容。然后分批迁移调用点，批次大小按影响范围确定（每个包、每个目录），每批单独建一个工单，并阻塞于扩展工单；由于旧形式仍然存在，每批之间都要保持 CI 通过。最后收缩：旧形式不再有调用方后，将其删除，并创建一个阻塞于所有迁移批次的工单。如果各批次无法单独保持构建通过，则保留原有顺序，但让它们共用一个集成分支，并全部阻塞于最终的集成与验证工单——只有到那一步才能保证构建通过。

4. 向用户确认

以编号列表的形式展示建议的拆分方案。对于每个工单，列出：

• 标题：简短且能描述内容的名称
• 阻塞于：必须先完成的其他工单（如有）
• 交付内容：该工单实现的端到端行为

询问用户：

• 颗粒度是否合适？（太粗 / 太细）
• 阻塞关系是否正确——每个工单是否只依赖真正会阻碍它的工单？
• 是否应合并某些工单，或进一步拆分？

反复调整，直到用户批准拆分方案。

5. 将工单发布到跟踪器

发布已批准的工单。具体方式取决于跟踪器——工单内容相同，只有阻塞关系的呈现方式不同：

• 本地文件 → 在 TRACKER.md 指定的目录下为每个工单写入一个文件，默认为 .scratch/<feature-slug>/issues/<NN>-<slug>.md，按依赖顺序编号，从 01 开始（先列阻塞项）。每个文件的“Blocked by”列出它所依赖的工单编号／标题。使用下方的单工单文件模板——每个文件一个工单，绝不要合并成单个文件。
• 真实工单跟踪器（GitHub、GitLab、Jira、Linear 等） → 按依赖顺序发布工单（先发布阻塞项），以便每个工单的阻塞关系都能引用真实标识符。平台支持原生阻塞／子工单关系时，使用该关系；否则，在每个工单的“Blocked by”中列出阻塞工单。除非另有说明，否则为适合 Agent 处理的工作应用 TRACKER.md 指定的标签——这些工单的设计本身就适合由 Agent 领取。如果其中没有指定此类标签，则跳过添加标签，并说明这一点。

处理当前前沿：所有阻塞项均已完成的工单。对于纯线性链，这意味着从上到下依次处理。

不要关闭或修改任何父工单。

6. 为整组工单设置统一入口

下游编排器无法领取单个工单——epic-runner 需要一个引用，并会在其下列出工单。因此，最后要为整组工单设置一个统一入口，并告知用户：

• 本地文件 → 在工单文件旁边写入一份清单，路径为 <dir>/issues.md，按依赖顺序为每个工单添加一行 - [ ]，并注明其文件名。这份清单就是统一入口；各工单文件则保存详细信息。
• 真实跟踪器 → 使用该跟踪器提供的容器归集工单，例如里程碑、共享标签、父跟踪工单或 Jira 史诗。说明使用了哪一种。

然后明确说明这个统一入口，例如：“运行 /epic-runner .scratch/csv-export/issues/issues.md”——这条命令就是此步骤的核心。

— <工单标题>

要构建的内容： 此工单要实现的端到端行为，从用户的角度描述，而不是逐层罗列实现步骤。

阻塞项： 阻塞此工单的其他工单编号／标题，或“无——可立即开始”。

状态： ready-for-agent

• 验收标准 1
• 验收标准 2

父工单

跟踪器中父工单的引用（如果源自现有工单；否则省略此部分）。

要构建的内容

此工单要实现的端到端行为，从用户的角度描述，而不是逐层罗列实现步骤。

验收标准

• 标准 1
• 标准 2

阻塞项

• 每个阻塞工单的引用，或“无——可立即开始”。

无论采用哪种形式，都应避免写入具体文件路径或代码片段——它们很快就会过时。例外情况：如果原型生成的代码片段比文字更精确地表达了某项决策（状态机、reducer、架构、类型结构），则可将其内联，并简要注明该片段来自原型。仅保留能明确表达决策的部分——不要放入可运行的演示，只保留重要内容。

---

改编自 mattpocock/skills，MIT © 2026 Matt Pocock。复制此文件时请保留此行。