Lesson 0016 · Engineering · 只能人启动（user-invoked）· 流程课

wayfinder：给太大太雾的任务画一张决策地图

你接手了一件真正大的事：把单体应用迁成事件驱动，或者从零做一个全新产品。 终点你隐约看得见，但从这里到终点的路完全被雾罩着—— 打开一个 agent 会话想直接开写，却连第一张工单都列不出来， 因为每个想写的任务下面都挂着三个还没人回答的问题。 /wayfinder 就是为这一刻准备的：它把这件「一个 agent 会话装不下」的事， 画成工单系统上的一张共享地图——一个父 issue 挂着一排 决策票（Decision ticket，装的是问题，不是要做的活）， 然后一次会话只解决一张票，直到雾散、路清。 它是 22 个已发布 skill 里最重的一条流程，也是只能由人启动的： AI 永远不会自己伸手拿它。学完这节课，你能说出两种调用模式各自的步骤、 四种票型谁来解、它会往工单系统写什么、雾散后交给谁， 以及行为不对时该改哪份文件的哪一段。

1. 它在整个系统里站在哪

0001 把 22 个 skill 分成配置层、编排层、纪律层。wayfinder 在编排层， 而且它是一条 on-ramp（入口匝道：一种产生工作、然后并入主流程的起点）， 和 triage（别人提来的 bug 与需求）、diagnosing-bugs（有东西坏了） 并列三条入口之一。它的入口条件最苛刻：一个巨大而模糊的努力—— ask-matt 的原话是 greenfield project 或 huge feature build， 大到、雾到一个会话装不下，并称它是「这里最耗认知的一条流程」 （the most cognitively demanding flow here）。

它和主流程的关系是「更上游」。主流程是 grill-with-docs → to-spec → to-tickets → implement， 前提是想法已经能在一个会话里聊透。当想法大到连「聊透」这一步都装不下时， 先走 wayfinder：它不交付任何产品代码，只交付决策； 等地图上的雾散尽，再从 to-spec 并入主流程。 ask-matt 特意划了分界：grill-with-docs 磨利的是「一个会话装得下」的想法， wayfinder 服务的是「装不下」的那类。

调用方式一句话说死：只能人启动。SKILL.md 的 frontmatter 里写着 disable-model-invocation: true，旁边的 agents/openai.yaml 里写着 policy.allow_implicit_invocation: false——两处一道把门关死： 你不输入 /wayfinder，它就不存在；AI 不会因为你任务大就自动加载它， 别的 skill 也不能用自然语言句子把它拉进来（0005 讲过的 prose 调用对它不适用）。 这是故意的：画地图要往工单系统里写一堆父 issue、子 issue、阻塞边， 这么重的副作用必须由人明确下令。

地图：0001 系统地图（wayfinder 行与「只能人启动」分组）· 路由规则：ask-matt/SKILL.md 的 On-ramps 一节 · 启动开关：wayfinder/SKILL.md frontmatter 与 wayfinder/agents/openai.yaml

2. 什么时候用它、什么时候换别的

docs 页给的判定句很具体：当一件工作 more than one agent session can hold （一个 agent 会话装不下），而且你能感觉到这件事的形状、却还没法把它写成 spec 或计划—— 用它。两个条件要同时成立：光是「大」不够（大而清楚直接去 to-spec）， 光是「模糊」也不够（模糊但小，一场 grill-with-docs 就能聊透）。

2.1 前置条件：工单系统得先接好线

地图和票都住在仓库的 Issue tracker（工单系统）上——这个词按 CONTEXT.md 的定义，指托管这个仓库 issue 的工具： GitHub Issues、GitLab Issues，或者本地 .scratch/ 目录下的一套 markdown 约定。 所以 wayfinder 假定 setup-matt-pocock-skills（0002）已经跑过： setup 会在 docs/agents/issue-tracker.md 里种下一节 「Wayfinding operations」，写清这个仓库的地图、子票、阻塞、前线查询具体怎么表达。 如果这份配置不存在，wayfinder 的 SKILL.md 让自己先去跑 setup； 如果连 tracker 都没提供，就退回本地 markdown 工单系统的默认约定（第 9 节细讲）。

判定与前置：docs/engineering/wayfinder.md 的 When to reach for it 与 Prerequisites 两节 （aihero.dev/skills-wayfinder）· 配置来源：setup-matt-pocock-skills/SKILL.md

3. 核心词汇：先把六个词说明白

wayfinder 自带一套独立词汇，CONTEXT.md 已经把其中最关键的 Decision ticket 收进了全仓库统一的领域语言。下面这张表按 SKILL.md 与 CONTEXT.md 的原文把每个词说成人话；后面的每一节都只用这套词。

