/wayfinder 技能

它的作用

wayfinder 承担对一个智能体来说太大的任务 会话 ——一个想法，其 destination 你能说出名字、却还看不清路线的——并把它绘制成共享的 map of 决策任务 在你的 issue 追踪器上，然后逐个解决它们，直到道路畅通。

它规划，不执行。每个任务装着一个问题，其解决是一个决策，而不是一段要执行的构建切片；当去构建之前再无决策可做时，地图就完成了。这一条规则正是 wayfinder 任务与普通实现 ticket，而这是智能体违反最多的规则。当地图清空时，wayfinder 交接；它不会继续进入代码。

何时使用

你通过输入 /wayfinder ——这个 agent 不会自动调用它。

它是套装里最重、最密的流程，所以触发条件很窄：任务必须真的比一个智能体会话能装下的更大，通往目的地的路线必须模糊。分工是干净的： /grill-with-docs 用于单会话规划， /wayfinder 用于多会话规划。

全新项目不是必需条件。Wayfinder 经常用于遗留和半成品代码库，而且在那种地方可以说更敏锐，因为很多迷雾是「这里已经成立的是什么」而不是「我们该做什么」。

前置条件

地图及其任务住在仓库的 issue 追踪器上，所以 wayfinder 需要 setup-matt-pocock-skills 写下的。那一步会写一个「Wayfinding 操作」部分，描述地图、子任务、阻塞边界和前沿查询如何在 GitHub、GitLab 或本地 markdown 中表达。Wayfinder 通过你 CLAUDE.md / AGENTS.md 而不是固定路径；完全没有配置追踪器时，它退回本地 markdown 文件。

追踪器不是装饰。阻塞关系正是让前沿在追踪器自己的 UI 中可视化呈现的东西，而没有原生依赖链接的追踪器——比如自托管 Gitea——会让 wayfinder 降级为从地图文本推断阻塞项，这能用但需要更密切的监督。

地图、迷雾与前沿

这个 map 是一个标记为 wayfinder:map；它的任务就是它的子 issue。它是一个 索引，不是存储 ——一个决策只住在一个地方，它的任务里，而地图只摘录它并链接。会话以低分辨率加载地图，按需放大到单个任务，这正是让地图不断增长、而不让每个会话为它的全部历史付费的原因。

四样东西住在上面：

• 目的地 ——走到这张地图尽头是什么样子。为它命名是制图的第一件事，早于任何任务存在，因为目的地定下每个任务被衡量的范围。
• 迄今的决策 ——每个已关闭任务一行，每行链接到细节真正所在的地方。
• 尚未规格化 ——这个 战争迷雾。你能预见其到来、却还无法清晰表述的决策。区分迷雾与任务的检验标准是：你能否精确地陈述这个问题 now，而不是你能否回答它。解决一个任务会清掉它前方的迷雾，并把现在已可规格化的一切升级为新的任务。
• 范围外 ——被判定超出目的地的工作。迷雾只会聚集在 toward 目的地，所以范围外的工作被关闭，永远不会升格。

这个 frontier 是开放、未阻塞、无人认领的任务——已知的边界。会话通过在做任何工作前把任务分配给自己来认领它，所以受派人 is 论断，并发会话会跳过它。任务全程按名称引用，从不裸用 #42；一堆 issue 编号在叙述中难以阅读。

四种决策任务类型

每个任务都带一个 wayfinder:<type> 标签，并且要么是 人机协同（HITL） ——与一个为自己发声的人合作过——或 AFK，完全由智能体驱动。一个 人机协同（HITL） 任务只能通过实时往来解决；一个自问自答的智能体 追问审视 问题破坏了它。

task 是唯一会 does 而不是决定，它靠解除决策阻塞来挣得位置——绝不靠交付目的地的一块。这是实践中出错最多的类型：智能体把它理解为实现步骤，开始在地图内写产品代码。

研究是 一个会话一个任务.

常见问题

这与 /grill-with-docs？我应该先开始哪一个？ 是会话数，不是项目规模。 /grill-with-docs 是单会话规划；wayfinder 是多会话规划。如果你能在一次对话中装下全部， 追问审视 是更便宜更好的工具，而 wayfinder 对那种情况确实更慢更密。社区沉淀出的简写：只有当工作装不进单个会话时，wayfinder 才有意义。这是 wayfinder 被问得最多的问题，而且它一直被问，因为描述没有告诉你自己的任务在那条线上处于什么位置——你必须自己判断会话数。

当它问「目的地」时，指的是这次会话的结束还是万事的结束？ 整个地图——整张地图的目的地，而不仅仅是初始会话。这个问题读起来有歧义，因为 wayfinder 按定义就是多会话工具，所以以会话为范围的答案永远没有意义。典型的目的地是一个 spec 要交接、一个在规划开始前要锁定的决策、一个概念验证，或一个原地进行的改动如数据迁移。

地图已清空。为什么我还需要 /to-spec and /to-tickets ——wayfinder 不是已经写了规格说明并制作了任务吗？ 不。Wayfinder 的任务是决策任务，地图关闭时它们也都关闭了。剩下的是满是关联决策的地图，它不是构建计划。 to-spec 把那些相互关联的决策压缩进一份规格说明—— /to-spec #<map_issue> ——以及 to-tickets 把它切成曳光弹实现任务。把地图直接循环进 implement 跳过折叠，扔掉关联的细节。只有当任务结果确实很小时才直接去实现。确实有人运行精简版流水线并报告有效；多出来的两步买来一份审查者或同事可读的明确规格产物，越不单打独斗越重要。

