wayfinder

一个初步想法出现了——它太大，无法在一次 Agent 会话中完成，而且笼罩在迷雾中：从这里到目标的路还看不清。Wayfinding 要做的是找到这条路，而不是径直冲向目标。这项技能会在仓库的问题跟踪器上绘制一张共享地图，然后逐一处理其中的决策工单——其解决结果是一个决定，而不是待执行的构建任务切片——直到路线清晰为止。

每项工作都有不同的目标，而为目标命名是绘图的第一步——它会影响每张工单。目标可能是一份准备交接并持续迭代的规范、一项必须在开始规划前敲定的决定，也可能是在原地完成的变更，例如数据结构迁移。这张地图不受领域限制——工程工作、课程内容，任何符合这种形式的事情都可以。

规划，而非执行

Wayfinder 默认用于规划：每张工单都会解决一个决定；当路线清晰时，地图就完成了——在有人开始做事之前，不再有待决定的问题。想要直接动手做的冲动，通常表明你已到达地图边缘，该交接了。某项工作可以在其备注中另行说明——将执行工作纳入地图本身——但若无此说明，就产出决定，而非交付物。

按名称引用

每张地图和工单都是一个问题，因此都有一个名称——也就是标题。在人类阅读的所有内容中——叙述文字、地图的“已做决定”部分——都要用名称指代它，绝不要只用 ID、数字或 slug。一串 #42, #43, #44 难以理解；名称则能让人一眼看明白。ID 和 URL 不会消失——名称会包裹其链接——但它们应当包含在名称中，而不是取代名称。

地图

地图是此仓库的问题跟踪器上的一个独立问题，标签为 wayfinder:map——它是权威记录。地图的工单是其子问题。

地图是一个索引，而非存储库。它列出已做出的决定，并指向存放详细内容的工单；每项决定只存在于一个地方——其对应工单中——因此地图不会重述决定，只会概述并链接。

地图、其子工单、阻塞关系和前沿查询具体存放在哪里，取决于跟踪器。 请阅读与仓库的工程师技能放在一起的 TRACKER.md——其中的“Wayfinding operations”部分说明了_此_仓库如何表示子问题、阻塞关系和前沿查询。如果没有 TRACKER.md，就根据用户提供的信息、Git 远程仓库以及已安装且已通过身份验证的 CLI，确定本次运行使用的跟踪器；如果都无法确定，则默认使用本地 Markdown 跟踪器。

工程师技能的目录因运行环境而异，因此请使用 glob 查找：