权威原文：wayfinder/SKILL.md 开篇、The Map、Ticket Types、Fog of war 各节 · 领域词：CONTEXT.md 的 Decision ticket 条

4. 地图的身体：五个固定小节

地图正文是「整张地图的低分辨率视图」，每个会话开工时加载一次。它固定五个小节， 开放票不列在里面——它们是开放的子 issue，靠查询找到：

## Destination
<这张地图要找的终点长什么样——spec、决策或变更。一两行；每个会话选票前先朝它对齐>

## Notes
<领域；每个会话都应该查阅的 skill；这次努力的长期偏好>

## Decisions so far
<!-- 索引——每张已关闭的票一行：足够判断相关性的一行摘要，细节点链接进票里看 -->
- [<已关闭票的标题>](链接) — <答案的一行摘要>

## Not yet specified
<!-- 战争迷雾：在范围内、但还没法开票的朦胧问题；随前线推进毕业 -->

## Out of scope
<!-- 被明确判在这次努力之外的活；已关闭，永不毕业 -->

三个小节各有一条容易违反的纪律，先在这里立住，第 6、8 节会反复用到：

• Decisions so far 只 gist 不复述：一个决策恰好住在一个地方——它的票里。 地图这行只是「足够判断相关性 + 一个链接」，想看细节就 zoom（变焦）进票。
• Notes 有实权：它写这次努力每个会话都该查的 skill 和长期偏好； 它还是唯一能推翻「plan, don't do」默认值的地方（第 5 节末讲）。
• 名字是给人读的，编号不是：SKILL.md 的 Refer by name 一节规定—— 在一切人读的东西里（叙述、Decisions so far），票用标题名字指代， 名字包住链接；编号和 URL 躲在名字里面，绝不单独站出来。 一面 #42, #43, #44 的墙没人读得下去，名字一眼能读。

权威原文：wayfinder/SKILL.md 的 The map body、Refer by name 两节

5. 四种票型：谁来解决这张票

每张票挂一个 wayfinder:<type> 标签，取值只有四个： research、prototype、grilling、task。 分型先看 HITL 还是 AFK，再看关键问题是什么。铁律先立： HITL 票只能通过和真人的实时交流来解决——agent 绝不替人站位子； SKILL.md 的原话是「一个自问自答的 grilling agent 已经破坏了这条规矩」。

5.1 Task 是唯一的例外，和它的资格证

wayfinder 的总原则是 Plan, don't do：每张票解决一个决策， 地图在「没什么还要决定的」那一刻就算完工——产出决策，不产出交付物。 「干脆把活干了吧」的冲动，通常就是信号：你已经摸到地图边缘，该交接了。 Task 型票是这套纪律里唯一「做」而不是「决定」的票型， 它挣到存在资格的理由只有一个：它解锁一个决策，而不是交付目的地。 如果一件「活」本身就是目的地的一部分，它不该出现在地图上——那是主流程的实现票。

整条 Plan, don't do 纪律本身也可以被推翻，但只有一个入口： 这次努力的 Notes 一节里写明「把执行也带进地图」。没有这句话，就老老实实产出决策。

权威原文：wayfinder/SKILL.md 的 Ticket Types、Plan, don't do 两节

6. 战争迷雾与范围之外

地图是故意不完整的：看不见的东西不要画。前线的票之外就是雾—— 那些你说得出「肯定要面对」、却还钉不下来的决策，因为它们挂在还没回答的问题上。 雾写在地图的 Not yet specified 一节：可以写得潦草也可以写得完整， 它同时是给协作者看的路标——这次努力在往哪走。

6.1 雾还是票？看能不能「说」，不看能不能「答」

• 问题已经锋利 → 开票，哪怕它现在被阻塞、动不了手。
• 还说不锋利 → 留在 Not yet specified。不要预先把雾切成票大小的片：雾比票粗，等前线走到它跟前，一块雾可能毕业成好几张票，也可能一张都不剩。

毕业（graduation）是雾离开的唯一正路：解决一张票 → 清掉它前方的雾 → 把现在能写清的部分开成新票 → 把已毕业的那块从 Not yet specified 划掉， 让它从此只以新票的形式存在。如此一次一张，直到通往目的地的路清楚、再没有票剩下。

6.2 范围之外：永不毕业的另一种「模糊」

雾只朝目的地聚集；目的地定死了范围，所以越过目的地的活不是雾， 不许进 Not yet specified。它有自己专属的一节：Out of scope—— 你有意识地判在这次努力之外的工作。落到这里是「范围」问题，不是「清晰度」问题。 范围之外的活永不毕业：前线到目的地为止；它要回来，只有一种可能—— 目的地被重画，而那是作为一次新的努力重新开始，不是恢复旧地图。

