/wayfinder：AI 编程时代的规划方法论——如何用 Agent 驾驭任意规模的工作

当 AI agent 能帮你写代码了，你发现规划反而成了瓶颈。单次 session 装不下大型项目的全貌，"迷雾"让每一步决策都像赌博。Matt Pocock 的 /wayfinder skill 给出了一套基于软件工程基本原理的解法——不是让工作变小，而是让规划本身可扩展。

---

---

一、问题：为什么现有工具"不够用"

如果你用过 AI coding agent（Claude Code、Cursor、Copilot 等），大概率经历过这样的循环：

• 开一个 session，告诉 AI 你要做什么

• AI 开始工作，进展不错

• 突然撞到一个无法回答的决策点

• 你不知道答案，AI 也不知道

• Session token 用完了，你也不记得前面聊了什么

Matt Pocock 把这种现象叫"迷雾"（fog of war）——起点和终点都大致清楚，中间全是未知。

他自己写过一个叫 Grill with Docs 的 skill，让 AI 通过访谈帮你理清需求、生成 spec。这是个好工具，但它有一个根本性的局限：绑定在单个 session 里。你只能在一次对话中完成所有规划，一但工作超过 context window 的"智能区"（smart zone），你就不得不手动拆分成小块——然后在小块之间丢失上下文。

Matt 的核心洞察：你不知不觉中把要做的东西缩小到"AI 能装下"的大小，而不是做出你想做的东西。

---

二、核心隐喻：绘制一张"决策地图"

Wayfinder 的核心思想很简单——把规划当成绘制地图。

你有一个起点（模糊的想法），一个大致的方向（目的地），但中间全是迷雾。Wayfinder 不是替你一步走到终点，而是帮你：

• 识别当前可以决策的事情（这叫 frontier，前线）

• 标注现在定不了的事情（这叫 fog，迷雾）

• 每做一个决策，就推进一寸前线，地图亮一点

• 等到所有迷雾都散了，路就出来了

这就是为什么它叫 /wayfinder——"寻路人"。

---

三、/wayfinder 的四阶段工作流

Matt 把整个流程打包成了一个单一的 skill，与你用的任何 coding agent 配合：

Phase 1：Chart the Map（绘制地图）

你给 Wayfinder 一个描述——"我想给我的应用加一个 command palette，支持图标选择、图表搜索和复制保存"。Wayfinder 会：

• 自动探索你的代码库结构

• 调用 grilling skill 反过来访谈你（"done 长什么样？要 spec 还是直接实现？"）

• 创建一张地图——这是一个父 issue

• 在父 issue 下创建第一批决策子 tickets

Matt 的实操案例：一个 command palette 需求，Wayfinder 一口气创建了 7 个 tickets，其中 3 个可以立即执行，另外 4 个标记为"迷雾中"——因为必须先完成前面 3 个才能决策。

Phase 2：Work the Frontier（推进前线）

这是使用 Wayfinder 的核心节奏。你逐个处理 ticket：

• 在每一个 ticket 上调用 /wayfinder 

• Agent 自动判断它是 research / prototype / grilling / task

• 处理完成后，结果写回父 issue，地图更新

• 前线移动

  ——新的 ticket 解锁，消失的迷雾让新的决策成为可能

Matt 描述的使用体验：_"OK，这个 ticket 解决了。看看现在打开了什么新 tickets？Frontier 动了多少？"_

Phase 3：Map → Spec（地图转规格）

等所有迷雾清除、前线推进到终点，你得到了一张完整的决策地图。此时：

• 调用 to-spec 命令，把所有决策汇总成一份 spec

• Spec 不是干巴巴的摘要——每个结论都链接回原始 decision ticket

• Agent 后续实现时如果困惑，可以顺着链接追踪一手资料

Matt 的一个 spec 初稿甚至超出了 GitHub issue 的字符上限——可见地图有多密集。

Phase 4：Implement & Clean Up

拿到 spec 后按常规流程走：拆 implementation tickets → 逐 ticket 编码 → Code review。关键区别：代码落地后，spec 直接关掉，不再维护。代码成为唯一真相源。

---

四、四种 Ticket 类型：Wayfinder 的决策工具箱

Wayfinder 不只是"拆任务"——它定义了四种不同类型的 tickets，各自对应不同的认知需求：