ls skills/*-engineer/TRACKER.md */skills/*-engineer/TRACKER.md .*/skills/*-engineer/TRACKER.md 2>/dev/null

地图正文

每个会话加载一次的低分辨率完整地图。未关闭的工单不会列出——它们是通过查询找到的未关闭子问题。

## Destination

<what reaching the end of this map looks like — the spec, decision, or change this effort is finding its way to. One or two lines; every session orients to it before choosing a ticket.>

## Notes

<domain; skills every session should consult; standing preferences for this effort>

## Decisions so far



- [<closed ticket title>](link) — <one-line gist of the answer>

## Not yet specified



## Out of scope

工单

每个工单都是地图的一个子议题；跟踪器的议题 ID 即其身份。工单正文是问题，规模适合在一个 100K token 的 Agent 会话中处理：

## Question

<the decision or investigation this ticket resolves>

每个工单都带有一个 wayfinder:<type> 标签，取值为 research、prototype、grilling、task 之一（参见工单类型）。

其中三种类型的标签决定了 HITL/AFK 轴：research 始终是 AFK，prototype 和 grilling 始终是 HITL。task 是例外——它既可能是 HITL，也可能是 AFK，因此 task 工单要在问题下方用 **HITL** 或 **AFK** 行注明所属轴。若不注明，便无法从跟踪器中还原所属轴，后续会话也无法判断工单是否需要人工参与。

会话通过先将工单分配给负责推进地图的开发者来认领工单；认领必须在开展任何工作之前完成，这样并行会话就会跳过该工单。被分配者_即_认领者：未关闭且无人认领的工单就是未认领状态。

阻塞关系使用跟踪器的原生依赖关系——这至关重要，因为它会在跟踪器自己的 UI 中_直观地_呈现前沿，让人无需打开地图就能看到哪些工单可以着手处理。只有在跟踪器不支持原生阻塞关系时，才使用正文约定作为替代。当阻塞某个工单的所有工单都已关闭时，该工单即为未阻塞；前沿是开放、未阻塞、未认领的子议题——也就是已知事物的边界。

答案不写入正文，而是在解决工单时记录（参见通过地图推进工作）。解决工单时创建的资源应链接到议题，而不是粘贴进去。

工单类型

每个工单都属于 HITL（人在回路中）或 AFK（由 Agent 独立推进）。HITL 工单只能通过与真人的实时交流来解决；Agent 绝不代替人类表达观点（如果提问的 Agent 自己回答了自己的问题，那就违背了这一原则）。

• Research（AFK）：阅读文档、第三方 API 或知识库等本地资源，以找到决策所依赖的事实。通过 research 技能解决——如果运行环境支持子 Agent，就派发给子 Agent；否则就在当前会话中执行。需要获取当前工作目录之外的信息时使用。
• Prototype（HITL）：制作成本低、粗略但具体的产物供人讨论，从而提升讨论的具体程度，例如大纲、初步方案、存根，或通过 prototype 技能编写的 UI/逻辑代码。将原型作为资源链接。关键问题是“它应该是什么样”或“它应该如何运行”时使用。
• Grilling（HITL）：对话。这是默认类型。始终调用 grill-me 技能，并在整个过程中保持领域语言准确——ubiquitous-language 规范适用：概念一旦敲定，就立即在 CONTEXT.md 中命名；如果某个术语与现有术语冲突，就对其提出质疑。
• Task（HITL 或 AFK）：必须在作出_决策_前完成的人工工作——没有什么需要决定、原型设计或研究，但讨论会被这项工作阻塞。例如注册服务以便评估其 API、配置访问权限，或移动数据以便查看其结构。这是唯一一种需要_执行_而非作出决策的类型；它的价值在于解除决策的阻塞，而非交付最终目标。Agent 能独立完成时就由 Agent 推进（AFK）；否则就向人类提供明确的检查清单（HITL）。工作完成后即可解决；答案应记录完成的工作及由此得出的事实（凭据位置、新 URL、行数），供后续工单依赖。

战争迷雾

这张地图是_有意_绘制得不完整的：不要标注你尚未看见的内容。尚未处理的工单之外，是战争迷雾——你能看出即将面临哪些决策和调查，却还无法确定其具体内容，因为它们取决于仍未解答的问题。解决一张工单，就能驱散前方的迷雾，把现在已能明确界定的事项转化为新工单——一次一张，直到通往目的地的道路清晰，不再有工单为止。

地图中的尚未明确部分，用来记录这片朦胧的景象：可能存在的问题，以及之后需要重新审视的领域。它是通往目的地的未知边界——这里的所有内容都在范围之内，只是还不够明确，无法转成工单。根据目前掌握的情况，可以写得宽泛，也可以写得详尽；它也能为协作者指明工作方向。

**迷雾还是工单？**判断标准是你现在能否准确表述问题——_而不是_现在能否回答问题。

• **符合工单条件：**问题已经明确——即便它受阻，暂时无法着手处理。
• **符合尚未明确条件：**你还无法如此准确地表述问题。不要预先把迷雾切分成工单大小的块：它比工单更粗略，待边界推进到那里时，一个部分可能会变成多张工单，也可能一张都不会变成。

尚未明确不包括已经决定的事项（迄今的决策）、已有的待处理工单，以及超出范围的事项（见下一节）。

超出范围

迷雾只会朝着目的地_聚拢_。目的地界定了范围，因此超出目的地的工作超出范围——它不是迷雾，也不属于尚未明确。地图上有专门的超出范围部分，用来记录你有意排除在_本次_工作之外的事项。是否明确，不影响归类；范围才是标准。

超出范围的工作永远不会转成工单——边界止于目的地——因此，只有重新划定目的地时它才会回来；届时它将作为一项全新的工作，而非恢复先前的工作。

将某项工作排除在范围之外，是范围界定行为，而不是路线上的一步。如果已有工单后来发现位于目的地之外——可能是在绘制地图时误将其纳入范围，也可能是在解决其他事项时才发现——请关闭它（已关闭的工单明确位于边界之外），并在超出范围部分写一行，简述其内容和超出范围的原因，同时链接到已关闭的工单。不要将其列入迄今的决策；该部分记录的是实际走过的路线，而范围边界并不是路线上的一步。

调用方式

有三种模式。在绘制地图和沿图推进工作模式下，每个会话最多解决一张工单——AFK 工单除外，因为它们不占用人工精力。超级寻路者模式完全不解决 HITL 工单；它只负责分派，然后停止。

提出前沿事项

绘制地图和沿图推进工作都会抵达一个前沿事项可处理的时刻。停下来让用户选择——绝不要替用户做决定。

按名称列出所有前沿工单，注明每项的类型以及属于 HITL 还是 AFK，并询问用户要处理哪些。用户的回答将决定本次批次：全部、指定的几项，或一定数量。注意力和资源有限，而你无法从这里判断限制是多少，因此应由用户设定，而不是由你猜测。

用户回答之前，什么都不要启动——包括研究。未经询问就启动研究成本很低，而且通常是显而易见的选择；也正因如此，唯独那一次例外才会令人意外。

如果用户一次选择了多张 HITL 工单，这就是超级寻路者模式。

绘制路线图

用户以一个宽泛的想法发起。

1. 确定目的地。 运行一次 grill-me 会话，在过程中逐步明确领域术语，确定这份路线图要通往何处——规范、决策或变更。目的地决定范围，因此要先敲定。
2. 绘制前沿。 再次进行提问，这次采用广度优先：遍历整个空间，而不是深入某一条线索，找出尚未解决的决策，以及现在就能采取的第一步。如果没有发现迷雾——通往目的地的路径已经清晰，整个旅程小到一次会话就能完成——就不需要路线图。停下来询问用户接下来想怎么做。
3. 创建路线图（标签为 wayfinder:map）：填写 Destination 和 Notes，Decisions-so-far 留空，将迷雾概略列入 Not yet specified。
4. 创建现在就能明确说明的工单，作为路线图的子议题；然后在第二遍中连接阻塞关系（议题需要先有 ID，才能互相引用）。连接后，它们会被整理到前沿和受阻项中；仍无法明确说明的内容留在迷雾中，即 Not yet specified 部分。
5. 提供前沿（如上），而不是自行启动任何任务。根据用户的回答采取行动：AFK 工单在此作为子 Agent 运行——research 工单通过 research 技能执行，将发现记录在临时的 research/<name> 分支上，并在工单中附上上下文指针；HITL 工单则按照 Ultra wayfinder 通过并行会话处理。
6. 停止——绘制路线图是一场会话的工作；不得在此自行处理任何 HITL 工单。

沿路线图推进

用户提供路线图（URL 或编号）发起。

工单是可选的——如果没有指定工单，就根据前沿判断下一步，而不是直接接手指定任务。

1. 加载路线图——查看低分辨率概览，而不是每张工单的正文。
2. 先进行同步。 任何已关闭但没有在 Decisions-so-far 中附上指针的子工单，都是由受派会话解决的；受派会话不得编辑路线图（参见 Ultra wayfinder）。将每张工单的解决评论并入索引，并处理其中提出的迷雾内容晋级或范围外裁定。路线图就是索引；未同步的路线图已经无法发挥索引作用。
3. 选择工单。如果用户指定了工单，就使用它。否则计算前沿：只有一张可执行工单，就处理它；多于一张，就提供前沿（如上）。如果用户选择了多张 HITL 工单，就属于 Ultra wayfinder，应按会话分别领取——转到该流程，不要在此继续。否则领取这张工单：开始任何工作前先将其分配给自己。
4. 解决工单——按需深入查看：按需获取任何相关或已关闭工单的完整正文；调用 ## Notes 区块中列出的技能。如有疑问，使用 grill-me。
5. 记录解决结果：将答案作为解决评论发布，关闭议题，并在路线图的 Decisions-so-far 中追加上下文指针。受派会话应在发布评论后停止——参见 Ultra wayfinder。
6. 添加新发现的工单（先创建再连接）；将已能明确说明的迷雾内容晋级，并从 Not yet specified 中清除每个已晋级的部分，使其只存在于新工单中。如果答案表明某张工单——无论是当前工单还是其他工单——超出了目的地范围，就应将其裁定为范围外，而不是沿途解决。如果决策使路线图的其他部分失效，请更新或删除相应工单。受派会话应在解决评论中提出所有这些操作，而不是直接执行。
7. 如果清除迷雾后拓宽了前沿，就在会话结束前提供前沿（如上）。

用户可能会并行处理未受阻的工单，因此要预期其他会话也在同时编辑跟踪系统。

路径一旦清晰，路线图就完成了。告诉用户接下来运行 to-tickets——它会将实际构建拆分为示踪弹式切片；这应由用户发起，而不是你。

Ultra wayfinder — 并行推进前沿工作

所需能力：能够调度同级会话的运行框架——人类可以加入这些兄弟 Agent 会话并直接与其交流。子 Agent 不能替代同级会话，原因如下。如果运行框架不具备此能力，Ultra 就不可用：请直说，并按串行方式推进前沿工作。

用户会用 “ultra wayfinder”（或“ultrawayfinder”）加上一张地图来调用它，也可以选择指定要处理的工单。指定的工单就是本批次。即使未指定工单，仍要先展示前沿——调用 Ultra 表示工作应如何开展，并不代表你可以自行决定工作范围。通过 Offer the frontier 进入 Ultra，意味着批次已经由人类选定。

**同级会话，而非子 Agent。**子 Agent 无法处理 HITL 工单：审问和原型工单只能通过与人类实时交流来解决，而子 Agent 无法联系到人类——因此它最终只能自问自答，并提交一项完全没有融入人类判断的解决方案。被调度的同级会话会暂停并等待输入，人类则依次加入每个会话。这样可以并行准备状态——加载并预热每个工单的上下文——同时让人类的注意力保持串行，而注意力才是稀缺资源。

根据 HITL/AFK 轴来调度，绝不能依据类型标签——决定一个会话能否代替人类的，正是这条轴：

• HITL（grilling、prototype、标记为 HITL 的 task）→ 每个工单各派发一个同级会话。
• AFK（research、由 Agent 独立推进的 task）→ 在当前会话中使用子 Agent。没有人类需要加入，因此同级会话毫无益处，只会带来上下文切换成本。

1. 加载地图并计算前沿。
2. 按照人类选定的集合执行。绝不能扩大到超出对方要求的范围。
3. 将每个 HITL 工单派发给一个同级会话，并附上以下简报。
4. 在此处将每个 AFK 工单作为子 Agent 运行，并由你亲自在地图上记录其解决方案。
5. 确认每个已派发会话都认领了自己的工单。如果会话在首次写入前就已终止，该工单就仍未被认领，并会回到前沿；但此时人类已被告知它正在处理中——认领是唯一的并发保护机制，因此要核实的是认领，而不是会话。重新派发未成功的工单，或报告哪些工单未成功派发。
6. 按名称报告已派发的工单，然后停止。

简述

每个被派发的会话都会收到以下四项内容，其中第一项是确保其余内容安全执行的关键：

1. 你是一个被派发的会话。 请用这几个字明确说明。会话会进入 Work through the map，否则就会照着第 5 步执行并编写地图，而这恰恰是绝不能发生的。
2. 通过命令形式明确调用 wayfinder。 这个技能设置了 disable-model-invocation，所以如果只是告知会话使用 wayfinder，会话并不会加载它的任何内容，包括 claim-first。这个故障不会显现出来：会话启动后停在那里，看起来一切正常。（epic-runner 也会以相同方式处理自己的派发。）
3. 先认领工单，再开始任何工作。 如果工单已经分配给别人，说明有人先到了——请停止并报告，而不要着手处理。
4. 地图和工单，以及：推进工作，直到遇到第一个确实需要人工回答的问题，然后停止并等待。

被派发的会话不得编辑地图正文。 它们照常发表评论说明处理结果，并关闭对应议题，但向「目前为止的决定」追加内容属于对同一份共享文档执行读-改-写操作，且没有锁定机制，并发会话会在不知不觉中互相覆盖。因此，它们只能提出建议——处理结果、模糊程度的调整，以及范围外事项的裁定都写入处理结果评论，由下一个处理地图的会话在协调步骤中纳入。

AFK 子 Agent 是例外，而锁定机制正是它们能成为例外的原因：它们在派发会话内部运行，因此只有一个写入者，照常记录它们的处理结果即可。

Claude Code 的绑定示例：

claude --bg -n "wf-<number>-<short-slug>" "/wayfinder <map> <ticket> — you are a dispatched session; <rest of brief>"

始终传入 -n：不传入时，会话所在行会以原始提示词为标题，列表就会变得难以阅读。使用 claude agents --json 验证。被派发的会话会在 Agent View 中停留于 "Needs input"（在空提示词上按 ←，或运行 claude agents），由人工按 → 接入。

---

改编自 mattpocock/skills，MIT © 2026 Matt Pocock。复制此文件时请保留此行。