Matt Pocock 的实战教程里讲到的 wayfinder skill解决的是 AI agent 跨会话规划这件事。说直白一点现在用 Claude Code 这类工具做一个需要跨几天、跨多轮会话的大型任务最让人头疼的不是它能写多少代码而是它经常“失忆”新开一个会话之前定的目录结构、任务顺序、已经改过哪些文件全都要重新解释一遍。wayfinder 的核心思路是别再指望模型在对话历史里记住一切而是把规划和进度写进一个外部文件每次会话开始时先读这份文件干活干到一段落再把最新状态写回去。这个思路听起来朴素但实际跑下来比在聊天窗口里反复说“请你记住”可靠得多。这篇文章会把 wayfinder 为什么有效、怎么落地、以及我实际使用中踩到的坑拆开讲。适合正在用 coding agent 做多文件、多阶段任务或者想把大项目分批交给 AI 完成的人。1. wayfinder skill 到底解决了什么问题1.1 AI agent 做大型任务的真正瓶颈很多人以为大模型的上下文窗口越长就能处理越复杂的任务。但实际上窗口大不代表记得牢。任务一旦超过几十轮最典型的现象就是前一半还按劲执行后一半开始忘记前期约定甚至重复改已经改过的地方。这不是模型变笨了而是对话历史越长无关信息和关键决策同时堆在里面模型容易被近期内容带偏。专业一点的叫法是“上下文漂移”。跨会话的时候更严重旧会话的所有中间状态都留在历史窗口里新会话启动后是一张白纸只能靠用户重新贴背景。如果你只是让它写一个函数、调一个接口问题不大一旦是一个“几百个文件、十几个模块、要跑好几天”的项目没有外部记录项目大概率做到第三轮就开始乱套。wayfinder 这类 skill 的价值就在这它不提升单轮生成能力而是解决“任务治理”问题。让 agent 把工作当成一条路线图来走而不是靠模型自己脑内记忆。1.2 它和普通 prompt、普通插件的区别这里先明确一下 skill 是什么。它不是你在聊天窗口里临时贴的一段指令而是一组预置文件通常放在项目目录里一个约定位置。agent 在进入相关任务时会主动读取这些文件然后按里面的规则行动。普通 prompt 只能影响当前这次对话下次还得重新粘贴。skill 不同它是一份长期可复用的操作手册。wayfinder 这个 skill 约定了这样一件事所有需要跨会话执行的复杂项目必须在项目目录里维护一个规划文件会话开始先读取任务完成后更新把整个项目状态持续外置到文件里。你不需要每次手动跟 agent 解释“你之前做到了哪里”。这里还要补充一个边界它要求 agent 具备文件读写能力而且最好是用在命令行或编辑器内置 agent 上。如果一个工具只能纯聊天、不能访问本地文件wayfinder 就无从落地。1.3 它能处理“任意规模”吗教程标题里说的“任意规模”我的理解不是指所有任务都该用它而是说现代 coding agent 有了外部状态文件之后理论上可以处理任何需要分阶段完成的任务。规模大小不再是模型窗口问题而是你愿不愿意付出“维护规划文件”的成本。规模越大这份文件的价值越高。2. 跨会话规划的核心设计思想2.1 把记忆放到上下文之外文件系统才是第二大脑大模型上下文是易失内存断电就没了。文件系统是持久硬盘写下来就不会丢。wayfinder 的设计核心就是让 agent 把最重要的工作状态全部“落盘”。我一般会用一个类比来理解写代码时不把配置写在代码里而是放在配置文件里程序启动时再去读改配置不需要重新编译。wayfinder 做的事情是把任务状态也当成配置。规划文件不参与具体业务逻辑它只是给 agent 看的“当前进度快照”。这个快照越准确每次会话恢复的成本就越低。关键不是聊天记录而是状态文件。你要让 agent 习惯从文件里获得指令而不是从之前的对话里找线索。2.2 每次会话固定三步加载、执行、更新这是整个工作流里最重要的一条规则。每个会话只做三件事加载会话开始让 agent 先读规划文件找到当前状态和下一步任务。执行只做当前任务块不做无关扩展不提前去碰后面还没排到的内容。更新任务结束或阶段性完成后把任务状态、完成情况、阻塞点、下一步写回规划文件。这三步必须闭环。只加载不更新下次会话仍然会丢失进度只更新不加载第一次会产生重复规划和重复劳动。我实际跑下来最常犯的错误就是任务完成得很兴奋直接关窗口没让 agent 更新进度文件第二天打开新会话还是从头开始。2.3 一个规划文件应该写什么规划文件不需要太长但必须包含几个关键字段。我建议至少写清楚这些字段作用示例项目目标说明最终交付物是什么给订单模块增加统一错误处理范围边界说明涉及哪些目录不涉及哪些只改 /services/order不改前端页面任务清单按顺序拆解任务标注状态[x] 完成[ ] 待做当前状态明确现在执行到哪一步已改 3/10 个文件正在处理第 4 个阻塞项记录卡住的问题和原因API 返回格式不确定需要确认下一步写出接下来第一个动作优先确认 order API 文档再继续第 5 个文件很多人会忽略“阻塞项”但它非常有用。它防止 agent 在同一个问题上反复撞墙也让人能快速判断是不是需要人工介入。格式不需要太复杂Markdown 就够了。3. wayfinder skill 的落地操作3.1 环境准备确认 agent 工具支持 skill要使用 wayfinder前置条件是有一个支持 skill 机制的 agent 工具。现在像 Claude Code、Codex 这类带文件读写能力的 coding agent 越来越常见很多也支持通过配置目录加载 skill。常见的方式是把 skill 文件夹放到项目内约定目录例如.claude/skills/或类似位置不同工具和版本可能有差异。这里最怕的是你以为放对了实际 agent 根本没读到。所以我建议先做一个最小验证让 agent 回答一个只有 skill 里才知道的规则问题。比如“当前项目使用哪个 skill它的第一条指令是什么”如果它能准确复述说明 skill 加载成功。如果答不上来优先检查目录路径、命名和文件格式而不是直接开始大项目。3.2 初始规划先定大方向再拆近期任务真正开始一个项目时不要一上来就逼 agent 把 50 个子任务全列出来。大模型对短期的预测比对长期的预测可靠得多。一次性拆太多容易出现两种情况一是任务之间有重复二是很多任务是基于错误假设生成的。更稳妥的做法是先写清楚三件事目标是什么、范围到哪里结束时、交付物长什么样。然后只拆出接下来两个任务块进入执行。当前两个任务做完再停下来重新看整体方向拆下一批。这个过程我称为“滚动式规划”。它比一次性把整个 roadmap 填满更抗意外尤其在 AI 生成代码时计划赶不上变化是常态。3.3 单次会话的执行纪律启动一个执行会话时我会在第一条指令里明确写让 agent 先读项目规划文件然后复述当前状态。确认它理解之后才开始干活。中间每完成一个任务块让它简单报告一下改了哪些文件、验证结果如何。最后一定让它更新规划文件。这里有个容易被忽略的细节更新文件不是可选步骤而是整个会话的“收尾动作”。如果任务做到一半卡住了也要更新把当前代码状态、已经改到哪一行、哪个问题还没解决写清楚。这样下一次会话不会从零开始而是从断点继续。注意更新规划文件前最好先跑一次验证命令。编译失败、测试挂掉的时候不要写“已完成”要写“已修改但验证异常”否则下次会话会基于错误状态继续问题会越滚越大。4. 一个跨会话中型任务的完整示例4.1 场景给旧项目批量添加接口错误处理我拿一个典型场景演示一个老项目里有很多接口调用没有统一错误处理导致用户看到一堆白屏和原始报错。目标是把核心服务的接口调用统一改成带 try/catch 的异常处理并返回统一错误结构。这个任务看起来不难但涉及几十个文件要一个个排查 API 返回结构、确认不同模块的调用方式单次会话一定做不完。按 wayfinder 的思路我把它拆成两轮会话配合一个 plan.md 文件推进。4.2 第一轮创建规划文件完成第一批任务下面是一份精简后的规划文件字段不复杂但足够让新会话接上进度# 项目规划订单服务接口统一错误处理 ## 目标 将订单服务中所有 HTTP 调用点改成统一异常处理错误响应统一为 { code, message, data: null } 结构。 ## 范围 - 只改 src/services/order 和 src/api/order - 不涉及用户模块、商品模块 - 不改后端接口协议 ## 任务列表 - [x] 1. 封装 request.ts 中的统一错误处理工具 - [x] 2. 重构 getOrderList - [x] 3. 重构 getOrderDetail - [ ] 4. 重构 createOrder - [ ] 5. 重构 updateOrder - [ ] 6. 重构 cancelOrder - [ ] 7. 全量编译检查 ## 当前状态 已完成前 3 个文件。createOrder 开始了一半暂时不继续。 ## 阻塞项 - createOrder 的失败响应里无法区分“参数不合法”和“库存不足” 需要确认后端返回的 status 枚举。 ## 下一步 先跟后端确认 createOrder 错误码枚举 确认后继续重构 createOrder然后处理 updateOrder。这个文件看起来简单但已经包含了新会话需要的全部信息。第一次会话结束时agent 会准确知道接下来要去确认什么而不是把整个项目重新读一遍。4.3 第二轮读取旧计划从断点继续第二天新开一个会话第一条指令就是“读取 plan.md按当前状态继续执行。先处理 createOrder 的阻塞项。”agent 读完之后会自己说出现在卡在什么地方、下一步要干什么。我只需要把后端确认好的错误码枚举贴给它它就能继续完成剩余任务。整个过程不需要把昨天的 50 轮对话重新贴一遍也不需要重新解释项目背景。这个反复确认“当前状态是否匹配规划文件”的过程就是跨会话规划的最关键操作。可以用一句话来判断新会话里的 agent能不能在没有你回忆背景的情况下自己说出项目目标和下一步如果能这套机制就起作用了。5. 怎么判断规划是否真的“跨会话”有效5.1 三个硬性验收标准不是写了 plan.md 就算 success。我每次跑完会按下面三个标准验收可恢复性新会话读完规划文件后30 秒内能说清楚项目目标、已完成内容、下一步动作。如果不能说明文件里缺信息或者写得不够清楚。可验证性每个任务都有明确的完成标准不只是一个动词。比如“重构 createOrder”远不如“createOrder 失败时返回统一 JSON 结构相关测试全部通过”可靠。可追溯性规划文件里记录了以前踩过的坑、确认过的约束下一次会话不会重蹈覆辙。这个要求很多人忽略但它能避免反复跟 agent 解释同样的问题。5.2 任务拆到什么粒度合适任务粒度太粗一次会话做不完状态难更新粒度太细plan 文件变成流水账维护成本比执行成本还高。我一般把握两个边界最小粒度一个任务块能在单次会话内完成并验证。最大粒度一个任务块不超过一个模块或一个阶段。每个任务描述尽量带三个要素动作、对象、完成标准。比如“给 login 模块加统一异常处理标准登录失败返回统一 JSON 结构相关测试通过”。这样 agent 执行时能自我判断而不是猜。5.3 什么情况不要依赖 wayfinder像任何工具一样wayfinder 不是所有场景都该用。如果任务本身只需要几分钟一次会话就能做完用 wayfinder 会显得很笨重。比如“修复某个文件的拼写错误”“给一个函数增加日志”这些完全没必要维护状态文件。跨会话规划真正的价值区间是任务会跨天、跨会话、涉及多个文件或者可能换人接手。方式上还有一点值得注意规划文件不只是给 AI 看的也是给人看的。如果项目中途需要同事继续规划文件本身就是一份交接文档。它记录了决策过程和当前状态比口头交接可靠得多。6. 实操中的常见坑与排查顺序6.1 我遇到最多的五个问题第一skill 根本没被加载。agent 还是按普通聊天方式跑完全不读规划文件。这种情况最常见的不是工具坏而是 skill 目录放错地方或者文件没遵守命名规范。让 agent 复述 skill 规则是排查最快的方法。第二规划文件和实际代码不同步。文件里写着“已完成”代码里没有对应改动。这通常是因为 agent 把“准备修改”误写成了“已完成”。解决办法是更新前必须先跑验证命令。第三会话中途退出导致文件没更新。网络断了、工具崩了、人关窗口了状态还停留在上一次。所以更稳妥的做法是每个任务块做完都更新一次不要等所有任务完成才更新。更新频率越高丢进度越少。第四路径写法混乱。会话和会话之间工作目录可能不同。如果计划文件里写的是绝对路径换机器或换目录后就会失效。我建议所有路径都相对项目根目录写。第五规划文件越来越臃肿。执行了几十轮之后plan 文件里塞满了历史记录每次读取占掉大量上下文。这时候应该做归档把旧阶段记录移到 archive 文件主文件只保留当前阶段信息。6.2 进度接不上时的排查顺序如果第二次会话明显不记得进度不要直接怪模型。按这个顺序查先看现象新会话是完全没有读文件还是读了但没理解状态再看计划文件里面是不是只有初始计划没有写着“当前状态”再看文件是否被读取让 agent 输出它读到的内容确认路径和内容。再看执行过程有没有出现修改了 A 文件但计划里标记的是 B 文件。最后看工具权限agent 是否真的具备写入文件的权限还是只能读不能写。很多时候问题出在最简单的环节。比如路径不对或者忘了把文件纳入项目上下文。排查口诀先看状态文件有没有再看内容准不准 再确认 agent 读没读到最后才怀疑模型能力。6.3 性价比判断什么时候该简化我还想强调一件事wayfinder 是一种工作流方法不一定要严格安装某个特定的 skill 才能用。核心是把“外部状态文件”这个概念用起来。如果你发现维护规划文件的时间已经超过实际执行任务节省下来的时间那就应该简化。比如任务只有三轮直接在项目根目录放一个PROGRESS.md就够了不需要复杂的 skill 流程。如果任务要持续一两个月那么一个结构化的规划文件非常值得。我自己的判断标准是当项目里开始出现“今天改了哪里”这类需要回忆的问题时就应该立刻把状态写进文件。等到开始乱套再补救已经浪费了不少时间。最后给一个个人建议真正把 wayfinder 这套思路跑顺之后你对 AI agent 的使用方式会从“临时对话”升级成“项目管理”。下次再接到一个大型任务时我的第一步一定不是让 agent 直接写代码而是让它先建规划文件。这个习惯比我试用过的任何模型技巧都有效。