我的智能体在 wayfinder 会话中途开始写生产代码。 该技能被报告最多的失败，背后有一个真实漏洞。Wayfinder「规划，不做」的默认可以在地图的 笔记 ——但 Notes 由智能体书写，所以约束和它的豁免住在被约束方拥有的同一个文件里。一位用户看着智能体把「此地图承载执行」写进它自己的 Notes，然后在后来的会话里把它读回来当作自己的许可，在真实服务器上构建。技能内没有对「我是说默认」的硬性阻止。在那之前：阅读任何不是你亲手绘制的地图上的 Notes，把实现留在它自己的会话中，并把任何 wayfinder:task 看起来像构建切片被误打。

我绘制了 27 个任务，当我画到第十三个时，其余的已经不再有意义了。 一个真实且被反复报告的结果，逐字引自一份实地报告。Wayfinder 的默认本能是全面规划，而一张后部任务建立在早期任务已推翻的假设之上的地图，正是该技能被指控的瀑布陷阱。有两件事在反制它。把地图范围限定在一个有界的目的地，而不是整个产品——实践者们一致报告，限定在单个明确 epic 的地图比漫无边际的「实现 V1」表现更好，而且一开始规划非常庞大的东西就不是目标——交付小增量才是。而 prototype 激进地：这条路线保持当下的全部原因，就是不确定性在实现依赖它之前，就被便宜的具象产物冲刷掉了。Wayfinder 是「原型拉满」，不是「规划拉满」。

我能并行处理几个任务吗？ 前沿为展示你可拿取的东西而建，阻塞边界的存在让并行工作在纸面上安全。实践中一次一个是更安全的默认。同时处理两个审问任务的用户，会在一个会话中被问刚在另一个会话答过的问题，因为会话之间不共享 context。原型任务上还有一个已知缺口：有报告称智能体构建了三个 UI 变体、自己选了一个并关闭了任务——选择权是你的，而该技能目前没有把这一点说得足够响亮。如果你确实要并行运行，请先自己检查依赖图。

我必须使用 GitHub Issues 吗？ 不——任何 issue 追踪器都可以。GitHub 是支持最好的路径，因为它的原生子 issue 和阻塞关系让前沿无需打开地图即可见；GitLab、Linear、Jira 和本地 markdown 都有人用。两个诚实的提醒：没有原生阻塞的追踪器意味着依赖图从文本推断，需要手动修正；而本地 markdown 把产物放进你的仓库，这并不推荐——把这类材料存在仓库里容易导致意外持久化。开源维护者遇到相反的问题——公共追踪器被智能体生成的规划任务塞满——却往往还是选择本地 markdown。

审问让人精疲力竭。每个问题都有三段长。 这是对 wayfinder 最尖锐的现行抱怨，尚未解决。一位用户给出的剖析：冗长本身导致决策疲劳，而长度剥掉 why 一个问题正在被提出，所以随着地图变长，你失去了决策到决策的链条。这种冗长看起来是当前这套 models 而不是技能的，而且没有修复落地。流传中的实践者缓解措施：运行更低的 推理投入，并把一条平实语言的指令放进你的全局 CLAUDE.md。无论如何，请做好在这里认真思考的准备——wayfinder 要求你投入的思考量不是缺陷，那正是它的主要用途。

一个我已经关闭的决策被证明是错的。我应该编辑旧任务还是新建一个？ 没有官方指引，而智能体的本能没有帮助：它倾向于绕开坏决策设计而不是挑战它，所以你必须手动掌舵。真正有效的是直白地告诉 wayfinder 什么变了——它会更新地图、修订受影响的任务，并在已关闭的任务上评论。地图中途的范围变化是可恢复的。一张你 designed 要改动的东西，是范围界定上的坏味道。

原来的 decision-mapping 去哪了？ 它就是本技能，改名为 wayfinder 在 v1.1 中，以 /wayfinder。「决策地图」是行话，而且也不准确，因为四种任务类型中只有一种是真正的决策。重新框架给了技能一套连贯词汇——目的地、战争迷雾、前沿、地图——而不是叠在上面的发明术语。不过单位保留了「决策」这个词： 决策任务 正是 wayfinder 任务的叫法，为的是阻止人们把它读成实现任务。

做到以下就算成功

• 目的地被写下并达成一致，早于任何任务存在。
• 每个开放的任务读起来都是一个问题。任何读起来像「构建 X」的任务，要么是打错了，要么属于地图的下游。
• 你可以看着追踪器，不用打开地图就知道哪些任务可拿——那就是前沿通过原生阻塞在自我呈现。
• 一个会话解决一个任务，把答案作为解决评论发布，关闭它，并在地图的 迄今的决策。然后它停下来。
• 尚未规格化 随时间缩小。一片升格为任务的迷雾会从该部分消失，而不是同时存在于两处。
• 当开场广度优先的审问完全没发现迷雾时，技能停下来告诉你任务小到可以跳过地图。
• 完成地图的会话把你递向规格说明，而不是 pull request。

在流程中的位置

wayfinder 是一个 情境入口，而不是默认入口。以审问为起点的想法 → 交付链条仍然是多数工作的起点；当想法大到一次会话装不下时，你才爬上 wayfinder，而它会在这条链的 to-spec，因为已清空的地图选择交接而非继续构建。

底层上，它大多是穿着 wayfinder 排程外衣的其他技能： 追问审视 and domain-modeling 解析默认任务类型， prototype 解决靠讨论解决不了的任务，并 research 作为 子智能体 所以它的阅读永远不会落在你的会话中。 handoff 是进出的桥梁——从一场自己膨胀过大的对话进入地图，当会话中途出现支线任务时从地图出来。其他情况， ask-matt 路由整个技能集。