v1.1：/wayfinder、/to-spec、/to-tickets、/grilling 改进等大量更新

经过一段较长的开发周期，技能仓库 1.1 版本终于准备合并。本次发布包含大量变更：全新的 Grilling 方法、对现有技能的一系列更新，以及两个主流程技能的重命名。

与其在这里试图概括全部内容，不如直接逐项看这些变更。

如何迁移

由于本次发布包含技能重命名和合并，你需要更新安装内容。技能安装器不会自动处理这些变化。

运行以下命令获取全部新技能：

npx skills add mattpocock/skills

这样你就可以自由选择需要哪些技能。完成后，检查技能目录，确保没有遗留旧技能。

新的公开文档页面位于：

• docs/engineering/to-spec.md
• docs/engineering/to-tickets.md

重大重命名： /to-spec and /to-tickets

这次最可能让人觉得麻烦、但又有充分理由的两个变化，是技能重命名。名称长期困扰着我，因为它们没有准确反映我们真正构建的东西。

原名称 /to-prd to /to-spec

/to-prd 技能已重命名为 /to-spec。关键在于，我们创建的东西其实并不是 PRD（产品需求文档）。PRD 描述的是产品本身，而我们之前允许非产品内容混入其中。实际上我们构建的是 specification（规格说明）——一个范围更广的术语，可以是技术性的、非技术性的，或两者的结合。

“Spec”现在是整套技能贯穿始终的统一术语。你可能仍习惯把这份文档称为 PRD，但今后我们将统一使用“spec”。

原名称 /to-plan and /to-issues to /to-tickets

两个技能已合并为一个：/to-plan 与 /to-issues 统一为 /to-tickets。旧名称偏向 GitHub 和 Linear，因为它们使用“issues”这个术语。但我们实际处理的概念更通用：你有一份规格说明，规格说明下有多个任务，而这些任务就是把规格真正落地、构建出来的路径。

/to-tickets 会把计划、规格说明或对话拆成一组任务——每个任务都是追踪弹道式的垂直切片，并明确声明阻塞边。根据任务跟踪器的设置，这份产物有两种工作方式：

• 本地文件（tickets.md）——阻塞边以文本写入，你可以手动从上到下处理
• 真实跟踪器——阻塞边变成原生阻塞链接，所有阻塞项已完成的任务都会进入前沿，多个智能体可以并行工作

多年希望名称更加准确后，这种命名清晰度让我十分欣慰。

Grilling 技能改进

下一组变更修复了大家在 /grill-me 和 /grill-with-docs 中遇到的问题。二者都依赖一个中央 Grilling 参考技能，用来向 LLM 展示如何有效追问一个人。

三项关键修复

1. 更清晰的提问指导

原有指导写着“同时提出多个问题会令人困惑”。即使有这条指令，模型偶尔还是会忽略它，一次提出多个问题。因此，我进一步明确解释了为什么不应一次提出多个问题。

2. 实现前增加确认门

在末尾增加确认步骤：“在我确认我们已经达成共同理解之前，不要执行计划。”许多人反馈，Grilling 会话结束后模型会直接跳进实现阶段。这道门可以阻止这种情况。

3. 防止自我追问

在某些异常情况下，模型会自我追问——探索代码库，在没有人类输入时自行 Grilling。这在 Fable 中尤其明显。为了解决它，我加入了 leading words，用来区分两类信息：

只增加几句话并重新调整少量内容，就让技能的一致性大幅提升。这些微调显著减少了大家报告的异常问题。

完整开发生命周期流程

我新增了几个技能，把 Grilling 从主要用于规划的练习，转变成完整的软件开发生命周期。许多人问我：“使用这些技能时，主流程究竟是什么？”答案如下：

流程：从 Grilling 到部署

1. 从 Grilling 开始

不要直接使用规划模式，而是让智能体围绕目标对你进行 Grilling。这会使用两份辅助文档：

• 词汇表，帮助智能体更好理解你的领域
• 架构决策记录（ADR），捕捉那些不明显的决策

2. 生成规格说明

Grilling 的输出会进入规格说明，规格说明定义你的目的地——这项功能或项目要走向哪里。

3. 拆分任务

接着使用 /to-tickets 把规格说明转成独立任务。开发工作会分布到多个智能体会话中，每个会话专注于一个任务。

4. 实现每个任务

使用 /implement 技能实现每个任务，过程非常简单：

Implement the work described by the user in the spec or tickets.
Use TDD where possible at pre-agreed seams.
Run type checking regularly.
Single test files regularly.
Full test sweep once at the end.

/implement 主要依赖智能体的先验知识，以及你的 agents.md 文件教给它的内容。我一度几乎不想为此创建技能，因为它实在太简单，但大家一直问“流程是什么”。现在你有了清晰终点：拿到任务后，在独立编码会话中逐一实现。

5. 代码审查

实现完成后，/implement 会调用 /code-review，在提交前审查工作。

