Wayfinder：当 AI 遇到"战争迷雾"，如何绘制大型项目的决策地图？

"

前言：当 AI 碰到"超大任务"

想象一下，你给 AI 下达这样一个任务：

"帮我们从零构建一个完整的电商平台，包括用户认证、商品管理、购物车、支付集成、订单处理、库存管理、物流追踪、数据分析、推荐系统、客服系统..."

对于人类开发者来说，这是一个需要数月的大型项目。对于 AI 来说，这更是一个超出单次会话能力范围的任务。

GitHub 上有个叫 Matt Pocock 的开发者，在他的 skills 项目中提出了一个有趣的解决方案——Wayfinder。

"Plan a huge chunk of work — more than one agent session can hold — as a shared map of decision tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear."

翻译：将大型工作规划为 issue tracker 上的决策票据地图，一次解决一个，直到路径清晰。

今天，我们就来分析这个"地图绘制式"的工作方法。

---

一、Wayfinder 的核心哲学

1.1 Plan, Don't Do（规划，不执行）

Wayfinder 的第一条原则：

"Wayfinder is planning by default: each ticket resolves a decision, and the map is done when the way is clear."

默认只规划，不执行。

每个票据解决的是一个决策，而不是交付一个功能模块。当地图上的路径清晰时，规划工作就完成了。

为什么？

因为大型任务往往被"迷雾"包裹——你不知道从起点到终点之间有多少未知的问题需要解决。

传统方法的困境：

• 直接开始编码 → 发现缺少关键信息 → 停下来调研 → 重新设计 → 返工
• 试图一次性规划所有细节 → 信息过载 → 规划过时 → 浪费时间

Wayfinder 的方法：

• 先绘制"低分辨率地图" → 只标注已知决策点 → 逐个解决 → 迷雾逐步散去 → 路径自然清晰

1.2 Decision Tickets，Not Task Tickets

关键区别：

Task Ticket（任务票据）：

实现用户登录功能
- 设计登录表单
- 实现认证逻辑
- 集成数据库

Decision Ticket（决策票据）：

选择认证方案
- 选项 A：Session-based auth
- 选项 B：JWT token
- 选项 C：OAuth 2.0

Wayfinder 关注的是决策，而不是任务。

为什么？

因为决策决定方向，任务只是执行。如果在错误的方向上快速执行，只会加速偏离目标。

---

二、共享地图：在 Issue Tracker 上绘制决策网络

2.1 The Map：一张 Issue，整张地图

Wayfinder 的核心 artifact 是一张标记为 wayfinder:map 的 issue：

## Destination

<抵达终点是什么样子——规格、决策或变更。一两行；每次会话在选票据前都要对照它>

## Notes

<领域；每次会话应咨询的 skills；本次努力的持续偏好>

## Decisions so far

<!-- 索引——每个已关闭票据一行：足以判断相关性，然后点击链接查看详情 -->

- `<已关闭票据标题>` — <答案摘要>

## Not yet specified

<!-- 见"Fog of war"：范围内但还无法票据化的迷雾；随前沿推进而升级 -->

## Out of scope

<!-- 见"Out of scope"：超出目的地的工作；已关闭，永不升级 -->

这张地图是索引，不是存储：

• 它列出已做出的决策
• 指向持有详情的票据
• 每个决策只存在一个地方——它的票据

2.2 Refer by Name：用名称，不用 ID

Wayfinder 的一条硬性规定：

"Refer to it by that name, never by a bare id, number, or slug."

反例：

已解决：#42, #43, #44
阻塞：#45 → #46

正例：

