打开任何一个 AI 编程工具先聊半小时需求再让它写第一行代码——这几乎是过去两年里最常见的开发画面。问题在于聊得越久上下文越长AI 越容易“忘事”。你换了新会话或者项目稍微变大一点前面说好的技术方案、目录结构、踩坑记录全部归零。更现实的是真实工作从来不是一次对话能解决的一个需求要跨好几天中间还可能换人、换分支、换电脑。最近看到 Matt Pocock 的实战教程主题就是把“wayfinder skill”用于跨会话规划任意规模的工作。这个思路很值得单独拆出来讲。wayfinder 这个词本身有“寻路者”的意思放到 AI 编程场景里它做的事情非常具体帮 AI 和开发者在多个会话之间维护一张“地图”——计划是什么、做到哪里了、下一步要做什么。用一张持续推进的路线图替代一次性的长对话。这篇文章会从真实痛点出发讲清楚以下几点什么是 Skill它和普通 prompt 到底有什么区别wayfinder 这类跨会话规划 skill 的核心机制是什么如何在你自己的项目里搭建一个最小可用的版本以及实际使用中会遇到哪些坑。文章会给出可直接复制的目录设计和代码示例读完后你可以立刻在自己的工作区里试一遍。1. 先搞清楚AI 编程为什么需要“跨会话规划”先看一个具体场景。你负责一个中后台项目技术栈是 React TypeScript现在要新增一个“导出报表并发送邮件”的功能。需求涉及文件下载、权限校验、异步任务、邮件模板、日志埋点至少要十几个文件。让 AI 帮你完成这个任务通常会有两种做法。第一种在一个会话里把所有需求描述完然后让它一口气生成。结果显而易见上下文窗口是有限制的AI 写到最后几个文件时已经忘了最开始约定的接口命名而且只要中间有一次输出中断整个讨论可能都要重来。第二种每个小任务单独开一个新会话按下去再打开。表面上规避了上下文长度问题但问题变成了“前一晚刚确认过的方案第二天 AI 完全不记得”。你要把之前的背景重新讲一遍更糟糕的是如果上一轮生成的代码里已经留下了一些带约束的注释新会话的 AI 会拿着这些约束重新发散而不是沿着原计划继续执行。这就是跨会话规划要解决的核心矛盾AI 编程工具本身是无状态的但项目开发是有状态的。只要把一部分状态显式地落到项目里AI 就能顺着这条线索把会话接续起来。wayfinder 的解法不是“继续聊”而是“先规划再执行再记录”。它把规划拆成一个可保存、可检索、可更新的文件集合每次会话开始都先读取这些文件再决定下一步动作。换句话说AI 不再靠聊天记录来记忆而是靠项目里的“文件记忆”。这个概念听起来不复杂但它真正改变的是 AI 编程的工作方式从“对话式编码”转向“项目式协作”。前者是把 AI 当作一个聪明但健忘的同事后者是把 AI 当作一个能跟着项目节奏走并且可以随时同步状态的协作者。2. Skill 到底是什么它不是“高级版 prompt”这么简单提到 wayfinder skill必须先厘清 Skill 这个概念。最近“skill”这个词在 AI 编程社区里的热度非常高类似“skill 是不是就是高级版的 prompt”“skill 和 agent 的区别”“如何编写 skill”这类问题频繁出现。如果只看表面Skill 确实像一段系统提示词给模型一段说明让它在合适的场景里表现得更好。但严格来说Skill 不仅仅是一段提示词。它通常由三个部分组成触发条件、执行步骤、工具或资源引用。换句话说Skill 是“在什么情况下按照什么流程调用哪些工具生成什么结果”的可复用封装。维度手写 promptSkillAgent是否可复用每次都要重新写一次编写多处复用本身是可执行的程序/服务是否带工具通常不带可以带工具调用规则自带工具调用循环是否管理上下文不管理通过文件、模板控制输入输出主动感知和决策适用场景临时性问答高频、可标准化的场景复杂、多步骤、需要反馈的流程把“wayfinder skill”放在这个坐标系里看它属于一种流程型 Skill。它不负责具体写某个功能它负责的是当你要开始一个跨会话任务时引导 AI 先生成项目路线图当你要结束当前会话时引导 AI 更新进度文件当你开启一个新会话时引导 AI 先读取路线图和进度再决定下一步。如果你对“如何编写 skill”感兴趣wayfinder 是一个很好的学习样本因为它的输入输出都是结构化文件非常容易理解。它不需要复杂的外部 API也不需要调度多个 agent只需要几个 markdown 文件和一套稳定的读写约定。这里还要回答一个高频问题为什么不能把规划直接写在项目根目录的 README 里非要单独做一个 skill因为 README 是给人看的它的组织方式不会严格按照“AI 每次都要先读哪一段”来设计。而 skill 的核心价值是约束 AI 的启动流程先看什么、后看什么、什么情况下更新什么文件。这个约束本身比文件内容更关键。3. 环境准备搭建你自己的 wayfinder skill 目录在动手之前先确认一下环境。wayfinder 并不是某个厂商的专用功能它本质上是一套可以放进任意 AI 编程工具里的技能包。无论你用的是 Claude Code、Codex 这类偏智能体方向的工具还是自己基于大模型 API 封装的 CLI 工具只要工具支持在项目目录内读取技能文件基本都可以按下面的方式落地。版本细节这里不写死以你实际使用的工具为准。本文演示的是通用思路在项目根目录创建一个.claude/skills或者skills目录把 wayfinder 相关的文件放进去然后在技能文件里写清楚调用规则。如果你的工具恰好支持SKILL.md约定可以参考下面的目录结构# 项目根目录 . ├── .wayfinder/ │ ├── PLAN.md # 总路线图目标、里程碑、任务清单 │ ├── PROGRESS.md # 进度记录完成了什么正在做什么卡在哪里 │ └── CONTEXT.md # 关键上下文技术决策、接口约定、风险点 ├── skills/ │ └── wayfinder/ │ └── SKILL.md # wayfinder 技能定义文件 └── README.md如果你的工具不支持自定义技能目录还有一个简化方案把 wayfinder 的启动说明直接放在项目的AGENTS.md或CLAUDE.md里让 AI 每次开始会话时都会自动读取。这种方式失去了“按需触发”的灵活性但对于小团队内部使用已经足够了。文件路径AGENTS.md # 项目协作约定 ## 在开始任何大型任务之前 1. 先读取 .wayfinder/PLAN.md 和 .wayfinder/PROGRESS.md。 2. 如果没有 PLAN.md调用 wayfinder skill 生成一份。 3. 如果 PLAN.md 存在根据当前进度判断下一步动作。 ## 在结束本轮会话之前 1. 更新 .wayfinder/PROGRESS.md。 2. 如果有重要技术决策补充到 .wayfinder/CONTEXT.md。环境准备这一步不需要安装任何额外依赖只需要一个还在正常工作的 AI 编程工具以及一个 git 仓库。真正重要的是把“先读状态再动手”变成一种固定动作否则后期很容易出现工具就位但流程失效的情况。4. wayfinder 的核心流程四个阶段拆解现在进入到最核心的部分wayfinder 是如何完成跨会话规划的。从拆解结果来看四个阶段缺一不可。第一个阶段是“理解任务”。AI 收到需求后不应该马上写代码而是先询问关键信息这个功能的用户是谁边界条件是什么成功标准是什么在这个阶段AI 做的事情和资深开发者在动手前做的事一样澄清需求缩小目标范围。第二个阶段是“生成路线图”。拿到足够信息后AI 把任务拆成里程碑和可执行的小任务写进PLAN.md。注意这里的计划不是一次性定死的它更像一个动态文档。真实项目里需求变更是常态路线图必须预留调整空间。一个比较合理的粒度是每个里程碑下面包含 3 到 8 个任务每个任务都必须有清晰的完成判断标准。第三个阶段是“执行与记录”。每完成一个任务AI 更新PROGRESS.md标记哪些任务已经完成哪些正在进行哪些被阻塞。同时遇到关键决策——比如某个依赖库版本的选择、某个接口设计方案的取舍——主动写入CONTEXT.md。这一步是很多人容易漏掉的。我们总是以为 AI 生成完代码任务就结束了但没有记录就没有跨会话的连续性。第四个阶段是“会话恢复”。下一次你打开一个新会话AI 读取PLAN.md和PROGRESS.md后能够准确告诉你当前路线图是什么已经推进到哪个位置下一步建议做什么。恢复得越好越接近“AI 真正参与了一个长期项目”的感觉而不是“AI 只是替你写了一段代码”。四个阶段的核心是通过文件系统把 AI 的短期记忆转化为长期记忆。这背后的思路其实和软件工程里的“日志驱动开发”有相似之处不依赖人的记忆也不依赖模型的隐式记忆而是依赖一个显式的、可审计的状态文件。这样做的好处是不仅 AI 能接续上下文团队里的任何一个人打开项目也能通过.wayfinder目录快速了解项目全貌。5. 完整示例为一个中型功能编写跨会话规划为了让这个过程更容易理解我准备了一个最小可运行示例。假设任务是在一个国际化网站里增加“多语言 SEO 元信息配置”功能。这个任务涉及数据模型、后台表单、前端标签渲染、sitemap 更新非常适合用来演示跨会话规划。第一步准备SKILL.md。这个文件的作用是告诉 AI触发 wayfinder 后要做什么。内容不追求复杂关键是流程要清晰。文件路径skills/wayfinder/SKILL.md --- name: wayfinder description: 在项目中进行跨会话规划。当任务规模较大、可能需要多个会话完成时使用。 --- ## 触发条件 - 用户要求规划一个中大型任务。 - 用户要求跨会话跟踪工作进度。 - 用户明确提到“wayfinder”。 ## 执行步骤 1. 读取项目根目录 .wayfinder 目录下的所有文件。 2. 如果不存在 .wayfinder/PLAN.md进入计划生成流程 - 澄清目标功能边界、用户、成功标准。 - 拆分里程碑每个里程碑包含多个任务任务要可验证。 - 写入 PLAN.md。 3. 如果 PLAN.md 已存在 - 读取 PROGRESS.md。 - 找出下一个未完成的任务。 - 询问用户是否立即执行还是只做计划更新。 ## 输出要求 - 计划文件使用 Markdown。 - PLAN.md 中每个任务都以 - [ ] 或 - [x] 开头。 - 每次更新后用一句话总结当前进度。第二步在项目里触发 wayfinder。你可以直接输入提示词“使用 wayfinder 规划多语言 SEO 元信息配置功能”。AI 会按照技能定义先输出一个计划文件。第三步把计划文件保存到.wayfinder/PLAN.md。下面的内容是 AI 可能生成的一份简化计划# 多语言 SEO 元信息配置功能计划 ## 目标 为每个内容类型提供独立的多语言 SEO 元信息配置并输出到页面 head 标签。 ## 里程碑 ### M1数据模型设计 - [x] 设计 seo_meta 表支持多语言字段 - [x] 编写数据库迁移 - [ ] 补充模型层校验逻辑 ### M2后台管理界面 - [ ] 新增 SEO 配置表单 - [ ] 支持按语言切换编辑 - [ ] 接入权限校验 ### M3前端渲染 - [ ] 在页面 head 输出 title、description、og:title - [ ] 处理默认语言回退逻辑 - [ ] 补充 sitemap 更新 ### M4测试与上线 - [ ] 编写后端单元测试 - [ ] 编写前端 e2e 测试 - [ ] 执行灰度发布第四步开始执行第一个任务。假设当前会话完成了“设计 seo_meta 表”和“编写数据库迁移”AI 要同步更新PROGRESS.md。# 进度记录 ## 最近更新 - 2025-06-01完成 seo_meta 表设计含 title、description、og_title、og_description 字段。 - 2025-06-01编写数据库迁移文件待业务方 review。 ## 当前状态 - 正在执行 M1 的“补充模型层校验逻辑”。 - 下一个计划任务M2 的“新增 SEO 配置表单”。 ## 阻塞项 - 等待产品确认默认语言回退规则。至此一个跨会话规划的最小闭环已经完成。你可以在今天关闭这个会话明天打开一个新会话然后对 AI 说一句“使用 wayfinder 继续”。只要计划文件和进度文件还在AI 就能接续上下文而不需要你把昨天的需求重新讲一遍。这里需要特别说明实际的 wayfinder skill 可能比我这个演示版本精致得多可能包含更复杂的 prompt 结构、工具调用甚至状态校验脚本。但核心机制是完全一致的就是用文件维护计划、进度和上下文。如果理解了这个小例子再看任何复杂的 skill 就都不会觉得玄学了。6. 状态文件设计跨会话恢复的关键细节在运行过程中最容易出问题的不是 AI 不会写代码而是状态文件本身写得一团糟。计划文件像一篇流水账进度文件只有日期没有结论上下文文件里塞满了过时的技术选型。这样的状态文件不但不能让 AI 快速恢复反而会因为矛盾信息干扰判断。所以这里单独拿出一个小节讲状态文件设计的几个关键原则。第一PLAN.md要保持“任务可验证”。每一行任务都要能回答一个问题我怎么知道这件事做完了比如“补充模型层校验逻辑”就不够明确它缺少验收标准。更好的写法是“补充模型层校验逻辑要求 title 为必填description 长度不超过 160 字符并在测试中覆盖”。可验证的任务AI 才能准确判断完成状态。第二PROGRESS.md要记录“当前状态”和“下一步动作”。有些人写进度喜欢只写“完成了 30%”这对 AI 没有意义。它需要的不是百分比而是当前卡在哪个具体位置下一步的第一个动作是什么。如果正好遇到阻塞项明确写出来下次恢复时 AI 会优先处理。第三CONTEXT.md要沉淀“决策理由”。这个文件不是功能说明书而是记录“为什么这么设计”。比如“选择使用自建 sitemap 而不是第三方插件因为项目里已经有了内容分级缓存自建方案更容易统一处理”。这个理由可能在三天后被挑战但如果没有人记得当时的决策背景重构时就会走弯路。第四避免状态文件过长。如果PLAN.md写了几百行AI 每次都要读一大段内容既增加 token 成本又容易分散注意力。更好的做法是让PLAN.md保持精简把更详细的背景信息放到具体任务对应的文档里用链接关联。文件的任务是告诉 AI “下一步做什么”而不是“所有细节都在这里”。第五把.wayfinder目录纳入 git 版本控制。这不是可选项而是必须项。因为状态文件一旦被误改或者 AI 更新时产生冲突git 可以帮你回滚。更重要的是如果你在分支上工作状态文件会跟随分支流动团队其他成员也能看到进度。从实践角度看跨会话规划的价值在单人项目里已经很有用在团队项目里则会被进一步放大。7. 跨会话规划常见问题与排查思路任何技能在真实项目里都会遇到意外情况。wayfinder 类技能的维护成本一般不高但有些问题如不及时处理会让整套流程迅速失去意义。下面用表格列出几个最常见的问题及排查思路。问题现象可能原因排查方法解决方案新会话里的 AI 完全无视技能文件技能文件目录命名不匹配工具约定检查工具文档确认技能目录名和文件名是否正确按工具的约定修改目录或在 AGENTS.md 中加入强制读取说明计划文件越来越大AI 每次读取耗时长缺少定期归档机制所有历史任务都堆在 PLAN.md 中检查 PLAN.md 大小和任务粒度将已完成的里程碑移到 ARCHIVE.md只保留当前里程碑在 PLAN.md进度文件与代码实际状态不一致更新进度依赖 AI 自觉缺少代码验证对比最近 git 提交记录和进度文件在 SKILL.md 中增加“完成一个任务前必须对照代码实测”的规则多个分支并行时状态文件互相覆盖状态文件作为普通文件提交没有隔离查看 git 分支历史和文件变更记录每个分支维护独立状态文件或把.wayfinder加入.gitignore并在本地保存CONTEXT.md 里出现过时决策AI 依然按旧方案执行没有标记决策状态和更新时间检查最近更新时间和相关代码在过时决策前加[DEPRECATED]标记并在 PROGRESS.md 中记录替代方案排查问题时有一条通用思路先看技能文件有没有被正确加载再看状态文件内容是否符合预期最后判断是模型行为问题还是流程设计问题。大多数情况下问题出在流程设计而不是模型能力。只要状态文件的粒度、位置和更新规则足够明确AI 其实不太容易跑偏。另一个容易踩坑的点是状态文件不要和业务代码逻辑耦合太深。比如不要把 AI 内部使用的临时标记写到业务代码的注释里否则后续 code review 和自动格式化工具会造成干扰。状态文件属于 AI 协作者的“工作草稿”边界要清晰。8. 工程实践建议把 wayfinder 变成团队协作的一部分跨会话规划在生产环境里能不能持续运转不取决于 skill 写得有多漂亮而取决于它有没有被纳入日常开发流程。这里给出几条值得认真落实的工程建议。第一把SKILL.md和项目模板绑定。在新项目初始化的时候就自动创建.wayfinder目录和初始状态文件。这样每个新项目都能默认支持跨会话规划不需要开发者额外回忆流程。如果你的团队使用自研脚手架可以把这个动作写进模板生成脚本里。第二配合 git commit 信息使用。每次 AI 完成一个里程碑要求它更新PLAN.md中的对应复选框同时在 commit message 里记录逻辑。这样做的好处是你可以在 git 历史里看到“计划 - 执行 - 记录”的完整链路。如果某个功能出了问题回溯的时候不是只能看代码 diff还能对照计划找偏差。第三定期做“计划对账”。建议每周花十分钟让 AI 读一遍当前的计划和进度对比代码里的实际实现找出已经完成但没勾选、或者已经废弃但还留在计划里的任务。“对账”的目的不是过度管理而是防止状态文件变成摆设。第四安全边界要提前定好。状态文件里可以记录技术决策、任务进度、接口约定但不要放密钥、明文密码、内部敏感数据。AI 工具在读取文件时可能会把内容发送给模型服务端任何包含凭据的内容都不应该写进计划文件。如果项目里有更严格的合规要求建议审查一下 AI 工具的数据处理策略。第五不要试图用这一个 skill 解决所有问题。wayfinder 擅长的是规划和跟踪它不擅长具体代码生成时的代码规范校验、依赖安全扫描、单元测试覆盖率分析。后者应该交给更专业的工具链来处理。把技能按职责拆开比把所有要求塞进一个 skill 更可靠。9. 总结从“一次性对话”到“持续项目协作”回到最初的问题AI 编程为什么在中小型项目里很好用一遇到真实工作就变味很大一部分原因是我们用“一次性对话”的方式去使用一个本质上没有跨会话记忆的工具。wayfinder 这类跨会话规划 skill 的价值正在于它提供了一条非常朴素的解决路径把状态显式地写到文件里用计划文件约束方向用进度文件记录位置用上下文文件沉淀决策。如果你正在尝试写自己的 skill我给你的建议是先从复制上面的最小示例开始跑通一个跨两天的任务体会一下“每次打开新会话AI 都记得昨天在干什么”是什么感受。跑通之后再根据自己的使用习惯调整目录结构和字段设计。很多人在第一次体验到这种连续性之后就很难回到原来那种反复解释需求的工作方式了。最后提醒一句这类技能类工具迭代速度很快具体工具对“技能目录”“技能名称”“触发方式”的约定可能随时变化。遇到新版本时优先查阅官方文档把本文当成理解原理和流程的起点而不是固定的配置手册。核心理念不会变让 AI 记住项目而不是让 AI 只记住对话。