ask-skills

询问 Skills

你不可能记住每项技能，所以遇到问题就问。

在说明某项技能的作用或建议跳过某个步骤之前，请先阅读该技能的 SKILL.md：此处的摘要仅供了解概况。

流程是穿过各项技能的一条路径。大多数路径沿着一条主流程前进，并有一条接入路径汇入其中。其他所有内容都是独立的。

主流程：从想法到交付

大多数工作都会走这条路线。你有一个想法，并希望把它实现出来。

1. /grill-with-docs 通过访谈打磨想法。只要你在工作目录中工作，就从这里开始：它会保留状态，将学到的内容记录在 GLOSSARY.md 和 ADR 中。（没有工作目录？改用 /grill-me，详见“独立技能”。两者运行的是同一个 /grilling 基元；grill-with-docs 会留下记录，因此只要有仓库可供记录，它就是更好的选择。）

2. 分支：能否在对话中解决所有问题？ 如果某个问题需要通过可运行的答案来解决（状态、业务逻辑、需要亲眼查看的 UI），就绕道制作原型，并通过双向的 /handoff 衔接（原型位于自己的目录中，这正是 /handoff 的用途；参见“阶段边界”）：

   • 先用 /handoff 交接出去，然后针对该文件开启一个全新会话，
   • 用 /prototype 编写临时代码来回答问题，
   • 再用 /handoff 带回所学内容，并在原始想法的讨论串中引用它。

3. 分支：这是一个需要多次会话才能完成的构建吗？

   • 是 → 用 /to-spec（将讨论串整理成规范），然后用 /to-tickets 将其拆分为示踪弹式工单，每个工单都要声明其阻塞边。之后有两种方式处理这些工单：
     • 每个工单使用 /implement，并在每个工单之间用 /clear 清理上下文。在本地跟踪工具中，每个工单对应 .scratch/<feature>/tickets/ 下的一个文件，并手动按阻塞项优先的顺序处理；在真正的跟踪工具中，这些边会成为原生阻塞链接，因此任何阻塞项都已完成的工单都可以领取。每个工单都是自包含的，所以最后一个工单的上下文可以丢弃。（“独立技能”下的 /delegate-tickets 会无人值守地运行这一循环，每个工单分配一个子 Agent。）
     • 对整个规范使用 /implement-spec 一次性完成。它会将工单作为任务图读取，让实现者子 Agent 并行处理已就绪的前沿，将所有内容合并到一个集成分支，然后对其运行一次 /review-axes。如果你更希望统筹整个构建，而不是亲自驱动每个工单，就选它。
   • 否 → 就在这里、同一个上下文窗口中运行 /implement。

   无论哪种方式，/implement 都会在内部通过驱动 /tdd 来构建每个工单：一次完成一个红绿切片，运行完整测试套件，对自身差异进行一轮重构（如果测试套件转红，则撤销重构），最后运行 /review-axes，对差异进行双轴审查（标准 + 规范），并以将工作提交到当前分支结束。如果你只想在没有完整规范的情况下，以测试优先的方式构建一项具体行为，就单独使用 /tdd；如果你想根据一个固定基准审查分支，就单独使用 /review-axes。/review-axes 用于审查你自己的工作，它会根据你遵循的标准和收到的规范来评判差异。审查他人的合并请求是另一项工作：参见“独立技能”下的 /review-mr。

   工作以拉取请求的形式提交时，/pr 会整理请求正文：用最精简的视觉材料展示改动，提供改动前后的有效性证据，并判断这是单向还是双向决策门。它由模型调用，因此 Agent 每次编写 PR 时都会使用它。

4. /retro 会在构建完成后回顾整个过程，尤其是在构建不顺利之后。它会读取会话，并建议修改 Agent 的环境，而不是代码：导航指引、自动化检查、/review-axes 强制执行的编码标准、引导文件、工具。机械性错误会转化为确定性检查；需要判断的事项会转化为编码标准。这样，下次构建就能从更好的环境开始。

5. /archive-feature 会在所有内容都实现后完成收尾。在本地跟踪器中，它会根据文件检查每个工单是否都处于 ready-for-human（或 done）状态，且所有复选框都已勾选；随后显示汇总表，并在获得一次确认后，将规范和工单设为 done，再用 git mv 将整个功能从 .scratch/ 移至 docs/archive/<feature-slug>/。传入功能名称或规范路径，也可以不传参数来扫描 .scratch/ 下的所有功能。只有在你指定功能名称时，才会归档未完成的功能，并在其规范中附上带日期的说明，列出未完成的内容。它绝不会勾选任何复选框。当你想问“我已经实现完了，现在该做什么？”时，就用它。它不适用于远程跟踪器。

上下文卫生