已经开出来的票被发现越界（画图时误判，或被某个答案暴露）：关掉它—— 关闭的票毫无歧义地不在前线上——然后在 Out of scope 一节留一行：摘要、 为什么越界、链到那张关闭的票。它不进 Decisions so far， 因为那里记录的是真正走过的路；划一条范围边界不是路上的一步。

权威原文：wayfinder/SKILL.md 的 Fog of war、Out of scope 两节 · 对照：0001 系统地图 的写入清单

7. 模式一：画地图（Chart the map）

触发方式：你带着一个松散的想法输入 /wayfinder。 SKILL.md 的 Invocation 一节把两种模式写得像操作手册，画图模式一共六步：

注意第 2 步的「无雾出口」：0001 的系统地图专门把它收进了分支表里—— 画图时发现其实没雾，是 wayfinder 的合法结局之一，不是失败。 它替你省下的正是「为一个下午的活维护一张几周的父 issue」。

权威原文：wayfinder/SKILL.md 的 Invocation / Chart the map · 无雾分支：0001 系统地图 · 研究票动机：docs/engineering/wayfinder.md

8. 模式二：走地图（Work through the map）

触发方式：你带着一张地图（URL 或编号）输入 /wayfinder。 票可带可不带——不带，就是「你替我挑下一个决策」，不是用户挑。一共五步：

1. 载地图——低分辨率视图（第 4 节那五个小节），不是每张票的正文。
2. 选票——用户点了名就用点名的；否则按顺序拿前线第一张。 然后认领（claim）：开工之前，先把票指派给驱动这张地图的开发者。 这个 assignee 就是认领本身：一张开放、没指派人的票就是没人认领的。
3. 解决——按需变焦（zoom）：相关的或已关闭的票，正文要用到了才去拉全文； 调用地图 Notes 一节点名的 skill；拿不准，就用 /grilling 和 /domain-modeling。
4. 记录解决：把答案作为解决评论发出去 → 关闭 issue → 在地图的 Decisions so far 追加一行上下文指针（名字包链接加一行摘要，第 4 节的纪律）。
5. 维护地图：把新浮出水面的票开出来（还是先建后接）； 把答案已经能写清的雾毕业成票，并把已毕业的部分从 Not yet specified 划掉； 如果答案暴露某张票——这张或别的——越过了目的地，按第 6 节「范围之外」处理（关掉加留行）， 而不是在路上顺手解决它；如果这个决定推翻了地图的其它部分，更新或删掉那些票。

8.1 并发是常态，所以 claim 必须是第一笔写入

SKILL.md 最后一句提醒你：用户可能并行跑多张未阻塞的票， 所以要预期别的会话正在同时改这个工单系统。 这就是认领顺序的理由——先指派、再开工，后来的会话看到 assignee 就会跳过这张票。 反过来的顺序（做完再指派）等于邀请两个会话解同一张票。

8.2 和 handoff 的对照：跨会话的记忆住在哪

0006 讲的 /handoff 是把一段对话压缩成 markdown 文件、搬进新会话； wayfinder 不需要它，因为这次努力的记忆不住在对话里—— 它就住在工单系统上：地图是低分辨率索引，票是细节，Decisions so far 是已走过的路。 每个新会话从地图重新定向，上下文窗口始终干净。 两套机制解决的是同一个问题（一个会话装不下），但 handoff 搬的是「会话状态」， wayfinder 搬的是「决策状态」——后者天然支持多人、多会话并行。

权威原文：wayfinder/SKILL.md 的 Invocation / Work through the map 及末句 · 对照机制：0006 handoff

9. 落到三种工单系统上

SKILL.md 把话说得很清楚：地图、子票、阻塞、前线查询物理上住在哪，是 tracker 特定的。 本 skill 只管语义（什么是地图、什么叫认领），物理操作去查仓库里 docs/agents/issue-tracker.md 的「Wayfinding operations」一节—— 那是 setup（0002）从模板种下来的。三份模板都在 skills/engineering/setup-matt-pocock-skills/ 目录里，下表是压缩对照：

三份模板在一个设计上完全一致：阻塞优先用工单系统的原生依赖关系， 正文里的 Blocked by 行只是没有原生能力时的退化方案。 理由写在 SKILL.md 里：原生关系会把前线画在工单系统自己的界面里， 人不打开地图就能看见哪张票能拿——这正是 Frontier 这个定义成立的物理基础。

模板原文： issue-tracker-github.md · issue-tracker-gitlab.md · issue-tracker-local.md （各自的 Wayfinding operations 一节）· 语义与物理的分工：wayfinder/SKILL.md 的 The Map 一节