结合重构坏味道的代码审查

代码审查技能从两个维度审查代码，每个维度使用一个子智能体：

两个子智能体会并行运行，逐一检查代码的各个部分。

这个技能有一个很酷的新特点：我最近重新阅读 Martin Fowler 的《Refactoring》，意识到智能体已经在训练中深深掌握了代码坏味道。你只需激活这个概念即可。以下是一些例子：

• 神秘命名
• 重复代码
• 特性依恋
• 数据泥团
• 基本类型偏执
• 重复的 switch
• 发散式变化
• 投机式泛化
• 消息链
• 中间人

当你描述这些概念时，智能体会理解术语并说：“是的，我发现了消息链，需要移除它们。我发现了中间人问题，需要修复。”

我测试了几周，发现它对提升代码质量极其有用。最棒的是，加入它的成本非常低——只需大约 10 行指导。

为大型计划引入 Wayfinder

接下来是我真正兴奋的一项技能：一种启动并塑造规格说明的全新方式。它叫 /wayfinder，在许多场景下可以取代 /grill-with-docs。

何时使用 Wayfinder

/wayfinder 适用于规划内容太多、一次智能体会话无法容纳的情况。你要么会离开智能体的聪明区，要么甚至会撞上上下文窗口上限。必须把任务拆成多个部分，才能逐步确定前进方向。

核心概念如下：

一个松散想法出现了，它太大，无法由一次智能体会话完成，而且被迷雾包围。从这里到目的地的道路还不可见。这个技能会在仓库的任务跟踪器中绘制一张共享地图，然后逐一处理地图上的任务，直到路线清晰。

Wayfinder 如何工作

Wayfinder 会创建一张保存为 GitHub issue 的地图，把每个决策限定为一次智能体会话的规模。决策之间通过阻塞关系连接，因此只有前置条件解决后，依赖决策才能作出。

下面是 Sandcastle 仓库中的一个例子，用于研究是否应将 AI SDK 引入为依赖：

任务类型：

• Research——让智能体 AFK 研究并报告发现
• Grilling——通过追问会话作出决策
• Prototype——通过快速原型提高讨论保真度
• Task——配置、供给或其他不需要 Grilling 的工作

为什么原型设计很重要

我一直主张在写规格说明前更多进行原型设计。做法是先构建一个成本低、粗略但具体的产物作为反馈对象——提纲、粗稿、桩，或 UI 逻辑代码——提高讨论的保真度。

以下情况使用原型设计：

• “它应该长什么样？”是关键问题
• “它应该如何表现？”是关键问题

对于几乎所有涉及前端代码的工作，这都至关重要。任何前端工作，我都强烈建议使用 /wayfinder。

Wayfinder 完成后

所有任务关闭后，全部信息都会保存回地图，并把原始任务作为一手来源。随后可以按常规方式把地图转换成规格说明。

Wayfinder 的美妙之处在于：你不再需要用 /grill-with-docs 管理会话焦虑，也不用担心交接和聪明区，一切都会自动管理。你只需关闭一个会话，再打开下一个 Wayfinder 任务。所有内容都保存在 GitHub 中，因此可以在团队内协作和共享。

辅助技能：Research 与 Prototype

为了支持 Wayfinder 工作流，新增了两个技能。

这个 /research 技能

/research 技能小巧但实用：

• 启动后台智能体执行研究，你可以在它阅读时继续工作
• 依据一手来源调查问题
• 把发现写入简单的 Markdown 文件
• 按照现有约定，把文件保存到仓库存放此类笔记的位置

任何需要进行研究、又不想打断当前流程时，都可以使用它。

这个 /prototype 技能

/prototype 技能现在允许模型调用，因此 Wayfinder 可以自行调用它。它提供两种类型供你选择：

两种类型的行为差异很大，可以帮助你在确定规格说明前探索设计空间。

TDD 技能更新

最后一项变更回应了大家长期提出的需求：让 AFK 智能体接收 /tdd 技能后即可直接工作。

旧方案

旧版 /tdd 会推荐一组步骤，并要求你逐一确认。这种方式很别扭，因为它不符合大多数人使用 TDD 的方式——大家希望智能体能够自主工作。

新方案

/tdd 技能现在只作为参考资料。它不规定具体步骤，只规定基本顺序：

1. Red - Write failing tests
2. Green - Make tests pass
3. Refactor - Improve code (moved out of the loop)

关键变化是：重构不再属于 TDD 循环，而是在代码审查阶段处理。这样实现阶段可以保持聚焦、更加清晰，也不会被重构问题拖累。

需要注意的事项

• /to-spec 取代 /to-prd——更新相关流程或文档
• /to-tickets 取代 /to-plan 和 /to-issues——三者现在已经统一
• 新工作流——考虑采用：Grilling → Spec → Tickets → Implement → Code Review
• 在大型规划任务中使用 Wayfinder——尝试用 /wayfinder 替代 /grill-with-docs