步骤 1–3 要放在同一个连续的上下文窗口中（直到运行完 /to-tickets 后，才能压缩或清除），这样问答、规范和工单才能基于同一套思路逐步构建。每次运行 /implement 都要从新上下文开始，基于工单开展工作。在要回顾的会话中运行 /retro，并在清除上下文前完成；清除后，则将其指向该会话的日志。

这里的限制是**智能区间**：模型仍能清晰推理的窗口范围（在最先进的模型上约为 150k 个 token）。如果会话在运行 /to-tickets 前就接近这个范围，不要在性能下降时硬撑；在最近的阶段边界运行 /compact，然后继续（参见“阶段边界”）。

入门路径

从能产生工作量的起点出发，然后并入主流程。

• 规模庞大、方向模糊的工作：从零开始的项目，或大到无法在一次会话中完成的大型功能构建 → /wayfinder，这是这里认知负担最大的流程。当从当前状况到目标的路径尚不清晰时，它会在问题跟踪器上绘制一张包含决策工单的共享地图，并逐一解决这些工单，产出的是决策，而非交付物，直到拨开迷雾、路径明朗。/grill-with-docs 适合梳理你能在一次会话中把握的想法，而 wayfinder 适合梳理你无法在一次会话中把握的想法；它的速度更慢、内容更密集，所以只应在这种情况下使用，绝不要用于范围明确的功能。

  地图清晰后，它会交接，而不是构建：并入主流程，从 /to-spec 开始，将地图中相互关联的决策整合成可构建的计划，然后照常运行 /to-tickets 和 /implement。直接从地图转入 /implement 会跳过这一步整合，丢失相互关联的细节；因此，只有当这项工作最终确实很小，才直接进入 /implement。在此过程中，它的研究工单会通过 /research 子 Agent 并行解决，因此你不必等到自己做完资料查阅工作。

代码库健康状况

不是开发新功能，只是维护。

• /improve-codebase-architecture：有空时就运行，保持代码库易于 Agent 操作。它会找出深化机会；选中一项后会生成一个想法，你可以在主流程中通过 /grill-with-docs 继续推进。

• /tech-debt-map：范围更广、视角更冷静的调查，一次检查一个模块。它会梳理项目如何划分为模块（如果项目尚未划分，也会自行定义），询问你要检查哪个模块，并显示每个模块上次检查至今经过了多久；随后会从各个维度全面检查该模块（架构、代码、业务规则、可维护性、可测试性、性能、安全性），并生成一份技术债务地图：最多列出 10 条有证据支撑的发现，按收益与影响范围排序，然后提供一个分三个阶段逐步执行的计划。这是诊断，不是重构，不会更改任何代码，不过会在 docs/tech-debt/README.md 中维护已提交的检查索引，以便发现哪些模块已经八个月没人审查。/improve-codebase-architecture 会针对一类问题展开调查，并以围绕单个候选项的深挖会谈收尾；而这个工具会生成一份文件，供你在数周内逐步处理，并通过重新运行来查看进展。它的条目会进入 /to-spec，再进入 /to-tickets；影响范围为 Systemic 的条目则会进入 /improve-codebase-architecture。

阶段边界

阶段是会话中的一段工作：深挖、实现、QA。两个阶段之间的边界有五种选择，如何选择是整张路线图中最模糊的决策：

• 继续：留在当前会话中。不花费任何代价，也不会丢失任何内容。
• /clear：清空上下文窗口，适用于当前内容与下一步无关的情况。
• /handoff会写入一个可移植的 Markdown 文件。适用范围很窄：仅用于新 harness、新目录、同事，或在阶段中途分叉处理并行任务。它带来的好处是可移植性。
• 子 Agent：将范围明确的任务交给独立窗口，并获取报告。
• /compact会压缩当前上下文，并用压缩后的内容开启新会话。它是默认选项，位于决策树的底部，而非优先选择。

阅读 PHASE-BOUNDARIES.md，了解按顺序排列的决策树：五个问题、每个分支背后的理由，以及为什么主要来源成本意味着应首先排除继续。请在边界处做出决定；阶段中途应继续，或将剩余工作拆分给子 Agent。

独立流程

完全脱离主流程。

