Wayfinder

它的作用¶

wayfinder 处理一个对单个智能体 会话 来说过大的任务。这是一个你能说出 目的地 但还看不到路线的想法。Wayfinder 会在你的问题跟踪器上将其绘制为共享的 地图，由 决策工单 组成，然后逐个解决工单，直到路线清晰。

它只做规划，不做构建。每个工单都提出一个问题，而答案是一个决策，不是一小段构建。当在有人构建该事物之前没有剩余需要决策的事项时，地图就完成了。这条规则将 wayfinder 工单与普通实现 工单 区分开来，也是智能体最常违反的规则。当地图清空时，wayfinder 会交接，而不会继续进入代码。

何时使用¶

你通过输入 /wayfinder 来调用它；智能体 不会自行使用它。

它是该集合中最重的流程，因此触发条件很窄。任务必须大于单个智能体会话所能承载的范围，并且通往目的地的路线必须不清晰。划分标准是会话数量：单会话规划用 /grill-with-docs，多会话规划用 /wayfinder。

全新项目不是必要条件。人们经常在遗留代码库和半成品代码库上使用 wayfinder，并且它在那里可能更有用，因为很多迷雾是“这里已经存在什么”，而不是“我们应该做什么”。

前置条件¶

地图及其工单位于仓库的问题跟踪器上，因此 wayfinder 需要来自 setup-matt-pocock-skills 的跟踪器设置。该步骤会写入一个 “Wayfinding operations” 部分。该部分描述如何在 GitHub、GitLab 或本地 Markdown 上表达地图、其子工单、阻塞边和前沿查询。Wayfinder 通过你 CLAUDE.md / AGENTS.md 中的指针找到该文档，而不是通过固定路径。如果没有配置跟踪器，它会回退到本地 Markdown 文件。

跟踪器承担实际工作。其原生阻塞链接会在跟踪器自己的 UI 中显示前沿。在没有原生依赖链接的跟踪器上（例如自托管 Gitea），wayfinder 会从地图文本中推断阻塞项。这可以工作，但你必须更密切地监督它。

地图、迷雾与前沿¶

地图 是一个标记为 wayfinder:map 的单个问题，其工单是其子问题。它是一个 索引，而非存储。一个决策只存在于一个地方，即其工单，而地图只给出一行摘要和一个链接。一个会话以低分辨率加载地图，并在需要时打开单个工单。这让地图可以不断增长，而无需每个会话加载其完整历史。

地图有四个部分：

• 目的地。 这张地图的终点是什么样。你首先命名它，在任何工单存在之前，因为目的地固定了用来衡量每个工单的范围。
• 迄今为止的决策。 每个已关闭工单一行，每行都带有指向详情所在位置的链接。
• 尚未指定。 这是 战争迷雾：你能感觉到即将到来但还无法清晰表述的决策。判断迷雾还是工单的标准是，你现在是否能精确陈述问题，而不是你是否能回答它。当你解决一个工单时，它前面的迷雾会消散，任何你现在能指定的内容都会晋升为新工单。
• 范围之外。 超出目的地的工作。迷雾只会向目的地聚集，因此范围之外的工作保持关闭，永远不会晋升。

前沿 是未关闭、未阻塞、未认领工单的集合（已知边缘）。一个会话在开始任何工作之前，通过将自己分配给工单来认领它。负责人 就是 认领，因此并发会话会跳过该工单。会话按名称引用工单，从不使用裸 #42，因为一堆问题编号在叙述中难以阅读。

四种决策工单类型¶

每个工单都带有 wayfinder:<type> 标签。每个工单要么是 HITL（与能代表自己发言的人协作），要么是 AFK（仅由智能体驱动）。HITL 工单只能通过实时交流解决。一个回答自己 grilling 问题的智能体已经破坏了它。

task 是唯一执行而非决策的类型。它之所以出现在地图上，只是因为它解除某个决策的阻塞，而不是因为它交付目的地的一部分。在实践中，这种类型最容易出错。智能体会把它读成实现步骤，开始在地图内编写产品代码。