类型	做什么	特点
Research	Agent 自行查找信息并汇报	异步执行，你不需要盯着——子 agent 跑完后自动写回结果
Prototype	创建可运行的原型	Matt 专门做了一期视频讲原型的重要性。它是防 Waterfall 的疫苗——在低 fidelity 的规划之后，用高保真原型快速验证关键假设
Grilling	深入讨论某个实现细节	延续 Grill with Docs 的访谈模式，但作用域缩小到一个具体决策
Tasks	现实世界的行动	Agent 做不了的事（联系某人、配置环境），或排在依赖后面的 agent 任务

Blocking relationships（阻塞关系） 是这四种类型的底层逻辑——某些决策天然只能在其他决策之后做出。Wayfinder 自动追踪这种依赖，确保你不会在迷雾里浪费时间。

---

五、/wayfinder vs Grill with Docs：对比

Wayfinder 替代了 Grill with Docs 在 Matt 工作流中的位置，但它不是简单的"升级版"——两者有本质区别：

• 范围

  ：Grill with Docs 是单 session 访谈；Wayfinder 是多 session 编排

• 真相源

  ：Grill with Docs 的 spec 是摘要，你只能信任它；Wayfinder 的 spec 每个结论都有链接指向原始决策讨论，agent 可以溯源

• 适配性

  ：小任务用 Grill with Docs 足够；大项目、"有迷雾"的探索性工作用 Wayfinder

---

六、实现：一切都在 Issue Tracker 里

Wayfinder 最聪明的地方——它不发明新的存储机制，直接利用你已经在用的 issue tracker：

• 一张"地图"就是一个 父 issue

• 子 issues = decision tickets，用 label 区分类型（wayfinder-research、wayfinder-prototype 等）

• 每个 ticket 解决后，结果写回父 issue 摘要

• 支持 GitHub、Linear、JIRA 等任意 issue tracker——只需简单配置

你的决策过程直接变成了 repo 里可搜索、可审计的记录——不用额外搭什么"AI 记忆系统"。

---

七、FAQ：三个最常见的质疑

Q1："这太重了吧？我就改个 bug 也要用？"

Matt 的回答很实在：如果你知道路怎么走，就别用地图。单 session 能搞定的工作不需要 Wayfinder。Wayfinder 专治"我知道要去哪，但不知道怎么去"的情况。

他还举了一个非编程例子——建花园办公室。用 Wayfinder 做 site survey、找承包商、比价调研——这个工具不只服务代码。

Q2："这不是 Spec-Driven Development 吗？"

Matt 对此的立场很鲜明：他的 spec 是非持久的。代码写完后 spec 就关了、删了，不会再回头看。传统 SDD 把 spec 当成活文档持续维护——Wayfinder 的 spec 只是"多 session 工作的导航文件"。到了目的地，地图就可以扔了。

Q3："你创建的那些 tickets 不就是最终的实现 tickets 吗？"

不。Wayfinder 产出的是 decision tickets（决定"做什么"），实现阶段拆出来的是 implementation tickets（执行"怎么做"）。两层分离——规划阶段不要跳到实现细节里。

---

八、五大设计原则

Wayfinder 不只是一个工具——它把一套规划哲学打包进了 skill。五个设计原则：

• Issue Tracker Agnostic

  ：不绑定任何平台——你的 issue tracker 就是 Wayfinder 的存储层

• Decision ≠ Implementation

  ：两种 ticket 不能混淆，分别对应规划与执行

• Non-Persistent Specs

  ：Spec 是消耗品，代码即真相——不需要维护两份文档

• Fog-Aware

  ：承认不确定性是第一原则——不要求你在不清楚的时候强行决策

• Primary Source Linking

  ：可溯源性是信任的基础——spec 中的每句话都有出处

---

总结：为什么 /wayfinder 值得关注

Matt Pocock 做了一件聪明的事：他没有发明一套新的 AI 工作流，而是把软件工程里验证过的规划方法论（任务分解、探索性规划、渐进式决策）适配到了 AI agent 时代。

Matt 说了一句话，我印象很深：

"There is no more fun feeling than starting a new Wayfinder session and knowing that you're going to see something awesome, but not quite knowing how you're going to get there."

"最爽的感觉就是：开始一个新的 Wayfinder session，知道自己会看到很棒的东西，但还不知道怎么抵达。"

传统 AI 使用方式给不了你这个——一个能容纳不确定性的框架。它让你敢于开始不确定的事，也让 AI 能陪你一起探索，而不是逼你在没想清楚的时候就做决策。

---

素材来源

• 原视频：Matt Pocock — /wayfinder: Nothing is too big to plan anymore

• 本文基于视频内容深度改写，非逐字转录