• /grill-me：与 /grill-with-docs 一样进行不间断访谈，但它是无状态的：不会在本地保存任何内容，也不会创建 GLOSSARY.md。当你不在工作目录中时（例如完善计划、设计、文稿，或任何没有代码仓库的事情），请使用它。如果你在工作目录中，则改用 /grill-with-docs：它会进行同样的访谈，并留下记录，因此显然是更好的选择。
• /grilling：访谈的基本机制：分轮进行，探索前沿，事实由 Agent 负责，决策由你做出。/grill-me 和 /grill-with-docs 是两种具名入口，/wayfinder 和 /improve-codebase-architecture 则会在内部运行它。只有在你想直接进行访谈、不需要任何封装时，才直接使用它。
• /prototype：一个小型、一次性程序，用来回答一个设计问题：这种状态模型是否合适，或者这个 UI 应该是什么样子。“一次性”约束的是代码的编写方式，并不意味着一定要将它销毁：得出的答案会融入正式代码，而原型本身会保留在从 main 分出的 prototype/<name> 分支上，作为一手资料，并从实现 issue 中链接到它。它是主流程第 2 步中的一个绕行步骤，但只要难以通过讨论敲定设计问题，随时都可以使用。
• /research：将阅读资料的工作委派给后台 Agent：它会根据一手资料调查问题，然后在代码仓库中留下带引用的 Markdown 文件。它阅读时，你可以继续工作。它生成的文件应带入 /grill-with-docs 的主流程中；研究为思考提供依据，但不能替代思考。
• /frontend-handoff：变更已交付，由另一个团队接手使用。它会读取规范和 diff，然后输出一个可直接粘贴的内容块，其中的结论（必须变更／应该变更／无需变更）是前端开发人员首先需要了解的内容。在 /implement 之后运行，用来回答“前端需要做什么改动吗？”，无需开会。它只移交上下文；前端工作本身是他们代码仓库中的独立任务。
• /to-questionnaire：当阻碍你的信息不在你的脑海中或代码库里，而在其他人那里时，它会编写一份问卷供对方填写。它与 /grill-me 正好相反：它不会就主题采访你，而是围绕问卷的发送采访你，了解收件人是谁、你需要对方提供什么，然后针对信息缺口设计问题。收到的内容可用于 /grill-with-docs 或 /to-spec。
• /wizard：用于只能由人类完成的步骤：配置基础设施、设置凭据或 CI 密钥、操作不熟悉的第三方仪表板、执行一次性迁移或切换。它会生成一个交互式 bash 脚本，逐个打开 URL、收集各项值，并将其写入 .env 和 GitHub secrets，这样你就不必每次都向 Agent 重新解释流程。它由模型调用，因此 Agent 一遇到只有你才能解决的障碍就会使用它。如果 Agent 能自行完成，就应该自己完成；此工具只用于确实需要人类介入的情况。
• /wait-what：用于纠正未能传达清楚的信息。在对话中途、任何其他技能内部都可以使用；Agent 会结合你缺少的上下文，用通俗易懂的英语重新表达刚才的内容，并使用 GLOSSARY.md 中的词汇。它可以事后使用；/grill-with-docs 则是事前的解决办法，因为及早商定共同语言，就能避免术语一开始就出现。
• /traduzir：将 Agent 的上一条消息翻译成巴西葡萄牙语（pt-BR），方便你阅读。它是一次性的阅读辅助工具：整条消息都会翻译，代码和命令保持不变，后续回复仍使用英语。/wait-what 会重新解释未能传达清楚的消息，而此工具则会翻译你看不懂的消息。
• /writing-for-agents：编写供 Agent 使用的文档时参考：技能、AGENTS.md 以及被明确指向的文档。
• /review-mr：审查他人的合并请求（GitLab、GitHub 或两个本地分支），检查错误、安全性、性能和设计，依据任务的验收标准进行核对，并将结论（批准或要求修改，以及原因）和审查发现写入本地 Markdown 文件。它会先询问 diff 无法回答的问题，再进行评判。/review-axes 会依据代码仓库的标准和规范评判你自己的 diff，而此工具评判的是他人的 diff。
• /delegate-tickets：通过全新的子 Agent 按顺序编排工单实现，一次处理一个工单，并要求每个子 Agent 都运行 /implement。当 /to-tickets 已生成工单，而你希望无人值守地完成所有工单的构建时，请使用它；每个工单之间都会运行 /clear 清除上下文。它只处理 Standard 和 Light 工单（使用 Sonnet，工作强度为 medium）；遇到 Heavy 工单或没有 Difficulty: 行的工单时，就会停止运行，让你手动处理。任何步骤需要人类回答时，它也会停止，而不是继续执行。

前置条件

• /setup-skills：在首次工程流程前运行，以配置问题跟踪器、分类标签、文档布局，以及项目 .claude/settings.json 中用于阻止破坏性 Git 操作的规则。自定义问题跟踪器也可使用。
• /setup-solid：可选，每个仓库运行一次。它会在 CLAUDE.md 中写入一个 SOLID 部分，约束之后的每个流程：SOLID 属于架构层面，与语言无关，并遵循 童子军规则，既应用于新代码，也应用于变更已涉及的代码，让代码库逐次变更地逐渐趋于完善。/improve-codebase-architecture 用于发现需要进行的重构，而这项设置则规定了代码应如何编写。