Research 是每个会话一张工单的唯一例外。

常见问题¶

这与 /grill-with-docs 有什么不同？我应该从哪个开始？ 会话数量，而不是项目规模。/grill-with-docs 是单会话规划；wayfinder 是多会话规划。如果你能在一次对话中容纳全部内容，grilling 更便宜且更好，而 wayfinder 在这种情况下更慢、更密集。社区简化的说法是，只有当工作无法放入单个会话时，wayfinder 才有意义。这是迄今为止被问得最多的 wayfinder 问题。人们不断问它，是因为技能描述没有告诉你自己的任务位于那条线的哪个位置。你必须自己判断会话数量。

当它询问“destination”时，是指本会话的结束还是所有事情的结束？ 整个地图的终点，而不仅仅是第一个会话的结束。这个问题读起来有歧义，但 wayfinder 按定义是多会话工具，因此以会话为范围的答案永远没有意义。典型的 destination 包括要交接的 规范、在规划开始前锁定的一项决策、一个概念验证，或就地变更（例如数据迁移）。

地图已经清空。wayfinder 不是已经写了 spec 并创建了工单吗？为什么我还需要 /to-spec 和 /to-tickets？ 不是。Wayfinder 的工单是决策工单，到地图关闭时它们也全部关闭了。剩下的是一张充满关联决策的地图，而不是构建计划。to-spec 将这些关联决策合并为一份规范（/to-spec #<map_issue>），to-tickets 将该规范切分为曳光弹式实现工单。如果你把地图直接循环到 implement，就会跳过合并并丢失关联细节。只有当工作量最终很小，才直接进行实现。有些人运行较短的流水线并报告它有效。多出的两个步骤会给你一份明确的规范，评审者或同事可以阅读；当你不是独自工作时，这一点更重要。

我的智能体在 wayfinder 会话中途开始编写生产代码。 这是该技能报告最多的失败，并且技能中一个真实的缺口导致了它。你可以在地图的 Notes 中覆盖 wayfinder 的“只规划，不执行”默认设置。但智能体编写 Notes，因此约束及其豁免都存在于被约束智能体拥有的文件中。一位用户看到智能体在自己的 Notes 中写下“此地图承载执行”。在后续会话中，智能体把这一行读作许可，并在线上服务器上构建。该技能没有针对“我指的是默认设置”的硬性停止。在它具备之前，阅读任何你自己没有绘制的地图上的 Notes，将实现保留在单独会话中，并将任何看起来像构建切片的 wayfinder:task 视为类型错误。

我绘制了 27 张工单，等到做到第十三张时，其余的已经不再有意义。 这个问题逐字来自用户报告，其他人也报告了相同结果。默认情况下，wayfinder 会全面规划。当后续工单依赖于早期工单所否定的假设时，地图就会落入批评者指责该技能存在的瀑布陷阱。有两点有帮助。首先，将地图范围限定到一个有界的目的地，而不是整个产品。用户报告说，范围限定到一个已定义 epic 的地图，比 sprawling 的“实现 V1”表现更好。目标是交付小增量，而不是规划一个非常大的东西。其次，积极进行 原型。路线保持最新，因为廉价的具体产物会在实现依赖它们之前暴露不确定性。Wayfinder 是“prototypemaxxing”，而不是“planmaxxing”。

我可以并行处理多张工单吗？ 前沿会显示你可以领取哪些工单，阻塞边使并行工作在纸面上安全。在实践中，一次一张工单是更安全的默认设置。如果你同时处理两个 grilling 工单，一个会话可能会问你刚刚在另一个会话中回答过的问题，因为这些会话不共享 上下文。原型工单也有一个已知缺口。一位用户报告说，一个智能体构建了三个 UI 变体，自己选择了一个，并关闭了工单。这个选择应该由你来做，而该技能目前说得还不够清楚。如果你确实并行运行工单，请先自己审查依赖图。

