安装此技能
npx skills@latest add mattpocock/skills --skill=wayfinder 然后在你的编码 agent 里输入 /wayfinder 。
本页目录
它做什么
wayfinder 接手的是一件大到一场 agent 会话（session）装不下的工作。这是一个你能说出目的地（destination）、却还看不清路线的想法。wayfinder 把它画成一张共享的、由决策工单（decision ticket）组成的地图（map），放在你的 issue 追踪器上，然后一张一张地解决这些工单，直到路线清晰。
它只做规划，不做构建。每张工单都提出一个问题，答案是决定，而不是构建工作的一块切片。当有人动手构建之前已经没有任何事情需要决定时，这张地图就完成了。这条规则把 wayfinder 的工单与普通的实现工单（ticket）区分开来，也是 agent 最常打破的规则。地图理清之后，wayfinder 就交接出去，不会继续写进代码。
什么时候用它
你通过输入 /wayfinder 来调用它；agent 不会主动去拿它。
它是整套技能里最重的流程（flow），所以触发条件很窄。这件工作必须大到一场 agent 会话装不下，而且通往目的地的路线必须还不清楚。分界在于会话数量：单场会话的规划用 /grill-with-docs，跨多场会话的规划用 /wayfinder。
| 你面前有什么 | 该运行什么 |
|---|---|
| 一个范围划得很好、你一坐就能定下来的功能 | grill-me，或者在有代码库时用 grill-with-docs |
| 一个全新项目，或者一次跨越许多场会话、路线仍不清楚的构建 | /wayfinder |
| 一个决定已经做完的讨论串 | to-spec：直接跳过地图 |
| 一张已经理清的 wayfinder 地图 | to-spec，然后是 to-tickets 和 implement |
| 一场已经长得太大的现有会话 | 说一句「把工作交接给 /wayfinder」（handoff 既能把工作接进地图，也能从地图里接出去） |
全新项目并不是前提条件。人们在遗留代码库和半成品代码库上也经常使用 wayfinder，而且在那里它可能更有用，因为大部分雾区（fog of war）是「这里已经为真的是什么」，而不是「我们该做什么」。
前提条件
地图和它的工单存放在仓库的 issue 追踪器（issue tracker）上，所以 wayfinder 需要 setup-matt-pocock-skills 做好追踪器配置。那一步会写下一个「Wayfinding operations」小节。这个小节描述如何在 GitHub、GitLab 或本地 markdown 上表达地图、它的子工单、阻塞边（blocking edges）和前沿查询。wayfinder 通过你 CLAUDE.md / AGENTS.md 里的指针找到那份文档，而不是在固定路径上找。没有配置追踪器时，它会退回到本地 markdown 文件。
追踪器承担实际工作。它原生的阻塞链接能在追踪器自己的界面里显示前沿（frontier）。在没有原生依赖链接的追踪器上（比如自托管的 Gitea），wayfinder 会从地图文本里推断阻塞者。这行得通，但你必须更密切地监督它。
地图、雾区与前沿
地图是一个带 wayfinder:map 标签的 issue，它的工单就是它的子 issue。它是索引，不是仓库。一个决定只存在于一个地方，也就是它的工单里，地图只给一行摘要和一个链接。一场会话以低分辨率加载地图，需要时再打开单张工单。这让地图可以持续生长，而不必让每场会话都加载它的全部历史。
地图有四节：
- 目的地。 这张地图的终点是什么样子。你要先给它命名，在任何工单存在之前，因为目的地确定了衡量每一张工单所用的范围。
- 迄今为止的决定。 每张已关闭的工单一行，每行都带一个链接，指向细节所在的地方。
- 尚未明确。 这就是雾区：你能够看出即将到来、却还不能精确表述的决定。区分雾区与工单的标准，是你能不能现在就把问题精确地说出来，而不是你能不能回答它。当你解决一张工单时，它前方的雾区就散开，任何你现在能够明确的东西都会毕业成一张新工单。
- 范围之外。 目的地之外的工作。雾区只会朝着目的地方向聚集，所以范围之外的工作保持关闭，永远不会毕业。
前沿是那些打开、未阻塞、未被认领的工单的集合（已知区域的边缘）。一场会话在做任何工作之前，先把工单指派给自己，以此认领它。负责人就是认领凭证，所以并发的会话会跳过那张工单。会话用名字来指代工单，绝不用光秃秃的 #42，因为一堵 issue 编号组成的墙在叙述里很难读。
四种决策工单类型
每张工单都带一个 wayfinder:<type> 标签。每张工单要么是**人在回路（HITL）（与能代表自己的人一起完成），要么是离开键盘（AFK）**（仅由 agent 驱动）。人在回路的工单只能通过实时交流来解决。一个自问自答自己的质询（grilling）问题的 agent 已经把它弄坏了。
| 类型 | 模式 | 什么时候用它 | 由谁解决 |
|---|---|---|---|
grilling | 人在回路 | 默认项。这个问题可以通过把它谈透来解决。 | grilling 加上 domain-modeling，在一场全新的会话里 |
prototype | 人在回路 | 「这看起来该是什么样」或者「它该怎么表现」：一个谈话解决不了的问题。 | prototype，工单里给出指向构建产物的链接 |
research | 离开键盘 | 工作目录之外的一个事实阻塞了一项决定。 | 一个 research 子代理（subagent），在你绘制地图时启动，在 research/<name> 分支上并行运行 |
task | 两者皆可 | 没有要决定的东西，但手工劳动阻塞了一项决定，比如开通访问权限、注册某项服务，或者搬移数据好让你看清它的形状。 | 能自己做的由 agent 独自完成，否则给人类一份精确的清单 |
task 是唯一一个去做而不是做决定的类型。它出现在地图上，只是因为它能解除一项决定的阻塞，绝不是因为它交付了目的地的一部分。这个类型在实践中出错最多。agent 把它读成一个实现步骤，然后开始在地图里写产品代码。
调研是每场会话一张工单的唯一例外。
常见问题
它和 /grill-with-docs 有什么不同？我该先用哪个？
看会话数量，不看项目大小。/grill-with-docs 是单场会话的规划；wayfinder 是跨多场会话的规划。如果你能在一场对话里装下整件事，质询更便宜也更好，而在那种情况下 wayfinder 更慢、更密。社区的简略说法是：只有工作装不进一场会话时，wayfinder 才讲得通。这是到目前为止被问得最多的 wayfinder 问题。人们不停地问，是因为技能描述没有告诉你，你自己的任务落在这条线的哪一边。你得自己判断会话数量。
当它问「目的地」时，指的是这场会话的终点，还是一切的终点？ 整张地图的终点，而不只是第一场会话。这个问题读起来有歧义，但 wayfinder 按定义就是一个跨多场会话的工具，所以一个只以一场会话为范围的答案永远讲不通。典型的目的地包括：一份用来交接的规范文档（spec）、一个在规划开始前就要锁定的决定、一个概念验证，或者一次原地改动，比如数据迁移。
地图已经理清了。wayfinder 不是已经写好规范文档、也建好工单了吗？为什么我还需要 /to-spec 和 /to-tickets？
没有。wayfinder 的工单是决策工单，等到地图关闭时，它们也全都关闭了。剩下的是满满一张链接着各种决定的地图，那不是构建计划。to-spec 把那些互相链接的决定收拢成一份规范文档（/to-spec #<map_issue>），而 to-tickets 把这份规范文档切成曳光弹（tracer bullet）式的实现工单。如果你把地图直接灌进 implement，你就跳过了收拢这一步，丢掉了那些带链接的细节。只有当这件工作最终证明很小时，才直接从地图走到实现。有些人跑的是更短的流水线，并报告说它有效。多出来的两步给你一份明确的规范文档，审查者或同事可以读它，而在你不是独自工作时，这一点更重要。
我的 agent 在一场 wayfinder 会话中途开始写生产代码了。
这是关于这个技能报告得最多的失败，而且它由技能里一个真实的缺口引起。你可以在**备注（Notes）**里覆盖 wayfinder「只规划、不动手」的默认设定。但备注是 agent 写的，所以约束和它的豁免都住在受约束的 agent 自己拥有的文件里。一位用户看着一个 agent 把「这张地图带有执行」写进了它自己的备注里。在后来的会话里，agent 把那行读成了许可，然后在一台线上服务器上构建起来。这个技能对「我指的是默认设定」没有硬性拦截。在它做到这一点之前，任何不是你亲手绘制的地图，都要读一遍备注；把实现放在单独的会话里；任何看起来像构建切片的 wayfinder:task 都当作类型标错处理。
我画了 27 张工单，等我做到第十三张时，其余的已经讲不通了。 这个问题逐字来自一份用户报告，其他人也报告了同样的结果。默认情况下，wayfinder 会做全面规划。当后面的工单建立在被前面工单推翻的假设上时，地图就掉进了批评者指责这个技能的那个瀑布式陷阱。有两件事有帮助。第一，把地图的范围限定在一个有边界的目的地上，而不是整个产品。用户报告说，范围限定在一个定义明确的 epic 上的地图，比一张漫无边际的「实现 V1」表现得更好。目标是交付小的增量，而不是规划一件非常大的事。第二，积极地做原型（prototyping）。路线之所以能保持最新，是因为廉价的具体产物会在实现依赖它之前就把不确定性暴露出来。wayfinder 是「把原型做到极致」，不是「把计划做到极致」。
我可以并行处理好几张工单吗？ 前沿会告诉你哪些工单可以拿，而阻塞边让并行工作在纸面上是安全的。在实践中，一次一张工单是更安全的默认做法。如果你同时做两张质询工单，一场会话可能会问你一个你刚刚在另一场里回答过的问题，因为这些会话不共享上下文（context）。原型工单也有一个已知缺口。一位用户报告说，一个 agent 构建了三种 UI 变体，自己挑了一种，然后关闭了工单。那个选择是你的，而这个技能还没有把这一点说得足够清楚。如果你确实要并行跑工单，先自己审查一遍依赖图。
我必须用 GitHub Issues 吗？ 不必。任何 issue 追踪器都行。GitHub 的支持最好，因为它的原生子 issue 和阻塞关系不必打开地图就能让前沿可见。人们也用 GitLab、Linear、Jira 和本地 markdown。有两个注意事项。在没有原生阻塞关系的追踪器上，wayfinder 会从文本里推断依赖图，而你必须手工纠正它。本地 markdown 把产物放进你的仓库里，这不被推荐，因为存放在仓库里的材料往往会意外地留存下来。开源维护者撞上的是相反的问题（公开追踪器里塞满了 agent 生成的规划工单），所以他们常常还是选择本地 markdown。
质询太累人了。每个问题都有三段那么长。
这是关于 wayfinder 最尖锐的未解决抱怨，还没有人修好它。一位用户这样拆解：冗长本身就造成决策疲劳，而长度掩盖了 agent 为什么要问一个问题，于是随着地图生长，你丢失了从一个决定到下一个决定的链条。这种冗长看起来是当前这组模型（model）的性质，而不是技能本身的性质。用户尝试了两种缓解办法：更低的推理投入级别（effort），以及在你全局 CLAUDE.md 里写一条平实语言的指令。反正要预期在这里动很多脑筋。wayfinder 要求你投入大量思考，而这正是它存在的主要目的，不是缺陷。
我已经关闭的一个决定后来发现是错的。我该编辑旧工单，还是新建一张？ 没有官方指导，而 agent 的默认做法没什么帮助。它倾向于绕过那个坏决定来设计，而不是质疑它，所以你必须自己掌舵。有效的做法是直接了当地告诉 wayfinder 什么变了。然后它会更新地图、修订受影响的工单，并在已关闭的工单上留下评论。你可以在绘制地图的过程中从范围变化里恢复过来。但如果你在设计一张注定要变的地图，那就是范围出了问题的信号。
decision-mapping 去哪了？
就是这个技能。v1.1 把它改名为 wayfinder，你通过 /wayfinder 来调用。「决策地图」是行话，而且也不准确，因为四种工单类型里只有一种本身就是决定。新名字给了这个技能一套前后一致的词汇（目的地、雾区、前沿、地图），而不是在它上面再叠一个生造的词。这个工作单元保留了「决策」一词：wayfinder 的工单是决策工单，这样人们就不会把它读成实现工单。
它生效的标志
- 在任何一张工单存在之前，目的地已经写下来并达成一致。
- 每一张打开着的工单读起来都是一个问句。任何读起来像「构建 X」的工单，要么类型标错了，要么属于地图的下游。
- 你能直接看追踪器就知道哪些工单可以拿，而不必打开地图，因为原生阻塞关系显示了前沿。
- 一场会话解决一张工单，把答案作为解决评论发出来，关闭它，并在地图的迄今为止的决定里加一行。然后它就停下。
- 尚未明确这一节会随着时间缩小。当雾区毕业成一张工单时，它会离开那一节，不会同时出现在两个地方。
- 当开局的那场广度优先质询完全没有发现雾区时，技能会停下，并告诉你这件工作小到可以跳过地图。
- 完成地图的那场会话会把你指向一份规范文档，而不是一个 PR（pull request）。
它在体系中的位置
wayfinder 是一个视情境而定的入口（on-ramp），不是默认的起点。大多数工作仍然从以质询为主导的「主意 → 上线」链开始。当主意大到一场会话装不下时，你才用 wayfinder。它在那条链的 to-spec 处重新汇入，因为理清的地图只交接，不构建。
大部分工作发生在 wayfinder 排期的其他技能里。grilling 和 domain-modeling 解决默认的工单类型，prototype 解决谈话定不下来的工单，而 research 作为子代理运行，这样它的阅读不会进入你的会话。handoff 负责把工作搬进搬出：从一场变得太大的对话搬进地图，以及在一场会话中途出现支线任务时从地图搬出去。其他任何情况，ask-matt 会在整套技能上为你路由。