10. 它依赖谁、谁依赖它

                 ┌────────────────────────┐
                 │ setup-matt-pocock-     │  种下 docs/agents/issue-tracker.md
                 │ skills                 │  含 Wayfinding operations 一节
                 └───────────┬────────────┘
                             │ 前置（没跑就先跑；否则退回本地 markdown）
                             ▼
   grill ───────────►  ┌─────────────┐         ┌──► research（research 票，AFK 子代理）
   with-docs ───────►  │  wayfinder  │ 解决票时调 ├──► prototype（prototype 票，HITL）
   （0019 ask-matt    │ user-invoked│         ├──► grilling + domain-modeling
    路由过来的入口）    └──────┬──────┘         │    （grilling 票 / 拿不准时的默认）
                             │                └──► domain-modeling 顺手写 CONTEXT/ADR
              雾散、路清      ▼
                 ┌────────────────────────┐
                 │ to-spec（0009）        │  把地图链着的决策「折叠」成可建计划
                 │ → to-tickets → implement
                 └────────────────────────┘

和 0005 那套词汇地板的关系是「平行不交叉」：wayfinder 不引用 codebase-design 的模块词汇， 它自己的六个词（第 3 节）就是全部术语需求；如果某张决策票恰好是「这个模块该怎么切」， 解决它靠的是 grilling + domain-modeling，必要时翻 codebase-design—— 但那是解决票内容的事，不是 wayfinder 机制的一部分。

依赖声明：wayfinder/SKILL.md 的 The Map、Ticket Types、Invocation 各节 · 下游交接：ask-matt/SKILL.md 的 On-ramps 一节

11. 副作用、下一步、行为不对改哪里

11.1 它会写什么、不会写什么

11.2 雾散之后，默认交给谁

1. 默认：进 /to-spec（0009）。ask-matt 的措辞是「折叠」—— to-spec 把地图上链着的决策压成一份可建的计划，然后照常走 /to-tickets（0010）、/implement（0011）。
2. 例外：直接 /implement——只有当这件努力在做题过程中 真的变小到一个会话装得下时。ask-matt 明确警告：把地图直接环进 implement 会跳过那次折叠，把链着的细节全扔掉——决策票里的答案、 研究分支上的发现、原型链接，都会在这一跳里丢失。
3. 如果画图第 2 步就发现没雾：地图根本没建，按用户选择直接进主流程—— 这是第 7 节讲过的合法出口。

11.3 行为不对时，去改哪个文件的哪一段

12. 检索练习

先别往回翻表，凭记忆答。选项的长度刻意对齐，不会从版式泄题。术语以本课、SKILL.md 与 CONTEXT.md 的精确定义为准。

13. 下一课与一手材料

本课主一手材料（请打开原文读，不要只背本页摘要）：

• skills/engineering/wayfinder/SKILL.md —— 全部语义：Plan don't do、Refer by name、地图五节、四票型、雾与范围之外、两种调用模式。
• skills/engineering/wayfinder/agents/openai.yaml —— 启动开关的另一半：allow_implicit_invocation: false。
• 三份工单系统模板的 Wayfinding operations 一节： GitHub · GitLab · 本地 markdown —— 物理操作的全部细节。
• docs/engineering/wayfinder.md （aihero.dev/skills-wayfinder） —— 给人看的叙事版：「索引不是仓库 / 雾是前线 / It's working if」。
• 路由与交接：ask-matt/SKILL.md 的 On-ramps 一节 · 领域词：CONTEXT.md 的 Decision ticket 条。

速查页（本课同步）： reference/wayfinder.html

导航： 上一课 0015 diagnosing-bugs （另一条 on-ramp：有东西坏了时的入口，修完发现没好接缝会把架构问题交出去）。 总览仍回 0001 系统地图； 本课反复用到的相邻课： 0002 setup（接线从哪来）、 0003 grilling 与 0004 domain-modeling（钉目的地和默认解决器）、 0006 handoff（搬会话状态，对照第 8.2 节）、 0007 research 与 0008 prototype（两种票型的解决器）、 0009 to-spec（雾散后的默认下一站）、 0019 ask-matt（路由表本身）。

建议下一课（0017，正在并行编写）： 0017 improve-codebase-architecture—— 三条 on-ramp 讲完后，换一条完全不同的线：codebase health（代码库体检）。 交接点值得先记住：0017 的扫描每次产生的是「一个加深想法」，正常走 grill-with-docs 进主流程； 如果那个想法大到、雾到一个会话装不下——比如「整个仓库的依赖方向要重画」—— 它就升级成你刚学的这张地图的原料。