我必须使用 GitHub Issues 吗？ 不。任何 issue tracker 都可以。GitHub 支持最好，因为其原生子 issue 和阻塞关系使前沿无需打开地图即可可见。人们也使用 GitLab、Linear、Jira 和本地 markdown。有两个注意事项。在没有原生阻塞的 tracker 上，wayfinder 会从文本推断依赖图，你必须手动纠正它。本地 markdown 会将产物放入你的 repo，这不被推荐，因为存储在 repo 中的材料往往会意外持久化。开源维护者会遇到相反的问题（公共 tracker 被智能体生成的规划工单填满），并且通常仍然选择本地 markdown。

grilling 令人精疲力竭。每个问题都有三段长。 这是关于 wayfinder 最尖锐的未解决抱怨，目前还没有人修复它。一位用户这样拆解：冗长本身会导致决策疲劳，而长度掩盖了智能体为什么提问，因此随着地图增长，你会失去从决策到决策的链条。这种冗长看起来是当前一组 模型 的属性，而不是技能的属性。用户尝试两种缓解措施：较低的 推理努力，以及在你全局 CLAUDE.md 中的通俗语言指令。无论如何，这里都需要你深入思考。Wayfinder 要求你进行大量思考，而这正是它的大部分目的，而不是缺陷。

我已经关闭的一个决策后来被证明是错的。我应该编辑旧工单，还是新建一个？ 没有官方指导，而代理的默认行为也无济于事。它往往会围绕错误决策进行设计，而不是质疑它，因此你必须自己引导它。有效的方法是直接告诉 wayfinder 发生了什么变化。然后它会更新地图，修订受影响的工单，并在已关闭的工单上添加评论。你可以在地图中途从范围变化中恢复。但如果你设计了一张会变化的地图，这说明范围本身有问题。

decision-mapping 去哪了？ 它就是这项技能。v1.1 将其重命名为 wayfinder，你通过 /wayfinder 调用它。“决策地图”是行话，而且也不准确，因为四种工单类型中只有一种本身就是决策。新名称让这项技能拥有一致的词汇（目的地、战争迷雾、前沿、地图），而不是再叠加一个生造术语。该单元保留了“决策”一词：wayfinder 工单是一张决策工单，以免人们把它读成实现工单。

如果满足以下条件，说明它正在起作用¶

• 在任何一个工单存在之前，目的地已被写下并达成一致。
• 每个未关闭工单读起来都像一个问题。任何读起来像“构建 X”的工单，要么类型错误，要么属于地图下游。
• 你可以查看跟踪器，无需打开地图就能看到哪些工单可处理，因为原生阻塞显示了前沿。
• 一个会话解决一个工单，将答案作为解决评论发布，关闭它，并在地图的迄今为止的决策中添加一行。然后停止。
• 尚未指定会随时间缩小。当迷雾升级为工单时，它会离开该部分，并且不会同时出现在两个地方。
• 当开头的广度优先 grill 完全没有发现迷雾时，技能会停止并告诉你工作量小到可以跳过地图。
• 完成地图的会话会把你引向 spec，而不是 pull request。

它在哪里适用¶

wayfinder 是一个情境化入口，而不是默认起点。大多数工作仍然从由 grill 引导的“想法 → 交付”链路开始。当想法大到无法在一个会话中容纳时，你使用 wayfinder。它在 to-spec 处重新汇入该链路，因为一张已清理的地图只负责交接，不负责构建。

大部分工作发生在 wayfinder 调度的其他技能中。grilling 和 domain-modeling 解决默认工单类型，prototype 解决无法通过讨论确定的工单，research 作为子代理运行，使其阅读内容留在你的会话之外。handoff 将工作移入和移出：从变得太大的对话移入地图，当会话中途出现支线任务时从地图移出。对于其他任何情况，ask-matt 在整个技能集合中路由。