SuperAPI AI 工具集

draft-shells

编程与开发

查看项目

更新于 10-16 07:08

技能介绍

用途

draft-shells 用于将一份规格说明(spec)文件分解为多个 shell。每个 shell 是一个独立的工作单元,对应一次单独的 Claude Code 会话,最终以带 YAML frontmatter 的 Markdown 文件写入 .turbo/shells/<spec-slug>-NN-<title>.md。其目标是把较大的规格拆成可分别实施、协调推进的片段,并保证需求覆盖与依赖关系可追踪。

主要能力

拆解过程创建任务跟踪,为每个步骤建立任务:解析源规格、拆解为 shell、解决开放问题、写入 shell 文件、呈现摘要。若确认的 shell 数量为 1,步骤 2 末尾的单 shell 退出机制会通过 TaskUpdate 删除任务 3 至 5 并退出。

在解析源规格时,按顺序使用规则确定要拆解的 spec:显式路径、显式 slug(解析为 .turbo/specs/<slug>.md)、单文件(Glob .turbo/specs/*.md 且恰好一个)、最近修改(多个文件时取最近修改)、遗留回退(无 .turbo/specs/ 但存在 .turbo/spec.md 时使用,slug 为 legacy)、未找到则停止。解析出的 spec 的 slug 成为 shell 文件名前缀。读取 spec 后需识别:范围、工作类别(UI、后端、数据层、基础设施、测试、文档、工具)、规格需求(枚举 ## Requirements 中的 R<N> ID,每个 R-id 必须至少被一个 shell 的 Covers 字段跟踪)、依赖关系、全新项目与既有项目、开放问题。若 spec 没有 ## Requirements 部分或不含 R<N> 编号项,则使用 AskUserQuestion 提供两个选项:重新运行 /draft-spec(随后从步骤 1 重启),或停止以便用户手动添加带枚举 R<N> ID 的 ## Requirements 部分。

使用方式

拆解为 shell 时,寻找工作可切分的位置与落地顺序:依赖顺序(脚手架、数据与领域层、核心业务逻辑、API 与服务层、UI 与前端、集成与端到端)、自然边界(一个产物的输出是另一个的输入)。强接缝指一侧必须先于另一侧存在,或两侧放在一个会话会超载;弱接缝指切分没有收益。某些部分必须共享一个 shell:紧耦合部分、原子连锁变更(共享接口的破坏性变更需所有消费方同步更新)、可达性(每个 shell 都要让代码库保持完全集成,无不可达组件)。每个 shell 需定义接线不变量:Produces(产出的模块、类型、端点、数据模型、UI 屏幕、迁移文件等概念级产物)、Consumes(依赖的、须已存在的内容,需可追溯到来源,或标记 from existing codebase)、Covers(实现的 R<N> ID)。所有 shell 的 Covers 并集必须等于 spec 中全部 R-id 集合。部分覆盖写为 R<N> (partial: <该 shell 拥有的切片>),独立 R<N> 仅用于由单个 shell 完全满足的需求。不得使用 (finished: ...) 等变体标注。跨切面义务由每个适用 shell 声明自己的部分实例,不能由单个基础 shell 独立声明。shell slug 由标题派生(小写、连字符、≤40 字符),前缀为编号 <spec-slug>-NN-<title-slug>。

形成建议 shell 数量时权衡:更多 shell 意味着每次全新会话交接成本(丢失内存上下文、重复模式调查、额外 /pick-next-shell 轮次)以及各自完整评审;更少 shell 则有超载风险。以文本输出建议数量、每个提议 shell 的一句话范围及理由,然后用 AskUserQuestion 让用户设定最终数量,推荐项标记 (Recommended) 并列 2-3 个备选,推荐数为 2 或以上时至少包含一个更低选项,自动追加的 Other 允许用户输入任意数量。若用户选择不同数量则重新分组。

若确认数量为 1,则不写 shell 文件,因为单 shell 拆解在结构上等价于计划:depends_on 为空、Covers 列出所有 R-id、Produces/Consumes 无消费方、自动化无需协调。

解决开放问题时,若没有开放问题则跳过。每个问题分析权衡并用 AskUserQuestion 提供 2-3 个具体解决选项及一个 Defer to expansion 选项,最强选项标记 (Recommended) 并置于首位。对难以逆转的问题或没有选项有把握时,可提供 Get a second opinion 选项(运行 /consult-codex 技能)。解决后更新内存中的拆解(Produces、Consumes、Covers、Implementation Steps);延迟则记录到相关 shell。默认解决,仅当答案确实需要尚不可用的代码库或模式调查上下文时才延迟。若答案会显著重构拆解(改变数量、合并、拆分),则重跑步骤 2。

写入 shell 文件时创建 .turbo/shells/(若不存在),使用模板写入,模板包含 frontmatter 的 spec 与 depends_on 字段,以及上下文、Produces、Consumes、Covers Spec Requirements、Implementation Steps (High-Level)、Open Questions、Expansion Deferred 等部分。depends_on 列出必须先扩展并实施完成的 shell 文件名(不含 .md)。若无开放问题,该部分写 None 以保持一致结构。

呈现摘要时给出 shell 数量、每个 shell 范围的一句话描述及对歧义的假设;当项目为某人带来价值时,给出故事列表(As a , I want so that )。然后用 AskUserQuestion 提供两条路径:Approve (Recommended) 表示拆解最终确定;Revise 表示用户描述更改,结构性更改需重跑步骤 2 并重写受影响文件,再重新摘要与呈现。批准后告知下一步:运行 /pick-next-shell 开始实施,在其停止后于新会话中运行 /implement-plan。

适用场景

适用于把一份规格拆解为多个可独立会话实施的单元,需要明确需求覆盖追踪(R-id)、依赖关系与接线不变量的项目。也适用于在实施前识别接缝、判断哪些工作必须组合、确定合适 shell 数量的场景。

限制

shell 文件是唯一输出,不得修改 spec 或项目文件。不得把 setup 与 finalization 合并到同一个 shell。每个 Consumes 条目必须有 frontmatter depends_on 的显式边支持,或标记 from existing codebase。所有 Covers 并集必须等于 spec 的 ## Requirements 中的全部 R-id,且每个 R-id 至少出现一次。覆盖标注仅允许独立 R<N>(完全,恰好声明一次)与 R<N> (partial: ...),不得发明变体。同一 R-id 不得同时出现独立声明与部分声明。Implementation Steps 描述构建工作,排除 git commit、git push 和 PR 创建。若 spec 缺少 R<N> 编号需求,shells 无法依赖稳定的 R-id 进行覆盖追踪。

暂未提供

官方文本为空,未提供收费、价格、平台、效果等方面的信息。