已解决：[选择认证方案](#42), [设计数据库架构](#43), [确定 API 风格](#44)
阻塞：[实现登录表单](#45) → [集成认证中间件](#46)

为什么？

因为名称可读，ID 不可读。人类阅读地图时，应该能一眼理解每个决策的含义，而不是被迫点开每个 issue 查看。

2.3 Fog of War：战争迷雾

Wayfinder 的核心概念——故意不完整：

"The map is deliberately incomplete: don't chart what you can't yet see."

为什么？

因为在大型项目初期，你根本看不到所有需要解决的问题。

案例：构建电商平台

初期地图（迷雾重重）：

## Destination

一个可运行的电商平台 MVP

## Decisions so far
（空）

## Not yet specified

- 支付集成方案选择
- 库存管理策略
- 物流对接方式
- 数据分析范围
- 推荐算法选型

中期地图（迷雾部分散去）：

## Decisions so far

- [选择支付集成方案](#1) — 使用 Stripe
- [确定库存管理模式](#2) — 先用简单计数，后期优化

## Not yet specified

- 物流对接方式
- 数据分析范围
- 推荐算法选型

后期地图（路径清晰）：

## Decisions so far

- [选择支付集成方案](#1) — 使用 Stripe
- [确定库存管理模式](#2) — 先用简单计数，后期优化
- [确定物流方案](#3) — 暂不集成，手动导出订单
- [界定数据分析范围](#4) — 仅基础统计，延后推荐系统

## Not yet specified
（空）

判断标准：

"The test is whether you can state the question precisely now — not whether you can answer it now."

• 能精确表述问题 → 创建票据
• 无法精确表述 → 留在 Not yet specified

---

三、四种票据类型

Wayfinder 定义了四种决策票据，每种都有明确的使用场景：

3.1 Research（研究）—— AFK（Agent 独自完成）

用途：阅读文档、第三方 API、本地资源（知识库）以获取决策所需的事实。

示例：

## Question

Stripe 支持哪些支付方式？是否支持中国用户的支付宝/微信支付？

解决方式：使用 /research subagent 调研

何时使用：当需要当前工作目录之外的知识时

3.2 Prototype（原型）—— HITL（Human-in-the-Loop）

用途：通过制作廉价、粗糙、具体的原型来提高讨论的保真度。

示例：

## Question

登录页面的交互流程应该如何设计？

解决方式：使用 /prototype skill 创建交互原型

何时使用：当"它应该看起来怎样"或"它应该如何表现"是关键问题时

3.3 Grilling（质询）—— HITL

用途：通过 /grilling 和 /domain-modeling skills 进行对话，一次一个问题。

示例：

## Question

用户认证失败时，应该如何向用户展示错误信息？

解决方式：与用户对话问答

何时使用：默认情况——大多数决策都适合这种方式

3.4 Task（任务）—— HITL 或 AFK

用途：在做出决策之前必须完成的手动工作。

示例：

## Question

获取 Stripe API 密钥并配置测试环境

解决方式：Agent 独自驱动时提供精确清单（AFK），或与人类协作完成（HITL）

何时使用：

• 注册服务以便评估其 API
• 配置访问权限
• 迁移数据以便查看其结构

关键点：这是唯一一种"做"而不是"决定"的票据类型，它的存在是为了解除决策的阻塞。

---

四、Out of Scope：明确边界

4.1 什么是 Out of Scope？

Fog of War 聚集朝向目的地。超出目的地的工作是 Out of Scope。

示例：

Destination：构建一个电商 MVP，支持商品浏览和支付

In Scope：

• 商品展示
• 购物车
• 支付集成
• 订单管理

Out of Scope：

• 推荐系统
• 数据分析平台
• 社交分享功能
• 多语言支持

4.2 如何处理 Out of Scope？

Wayfinder 的规定：

"Out-of-scope work never graduates — the frontier stops at the destination."

处理方式：

1. 地图创建阶段：直接排除，不创建票据
2. 执行阶段发现：关闭票据，在 "Out of scope" 部分记录

示例：

## Out of scope

- [推荐系统架构](#12) — 超出 MVP 范围，延后到 v2.0
- [多语言支持方案](#13) — 当前仅支持中文，后期评估

为什么？

因为范围固定，方向清晰。如果不断添加"nice-to-have"的功能，地图永远无法完成。

---

五、工作流程：绘制与执行

5.1 Chart the Map（绘制地图）

触发条件：用户提出一个模糊的大型想法

步骤：

1. 命名目的地

   • 运行 /grilling 和 /domain-modeling session
   • 明确这张地图要抵达什么终点

2. 映射前沿

   • 再次使用 /grilling，这次是广度优先
   • 横向扫描整个空间，而非深入任何一条线
   • 找出所有开放决策和当前可执行的第一步

3. 创建地图

   • 创建标记为 wayfinder:map 的 issue
   • 填充 Destination 和 Notes
   • Decisions-so-far 保持空白
   • 将迷雾草图写入 Not yet specified

4. 创建票据

   • 为当前可指定的决策创建子票据
   • 分两步：先创建所有票据（获取 ID），再连接阻塞关系

5. 启动研究 subagents

   • 为每个 research 票据启动 /research subagent
   • 并行处理，捕获发现

6. 停止

   • 绘制地图是一次会话的工作
   • 手动解决任何问题

关键点：如果广度扫描后发现没有迷雾——路径已经清晰——你不需要地图。直接执行即可。

5.2 Work through the Map（执行地图）

触发条件：用户提供地图（URL 或编号）

步骤：

1. 加载地图

   • 读取低分辨率视图，不加载每个票据的详情

2. 选择票据

   • 如果用户指定，使用指定的
   • 否则，按顺序选择第一个前沿票据
   • 声明它：在开始任何工作前分配给自己

3. 解决它

   • 按需放大：获取相关或已关闭票据的完整内容
   • 调用 ## Notes 中命名的 skills
   • 有疑问时使用 /grilling 和 /domain-modeling

4. 记录解决方案

   • 发布答案作为决议评论
   • 关闭 issue
   • 在地图的 Decisions-so-far 中追加上下文指针

5. 更新地图

   • 添加新浮现的票据（创建-然后-连接）
   • 将答案使可指定化的迷雾升级为票据
   • 从 Not yet specified 中清除已升级的部分
   • 如果发现票据超出目的地，排除出范围

关键点：用户可以并行运行未阻塞的票据，预期其他 session 会并发编辑 tracker。

---

六、Wayfinder 的核心价值

6.1 渐进式揭示

传统规划：

• 试图一次性规划所有细节
• 信息过载
• 规划过时

Wayfinder：

• 只规划当前可见的决策
• 逐个解决，迷雾逐步散去
• 每个决策为下一个决策提供上下文

6.2 共享地图

优势：

• 可视化：Issue tracker 提供原生 UI 展示阻塞关系
• 协作：多个 agent session 可以并行工作
• 可追溯：所有决策都有历史记录
• 可恢复：中断后可以从地图恢复

6.3 明确边界

Fog of War：

• 范围内的未知领域

Out of Scope：

• 范围外的明确排除

效果：

• 防止范围蔓延
• 防止永远无法完成的地图
• 明确 MVP 边界

6.4 决策驱动

核心思想：

• 每个票据解决一个决策
• 地图完成 = 路径清晰
• 然后才开始执行

价值：

• 避免在错误方向上快速执行
• 确保每个任务都有明确目的
• 减少"为了做而做"的浪费

---

七、给我们的启示

7.1 AI 编程的"地图哲学"

Wayfinder 的启示：

• AI 不应该"一键生成"整个系统
• AI 应该先帮你绘制"决策地图"
• 然后逐个解决决策，路径自然清晰

类比人类开发：

• 资深架构师不会直接写代码
• 而是先画出"技术决策地图"
• 然后指导团队逐个解决

7.2 大型项目的"迷雾管理"

Wayfinder 的智慧：

• 不要试图一次性看清所有问题
• 接受"迷雾"是大型项目的常态
• 逐步揭示，比一次性规划更有效

类比军事行动：

• 没有将军会在战前完全看清战场
• 而是先绘制"战略地图"
• 然后逐步推进，迷雾自然散去

7.3 Issue Tracker 的新用途

传统用途：

• Bug 跟踪
• Feature request
• Task management

Wayfinder 的创新：

• 决策地图
• 知识索引
• 协作白板

7.4 Plan vs Do 的平衡

Wayfinder 的选择：

• 默认只规划
• 只有明确需要时才执行

核心原则：

• 规划决定方向
• 执行只是沿路前行
• 方向错误 = 越走越偏

---

八、总结：地图决定路径，路径决定终点

Wayfinder 的核心哲学：

"Wayfinding is about finding that way, not charging at the destination."

翻译：Wayfinding 是关于找到路径，而不是冲向终点。

给我们的三点启示：

1. 接受迷雾：大型项目初期，迷雾是常态。不要试图一次性看清所有问题。

2. 绘制地图：先绘制"低分辨率地图"，只标注可见的决策点。逐个解决，迷雾自然散去。

3. 明确边界：通过 Fog of War 和 Out of Scope 明确范围，防止地图永远无法完成。

AI 编程的未来：

• 不是 AI 直接"一键生成"
• 而是 AI 先帮你绘制"决策地图"
• 然后逐个解决，路径自然清晰
• 最后才开始执行

Wayfinder 的终极价值：

• 它不让 AI 替代人类思考
• 而是帮助人类更好地思考
• 通过共享地图，让复杂变得可视
• 通过渐进揭示，让混乱变得有序

---

参考资源：

• Matt Pocock Skills 项目：https://github.com/mattpocock/skills
• Wayfinder Skill：https://github.com/mattpocock/skills/blob/main/skills/engineering/wayfinder/SKILL.md

---

如果你觉得这篇文章有帮助，欢迎点赞、转发，让更多人了解这种"地图绘制式"的工作方法！