在 Matt Pocock 的实战教程中wayfinder skill 解决的是 AI 辅助开发里最容易被忽略的问题跨会话规划。用户一边让模型完成需求分析、架构设计、模块开发、测试修复一边还要面对聊天窗口关闭后模型“失忆”的尴尬。普通做法是把需求重新粘贴或者让模型在单次对话里输出一段计划。短任务没问题但一旦工作要拆成多个会话、多个阶段计划就会散落在聊天记录和笔记里很快失去一致性。wayfinder skill 的做法是把“规划”本身做成一个可复用工具模型按照固定协议把模糊目标拆解成一份 Markdown 路线图并保存到文件后续会话通过读取该文件继续推进。这里的“任意规模”并不是指一次对话能装下多少内容而是指工作可以被拆成多个阶段每个阶段在独立会话里推进不再受上下文长度和会话隔离约束。这套思路适合写长代码、做中期项目、整理复杂学习路线也适合需要多人协作时反复同步上下文的场景。下面直接按“理解原理、搭建环境、实现 skill、运行验证、排查问题、形成规范”的顺序把 wayfinder skill 整理成一门可复现的工程实践。1. 先搞清楚 wayfinder skill 解决的是什么问题1.1 长任务为什么不能只靠一次对话模型对话的工作方式本质上是一次性的。用户输入一句话模型结合自身参数和当前上下文生成回答然后这段对话进入历史记录。只要会话不关闭模型可以继续引用前文但会话一旦关闭或者上下文长度超过限制前面的内容就可能被截断、被丢弃甚至完全失真。实际项目里最常见的情况是第一天让模型做了架构设计并确认了数据库表结构第二天打开新会话想让模型继续写一个接口结果模型完全不记得表结构是 user_id 还是 userId。用户只能重新粘贴一遍。如果项目周期拉长到两三周这种“重新粘贴”会反复发生而且粘贴的内容越多上下文里有效指令的比例越低模型越容易跑偏。长任务真正需要的不是“更长的上下文”而是一个可持久化的外部状态。wayfinder skill 的核心假设就在这里把规划从“对话内容”变成“项目文件”。规划不是存在于模型记忆里的东西而是存在于文件系统里的东西。模型可以随时读取用户也可以随时修改版本管理也可以正常纳入。1.2 wayfinder skill 与普通提示词的本质区别普通提示词是一次性指令。用户写一段“请先规划再实现”模型理解后按当时的上下文执行。这段提示词本身没有结构没有触发条件没有输出协议也没有文件落盘规则。它依赖用户每次手工输入同样的话也依赖模型每次都保持同样的理解水平。wayfinder skill 属于 Agent Skills 这一类能力。它打包了三样东西元信息、指令和输出协议。元信息告诉模型“什么时候应该使用这个技能”指令告诉模型“拿到任务后按什么步骤处理”输出协议则约束模型“最终必须给出什么结构、保存到哪里”。这种结构让规划行为不再随机而是变成一个可以复用、可以调试、可以纳入项目工程体系的功能。下面用表格对比普通提示词和 wayfinder skill 的差异。这里的普通提示词指的是用户在对话里随手写下的规划指令wayfinder skill 指的是打包成 skill 目录的完整方案。对比维度普通提示词wayfinder skill触发方式用户每次手工输入模型根据任务描述自动识别也可显式调用指令稳定性受上下文和措辞影响容易漂移固定写在 SKILL.md 中行为更稳定产出物对话文本关闭即丢失Markdown 规划文件可持久化、可回读复用性每条项目都要重新写一套 skill 可用于多个项目可排查性出了问题难以复现可以检查文件、日志、字段定位更准确与项目的关系游离在代码之外作为项目目录的一部分可进入版本管理这个表格不是要否定普通提示词。短任务、一次性任务、随手问一个问题直接写提示词更高效。只有当任务规模变大、跨会话、跨阶段、需要持续同步状态时wayfinder skill 的价值才体现出来。1.3 核心产出物一份可持久化的路线图wayfinder skill 的产出物不是一两句建议而是一份结构化的路线图文件。这个文件至少要包含目标、范围、里程碑、任务、状态、风险和检查点。它本质上是一个“项目状态文件”模型在每个会话开始时读取它就能知道自己处于哪个阶段、下一步要做什么、哪些任务已经完成、哪些任务被卡住了。为什么一定要落盘因为文件是项目里客观存在的东西。用户可以审查、修改、提交到 Git也可以让多个会话共享。相比之下对话里的计划只存在于模型内部状态中用户无法直接编辑也无法保证下一个会话能读到。落盘之后跨会话规划才真正成立。这里需要注意wayfinder 规划文件与普通 TODO 清单不同。TODO 清单只记录“要做什么”wayfinder 规划文件还记录了“为什么这么做、这样做的边界是什么、完成一项任务后如何验证”。它不是任务列表而是一份可以指导执行的路线图。后面的章节会围绕这个路线图做具体设计。2. 动手前先搭好 Skill 运行环境2.1 前置条件与版本认知要运行 wayfinder skill需要一个支持 Agent Skills 机制的客户端环境。在常见实践中Claude Code 和较新版本的 Claude 客户端都具备这类能力。不同客户端对 skill 目录的识别方式会有差异因此落地前要先确认两个问题当前客户端版本是否支持 Skills 目录以及 skill 目录放在全局目录还是项目目录。如果你使用的是 Claude Code通常会在终端里先确认版本claude --version如果命令不可用说明 Claude Code 环境还没有配置好需要先安装并登录后再继续。这里不针对具体安装步骤展开因为不同系统的安装方式差异较大而且版本变化很快。下面的表格概括了常见环境组件。这里的建议面向大部分学习场景生产环境要根据实际客户端调整。组件作用学习环境建议生产环境注意Claude Code 或兼容客户端提供模型运行环境使用最新稳定版即可与团队统一版本避免行为不一致Node.js 环境Claude Code 的常见运行依赖安装 LTS 版本由运维统一管理版本项目目录存放 skill 和规划文件新建一个实验项目即可使用独立的代码仓库docs/plans 目录保存 wayfinder 生成的路线图放在项目内纳入版本控制并设置备份SKILL.md定义 wayfinder 行为按本文示例复制修改由团队评审后再固化注意落地前先确认当前客户端版本是否支持 Skills 目录。即使是同一套工具老版本也可能只支持全局说明文件而不支持按目录拆分的 skill。可以先创建一个最小 skill再逐步扩展。2.2 创建 wayfinder skill 的目录骨架在常见项目中skill 可以放在全局目录也可以放在项目目录。全局目录适合所有项目都能使用 wayfinder 的场景项目目录适合把 skill 行为绑定到当前项目、跟随代码仓库一起分发的场景。推荐刚开始用项目目录这样不会影响其他项目出错时也更好排查。以项目目录为例可以在当前项目里执行下面的命令创建 wayfinder skill 的基础结构mkdir -p .claude/skills/wayfinder mkdir -p docs/plans创建完成后可以使用 tree 命令确认目录结构tree -a .claude docs如果没有安装 tree可以使用 find 命令查看find .claude docs -type f -o -type d此时目录结构应该是my-project/ ├── .claude/ │ └── skills/ │ └── wayfinder/ │ └── SKILL.md ├── docs/ │ └── plans/ └── src/SKILL.md 是 wayfinder skill 的核心文件下一步会写入完整内容。docs/plans 是规划文件的默认保存目录。这里建议从一开始就固定目录避免模型在多个路径之间犹豫。2.3 让模型能够发现 wayfinder skill大部分支持 Agent Skills 的客户端会自动扫描.claude/skills目录下的 skill。因此只要目录和文件命名正确模型通常就能发现 wayfinder。如果当前客户端没有自动发现需要检查设置项或用户级配置确认如何注册自定义 skill。不推荐在一开始就猜测配置字段因为不同版本差异很大。先用目录扫描方式做最小验证确认模型能读到 SKILL.md再考虑注册到用户配置里。检查是否被发现的常用方式是在会话中显式调用wayfinder 请规划一个跨会话项目构建一个带登录和看板的 Web 应用。如果显式调用后模型仍然不理解说明 skill 没有被加载。此时要回到目录路径、文件名、客户端版本三个方向排查。3. 用 SKILL.md 定义 wayfinder 的规划协议3.1 frontmatter告诉模型何时使用这个 skillSKILL.md 是 wayfinder skill 的“说明书”。文件开头的 frontmatter 包含 name 和 description 两个关键字段。name 是 skill 的标识description 是模型判断触发时机的依据。description 写得好不好直接决定模型能不能在合适的场景里主动使用 wayfinder。下面是一个可复用的 SKILL.md 骨架。这里的内容用于说明思路实际项目里可以根据自己的工作流调整。--- name: wayfinder description: 当用户需要规划一个复杂、模糊、需要多阶段完成的目标时使用。适合跨会话任务管理、项目拆解、长周期迭代等场景。 --- # wayfinder 你是一个跨会话任务规划器。你的职责不是直接写代码而是把用户的目标拆成可执行、可验证、可跨会话接力的计划。 ## 工作步骤 1. 澄清目标如果用户给出的目标过于模糊先提出 3 到 5 个关键问题而不是马上输出计划。 2. 确定范围明确做哪些、不做什么、技术边界在哪里。 3. 拆分里程碑把目标拆成 3 到 7 个里程碑每个里程碑必须可以被验证。 4. 拆分任务为每个里程碑拆出具体任务每个任务需要写明产出物和完成标准。 5. 输出规划把所有内容写入 Markdown 文件。 6. 返回路径在对话中输出文件路径、关键风险和下一步建议。 ## 输出协议 规划文件必须保存到以下目录 text docs/plans/推荐文件名为 current-plan.md。每次重新规划时覆盖该文件同时可以在文件名中追加时间戳例如docs/plans/plan-20250101-1000.md文件必须包含以下章节目标、范围、里程碑、任务、状态、风险、检查点。约束不要在执行规划前直接写业务代码。不要为了输出完整而编造不存在的约束。如果用户提供的技术栈不明确需要先确认。不要让规划文件依赖模型对话记忆所有关键信息必须写入文件。这里最关键的是“输出协议”和“约束”两个部分。很多模型在规划时会表现得很积极输出一段漂亮的计划但没有落盘。没有落盘跨会话规划就退化成普通聊天。因此 SKILL.md 里一定要写清楚文件路径和文件结构。 ### 3.2 指令部分规划、落盘、输出格式 SKILL.md 的命令部分要足够明确但也不能过度机械化。模型需要具备一定的判断能力例如理解用户说“做一个项目”到底是指做一个 Demo 还是做一个可上线的产品。但输出格式必须固定这是 wayfinder skill 能长期复用的基础。 推荐采用“先澄清、后规划、再落盘、最后返回路径”的顺序。很多人会跳过第一步“澄清目标”直接让模型输出计划。这样得到的结果往往非常泛比如“第一步需求分析第二步设计第三步开发”。这不算规划只是列了一个通用流程。 真正有效的 wayfinder 规划应该在每个任务后写出验收标准。例如 markdown - [ ] 完成登录接口开发 - 验收标准输入正确账号密码时返回 token输入错误时返回 401这种粒度才能让后续会话知道任务到底有没有完成。SKILL.md 中应该明确要求模型“每写出一个任务必须给出完成标准”。3.3 规划文档的字段设计规划文档不是越长越好。它需要包含足够的信息让一个完全不了解前因后果的新会话能够开始工作。下面这张表可以作为规划文档字段定义的参考。字段作用是否必填示例目标说明这次跨会话工作最终要达成什么必填构建一个带登录和看板的 Web 应用范围明确做什么、不做什么必填本期不做移动端不做第三方支付里程碑把目标拆成多个可验证阶段必填M1项目骨架与数据库M2登录认证任务每个里程碑下的最小执行单元必填实现用户注册接口状态标记任务处于待办、进行中、完成、阻塞、已取消必填进行中依赖说明前置任务或外部依赖建议填写登录接口依赖用户表结构风险记录可能影响进度的因素建议填写第三方短信服务未确定影响注册流程检查点每个阶段完成时需要验证的内容建议填写登录流程可以用测试账号跑通字段数量不要太多。如果字段过多模型在后续会话中更新文件的成本会变高反而容易放弃维护。建议第一版只保留目标、范围、里程碑、任务、状态、检查点后续需要时再增加风险、依赖和决策记录。4. 从模糊想法到可执行计划wayfinder 实战演示4.1 模拟一个需要跨会话推进的真实项目下面用一个常见的项目来演示 wayfinder skill 的完整流程。目标是构建一个带用户登录和项目看板的 Web 应用技术栈还没定规模中等计划用多个会话分期完成。这个场景既包含需求规划又包含代码实现适合验证跨会话规划是否能真正减少重复沟通。首先在会话中触发 wayfinder。如果模型没有自动识别可以显式调用wayfinder 请规划一个跨会话项目构建带用户登录和项目看板的 Web 应用技术栈未定希望分阶段完成。如果当前客户端支持命令行直接提问也可以尝试claude -p 请用 wayfinder 规划构建带登录和看板的 Web 应用分阶段完成技术栈还没定。无论哪种方式wayfinder 的第一轮输出都不应该是完整开发计划而应该是一组澄清问题。例如1. 这个应用是内部工具还是面向公众的产品 2. 用户登录是否需要手机号、邮箱或第三方账号 3. 看板需要支持多少人同时协作 4. 后端技术栈有偏好吗 5. 部署环境是云服务器、私有服务器还是本地运行这些问题的意义在于避免模型用一套通用模板套所有项目。跨会话规划要真正可用必须在开始阶段就把关键决策固化下来。4.2 触发 wayfinder 并观察输出假设用户回答了上述问题这是内部工具使用邮箱登录看板支持团队协作后端可以使用 Node.js部署在公司内网服务器。此时 wayfinder 进入正式规划阶段最终会在 docs/plans 目录下生成一份规划文件。下面是简化后的规划文件示例。实际生成的内容会比这个更详细这里展示的是核心结构。# 跨会话规划内部项目看板应用 ## 目标 构建一个支持团队内部使用、通过邮箱登录、可以管理项目任务看板的 Web 应用。 ## 范围 - 本期实现邮箱登录、任务看板、成员管理。 - 本期不做移动端适配。 - 本期不做第三方登录。 - 本期不做自动化部署。 ## 里程碑 1. M1确定技术栈与项目骨架 2. M2数据库设计与用户注册登录 3. M3看板数据模型与接口 4. M4前端页面与交互 5. M5联调、测试与内网部署 ## 任务 - [ ] M1 确定后端框架NestJS 或 Express并建立项目仓库 - 验收标准项目能启动提供健康检查接口 - [ ] M2 设计用户表与会话表 - 验收标准数据库迁移脚本可执行建表成功 - [ ] M2 实现邮箱注册与登录接口 - 验收标准正确密码返回 token错误密码返回 401 - [ ] M3 设计任务和看板列的数据结构 - 验收标准通过接口能新增任务并修改任务所在列 - [ ] M4 实现登录页和看板页 - 验收标准登录后可以查看看板并拖拽任务 - [ ] M5 编写关键接口测试并部署到内网服务器 - 验收标准登录、新增任务、移动任务三条主流程测试通过 ## 状态 - 当前阶段M1 - 当前阻塞任务无 ## 检查点 - 进入 M3 前必须确认用户注册登录流程已经完整跑通。 - 进入 M5 前必须确认看板接口的自动化测试通过。生成这份文件后模型需要在对话中返回文件路径和下一步建议。如果这一步只输出了计划但没有保存文件说明 SKILL.md 的落盘指令没有被正确执行需要回到环境或指令配置排查。4.3 后续会话如何读取计划继续推进到了第二个会话用户不需要重新粘贴全部需求。只需让模型读取规划文件然后执行第一个未完成任务即可。例如claude 读取 docs/plans/current-plan.md并继续执行第一个未完成任务。模型会先读取 current-plan.md理解当前处于 M1 阶段再根据 M1 下的第一个任务开始工作。这个过程中规划文件承担了“外部记忆”的职责。模型不需要记住上一个会话的完整对话只需要读取文件并结合当前项目状态做判断。执行完一个任务后应要求模型更新规划文件。例如claude M1 的第一个任务已完成请更新 current-plan.md 的状态并告诉我下一步做什么。这里的关键是让“状态更新”成为 wayfinder 工作流的一部分。如果不更新文件跨会话规划就会逐渐失真。理想的循环是读取计划、执行任务、更新状态、开始下一个任务。5. wayfinder 不按预期工作时按这条链路排查5.1 排查顺序从加载、落盘到格式遵守wayfinder skill 不按预期工作时不要急着修改 SKILL.md 内容先按下面顺序排查。第一确认 skill 是否被加载。检查目录路径是否正确find .claude/skills -name SKILL.md如果找不到文件说明目录位置不对。如果文件存在但没有被模型识别尝试重启会话或者用wayfinder强制调用。第二确认模型是否读到了 SKILL.md。可以在对话里直接问模型“wayfinder 这个 skill 的规划文件路径是什么”。如果模型答不上来说明它没有加载 SKILL.md而不是不会规划。第三确认模型是否有文件写入权限。很多情况下模型输出了完整计划但因为没有写文件权限所以无法落盘。这里需要检查当前客户端工具的权限配置或者调整 docs/plans 目录的写入限制。第四确认模型是否遵守了输出协议。如果模型输出了计划但结构完全不符合 SKILL.md 中定义的章节说明指令不够强。可以在 SKILL.md 中追加一句“如果缺少目标、范围、里程碑、任务、状态、检查点中的任意一个章节这个规划视为失败”。5.2 常见错误对照表下表汇总了 wayfinder 跨会话规划中最容易遇到的几个问题以及对应的处理方式。问题现象常见原因检查方式处理建议模型没有自动触发 wayfinderdescription 不够明确或 skill 未被加载显式调用wayfinder重写 description强调“跨会话、复杂项目、多阶段”模型输出了计划但没有保存文件没有写文件权限或输出协议不明确检查上下文是否提到写入失败在 SKILL.md 中明确文件路径并检查权限配置第二个会话读不到规划文件工作目录不一致或文件路径写错执行ls docs/plans统一工作目录使用固定文件名 current-plan.md规划内容太泛像通用模板SKILL.md 中没有要求输出验收标准检查生成文件的“任务”字段要求每个任务附带验收标准否则视为未完成模型规划到一半开始写代码约束不够强观察输出是否偏离规划在 SKILL.md 中写明“不直接写业务代码先落盘计划”更新状态时覆盖了历史内容current-plan.md 被整体覆盖查看 Git 提交记录或文件备份保留带时间戳的历史文件或用 Git 管理变更这些问题的排查顺序建议按照“文件是否存在、模型是否读到、权限是否允许、协议是否明确”来推进。大多数情况都是路径或权限问题而不是模型能力问题。5.3 调整 SKILL.md 后如何验证修改 SKILL.md 后不要马上放到大型项目里测试直接做一个最小验证。让 wayfinder 规划一个非常小的任务例如“把一个 Markdown 文件拆成三个章节”。这个任务足够小模型可以快速完成规划并落盘。验证完三个点模型是否成功生成 docs/plans/current-plan.md。生成的文件是否包含目标、范围、任务、状态、检查点。模型是否在对话中明确返回文件路径。如果这三个点都成立再把 wayfinder 用于真实项目。如果最小验证都不过说明问题出在环境或 SKILL.md 指令本身继续扩大任务只会让排查更难。6. 把跨会话规划用于日常项目的实践建议6.1 规划文档要能被回读和更新一份优秀的 wayfinder 规划文件应该能被一个对项目毫无了解的新会话直接读取并开始执行。这意味着文件里不能有“刚才我们讨论过”这类依赖对话记忆的表述。所有关键决策、技术选型、边界条件和验收标准都必须写在文件里。同时规划文件需要能被持续更新。推荐使用 current-plan.md 作为当前版本同时保留带时间戳的历史版本。这样万一更新错误还能回滚到上一个状态。如果项目使用 Git把 docs/plans 纳入版本管理是最简单的方式。建议在 SKILL.md 中明确规定任务状态字段的取值。下面是一组常用状态取值待办 进行中 完成 阻塞 已取消这些状态越简单越好。不要使用“基本完成”“快了”“待优化”这类无法判断的表述否则更新文件时模型和用户都会感到困惑。注意不要把服务器地址、数据库密码、第三方密钥写进规划文件。规划文件会进入版本管理也会被多个会话读取敏感信息一旦写入就很难彻底清除。6.2 规划与执行解耦别让模型边规划边写码wayfinder 的定位是规划器不是执行器。它负责把目标拆成可执行的计划执行应该放到后续会话中完成。如果让模型在同一个会话里既规划又实现计划往往会被跳过或忽略模型会直接进入代码生成环节最终无法真正验证规划是否合理。推荐的协作方式是第一个会话使用 wayfinder 生成规划文件。后续会话读取 current-plan.md只执行第一个未完成任务。一个里程碑完成后更新 current-plan.md把已完成的任务标记为完成。遇到阻塞在规划文件中记录阻塞原因再决定是否调整里程碑。这种模式的好处是每个会话都有明确的起点和终点。上下文不会被大段历史计划占用模型可以专注于当前任务。6.3 跨会话规划前的检查清单在真实项目中使用 wayfinder 前建议先把下面这份清单过一遍。清单的目的不是保证一次成功而是把常见问题提前拦截住。客户端版本是否支持 Skills 机制目录位置是否正确。wayfinder 目录下是否存在 SKILL.mdfrontmatter 是否有 name 和 description。docs/plans 目录是否存在当前账号是否对它有写入权限。SKILL.md 中是否写明了固定输出路径和文件结构。每个任务是否都有验收标准而不是只有描述。规划文件是否不包含敏感信息和不可公开的内容。是否已经确定后续会话的读取方式例如claude 读取 current-plan.md。是否已经约定状态字段取值避免不同会话使用不同写法。是否把 docs/plans 纳入 Git 管理方便回滚。是否做到先规划、再执行不混在一个会话里完成。如果项目刚开始还不太熟悉 wayfinder建议先拿一个小任务跑通全流程再逐步增加项目规模。6.4 扩展方向从个人任务到团队协作wayfinder 的跨会话规划模式天然适合从个人任务滑动到团队协作。个人使用时规划文件只服务自己团队使用时规划文件可以成为共享的项目状态。常见的扩展方向包括为每个里程碑单独开一个会话避免一个会话塞入太多上下文。用脚本统计 current-plan.md 中状态为“完成”的任务数量生成进度报告。把规划文件与 CI 流程结合在每次提交时检查是否有未更新状态的任务。把 wayfinder 的 SKILL.md 放入团队公共仓库让所有成员使用同一种规划协议。为每个任务绑定一条验证命令例如“运行 npm test”或“执行 curl 检查接口”让后续会话更清楚如何验收。这些扩展方向都会增加工程复杂度建议按需引入。对个人开发者和中小团队来说最核心的还是先把“读取计划、执行任务、更新状态”这条链路跑稳。跨会话规划的核心不是让模型更聪明而是让模型知道自己处于哪个阶段、下一步做什么、哪些信息已经固化到文件里。wayfinder skill 展示的正是这个思路。建议先找一个预计两到三周完成的中型任务把 SKILL.md 按自己的项目调整跑通一次“规划、落盘、新会话读取、更新状态”的完整循环。只要这条链路稳定扩大到更大规模的工作就只是计划文件迭代的问题而不是上下文记忆的问题。