这几年做 AI 辅助开发我最大的感受是单次对话里让模型写一个函数、修一个报错很容易一旦工作规模变大——比如“把这个旧系统迁移到新架构”“实现一个包含登录、权限、订单的完整模块”——单次会话根本装不下。任务做到一半上下文就乱了新开会话又得重新解释背景模型给出的方案经常前后矛盾。最近看了 Matt Pocock 分享的 wayfinder skill 实战思路发现他处理的正是这个痛点通过一个可复用的 skill让 AI 在多个会话之间保持对目标的统一理解并且把任意规模的工作拆成一份可持续跟踪的“路线图”。这篇文章我会围绕 wayfinder skill 展开先说明它解决什么问题再带你从零搭建一套可用的跨会话规划方案最后给出常见问题和工程建议。无论你是 AI 编程的重度用户还是想用 Claude 这类智能体来管理个人项目、开源任务、团队需求这篇文章的思路都适用。1. 背景与核心概念1.1 什么是 Agent Skill在继续之前先明确一个概念Agent Skill智能体技能。你可以把 Skill 理解成“预置给 AI 的一套专业工作手册”。它不是一个普通的提示词模板而是一个带有目录结构的文件夹里面可能包含一个SKILL.md文件描述这个技能的用途、触发条件和执行步骤若干参考文档、示例代码一些可执行的脚本或工具。当 AI 识别到当前任务符合某个 Skill 的描述时它会自动加载这套手册按照手册规定的流程来工作。好处是显而易见的工作流程被固化了AI 不会每次凭感觉自由发挥产出质量更稳定。wayfinder skill 就是这类技能中的一种只不过它专注的方向是“规划”。1.2 跨会话规划要解决什么问题大语言模型的上下文窗口虽然越来越大但它并不是无限长的。当你让 AI 处理一个持续数天、甚至数周的项目时会遇到三个很现实的问题第一上下文溢出。所有历史记录都塞在一个会话里很快就会超过模型的处理上限AI 开始“遗忘”早期信息。第二状态丢失。新开会话后AI 不再记得之前的决定、已完成的步骤、待办事项你需要花大量时间重新描述背景。第三目标漂移。如果每个会话都由 AI 临时发挥很容易出现方案不一致的情况尤其是当你不小心用了不同的措辞描述同一需求时。跨会话规划的思路是不把项目的全部状态放在 AI 的记忆里而是放到外部文件中。AI 每次会话开始时读取这些文件结束时更新这些文件。项目状态从一个会话“传递”到下一个会话AI 始终知道自己做到哪一步。1.3 wayfinder skill 在其中的位置wayfinder 这个名字很有意思直译是“探路者”。它的职责就像队伍里负责看地图、定路线的那个人不具体搬砖但保证每一步都知道往哪儿走。放在 AI 工作流里wayfinder skill 的核心职责包括理解用户给出的高目标把目标拆解成可执行的阶段和任务生成一份可持续更新的项目计划文件在任务的每个节点记录进度、状态、风险新会话启动时基于计划文件快速恢复上下文。如果你熟悉项目管理会发现它很像一个轻量级的项目管理方法论有目标、有阶段、有任务、有状态追踪。只不过执行者是 AI维护者是 AI 加你共同完成。2. 环境准备与版本说明在开始搭建设计之前先把环境和准备工作理清楚。2.1 运行环境说明wayfinder skill 本身不依赖特定的操作系统它本质上是文件加规则。你可以在 Windows、macOS、Linux 上使用只要你的 AI 工具支持自定义 Skill 机制即可。以当前主流的 Claude 生态为例Agent Skills 通常放在以下目录~/.claude/skills/ # 用户级技能所有项目可用 ~/.claude/projects/ # 项目级配置 ./.claude/skills/ # 项目级技能放在项目根目录和传统插件的区别在于Skill 不需要编译、不需要安装依赖只要你把文件夹放到指定位置AI 就能识别。2.2 版本与兼容性说明注意Agent Skills 功能仍在快速演进中不同版本的客户端对 Skill 的支持程度可能不同。本文示例基于以下假设你使用的 AI 工具支持自定义 Skill 目录当前 Claude 桌面端与 CLI 环境均有对应支持你的模型版本支持读取本地文件你拥有可用的订阅或 API 权限。如果你的工具版本不支持某种写法请以官方文档为准。重点是理解 wayfinder skill 的设计模式而不是死记某一个文件夹路径。2.3 准备工作清单在动手前建议准备一个用于测试的空项目文件夹例如wayfinder-demo你常用的 AI 客户端能配置自定义 Skill一个真实的、规模适中的目标任务不要用“写个 Hello World”这种太简单的任务至少要包含三四个步骤才能感受到规划的价值基本的命令行操作能力会创建文件夹、编辑 Markdown 文件即可。3. 理解 wayfinder skill 的核心设计在写具体代码之前我们先把 wayfinder skill 的工作原理讲透。如果只复制文件不理解机制遇到问题你还是不会排查。3.1 状态外置wayfinder skill 最关键的设计原则是“状态外置”。AI 的记忆是不可靠的但文件是可靠的。我们约定一个固定的状态目录例如wayfinder/state/里面存放goal.md目标描述一句话说清楚要完成什么plan.md完整计划包含阶段划分、任务列表、依赖关系progress.md进度跟踪记录当前进行到哪一步、阻塞在哪、下一步做什么decisions.md决策日志记录重要决定的背景和结果。这四个文件的职责划分非常明确目标是锚点防止 AI 跑偏计划是地图告诉 AI 有哪些路径进度是当前位置告诉 AI 已经在哪儿决策日志是历史告诉 AI 为什么这样做。当 AI 开始工作时它先读取这四个文件当它完成一个阶段时它同步更新这四个文件。新会话启动后同样先读取再继续。状态就这样跨会话地延续下来了。3.2 任务分解的粒度控制很多人在让 AI 规划时会犯一个错误把任务拆得太粗或者拆得太碎。拆得太粗AI 面对一个“实现用户模块”的任务时依然无从下手拆得太碎比如“点击按钮”“弹出提示框”这种级别也写进计划里会让计划文件无比臃肿AI 加载效率变低。wayfinder skill 推荐一种分层结构目标goal └── 里程碑milestone └── 任务task └── 子步骤subtask可选在plan.md文件中只需要维护到“任务”级别具体到“子步骤”时让 AI 在真正执行该任务的那个会话里去展开。这样既保证了全局视野又不让计划文件过度膨胀。用实际项目来举例。目标是“把博客从 WordPress 迁移到 Astro”那么计划可以写成里程碑 M1内容迁移 任务 M1-T1导出 WordPress 文章与图片 任务 M1-T2清洗 Markdown 格式 任务 M1-T3建立文章目录结构 里程碑 M2主题开发 任务 M2-T1搭建 Astro 项目骨架 任务 M2-T2设计首页布局 ...这种粒度AI 在任何一个会话里都能清晰地知道自己正在处理哪一块又不会被大量实现细节淹没。3.3 会话启动与收尾流程wayfinder skill 要求 AI 在每次会话时执行一个固定的流程通常写在SKILL.md中。这个流程大致是这样的会话启动时读取goal.md确认项目目标读取plan.md确认整体计划读取progress.md确认当前进度读取decisions.md了解历史决策根据这些信息向用户汇报“当前状态 建议的下一步”。会话进行中每完成一个任务就更新progress.md如果发现计划不合理修改plan.md并记录原因如果做了重要决定追加到decisions.md。会话结束时更新progress.md写清当前完成到哪一步如果有遗留问题或风险写进progress.md的“风险”区域推荐下一步可以开一个新会话继续。这套流程确保了一个会话的结束不是项目的中断而是下一个会话的起点。4. 完整实战从零搭建 wayfinder skill接下来我们实际动手。我会带你创建一个最小可用的 wayfinder skill并用一个示例任务做全流程演示。4.1 创建项目目录结构首先在测试目录里创建项目结构和技能目录mkdir -p wayfinder-demo/.claude/skills/wayfinder mkdir -p wayfinder-demo/wayfinder/state cd wayfinder-demo目录说明.claude/skills/wayfinder/存放 skill 定义文件wayfinder/state/存放当前项目的规划状态文件。你也可以把 skill 放在用户全局目录~/.claude/skills/这样所有项目都能用。实际项目中更推荐先放项目目录验证没问题后再考虑全局化。4.2 编写 SKILL.md 核心文件在.claude/skills/wayfinder/下创建SKILL.md。这是 skill 的核心AI 会通过它来理解你希望它如何工作。--- name: wayfinder description: 用于跨会话规划和管理任意规模的工作。当用户提出一个复杂的、多步骤的目标或希望跟踪项目进度时使用本技能。 --- # wayfinder skill 你是一个项目规划与进度管理专家。你的目标是在多个会话之间维持对项目目标的统一理解持续跟踪进度并保证任务持续推进。 ## 工作方式 1. 在启动任何任务之前先读取状态目录中的四个文件 - wayfinder/state/goal.md - wayfinder/state/plan.md - wayfinder/state/progress.md - wayfinder/state/decisions.md 2. 如果这些文件不存在先向用户确认目标然后初始化这几个文件。 3. 每次会话开始向用户汇报 - 目标一句话复述当前目标 - 进度当前完成到哪一步 - 下一步建议接下来处理哪个任务。 4. 每次会话中完成一个任务后立即更新 progress.md。 5. 每次会话结束前更新 progress.md 与 decisions.md。 ## 计划文件格式 plan.md 使用以下格式项目计划目标来自 goal.md里程碑M1里程碑名称[ ] M1-T1任务描述[ ] M1-T2任务描述M2里程碑名称[ ] M2-T1任务描述## 进度文件格式 progress.md 使用以下格式进度跟踪当前状态开始日期预计结束日期完成里程碑当前里程碑任务状态[x] M1-T1任务描述完成日期[ ] M1-T2任务描述进行中[ ] M1-T3任务描述未开始阻塞与风险无下一步## 原则 - 不要在没有确认目标的情况下直接开始规划。 - 计划必须可执行每个任务都要有明确的完成标准。 - 如果任务规模很小且可以在一次会话中完成不必强行使用本技能。这个文件是 wayfinder skill 的行为核心。它规定了 AI 如何在会话之间传递信息。4.3 编写辅助脚本可选Markdown 文件已经足够完成大部分工作但如果你希望状态更新更规范可以写一个简单的 shell 脚本用于初始化状态目录。创建scripts/init-wayfinder.sh#!/usr/bin/env bash # 初始化 wayfinder 状态目录 set -euo pipefail STATE_DIRwayfinder/state if [ ! -d $STATE_DIR ]; then mkdir -p $STATE_DIR fi if [ ! -f $STATE_DIR/goal.md ]; then cat $STATE_DIR/goal.md EOF # 项目目标 在这里描述你的目标。要求具体、可衡量、有时限。 EOF fi if [ ! -f $STATE_DIR/plan.md ]; then cat $STATE_DIR/plan.md EOF # 项目计划 ## 目标 来自 goal.md ## 里程碑 ### M1第一个里程碑 - [ ] M1-T1第一个任务 EOF fi if [ ! -f $STATE_DIR/progress.md ]; then cat $STATE_DIR/progress.md EOF # 进度跟踪 ## 当前状态 - 开始日期 - 预计结束日期 - 完成里程碑 - 当前里程碑 ## 任务状态 - [ ] M1-T1第一个任务未开始 ## 阻塞与风险 - 无 ## 下一步 - 等待用户确认目标 EOF fi if [ ! -f $STATE_DIR/decisions.md ]; then cat $STATE_DIR/decisions.md EOF # 决策日志 记录项目中重要的决策和原因。 | 日期 | 决策 | 原因 | | --- | --- | --- | | 日期 | 决策内容 | 决策原因 | EOF fi echo wayfinder 状态目录初始化完成$STATE_DIR然后给它执行权限chmod x scripts/init-wayfinder.sh这个脚本不是必须的。它的价值在于当你要开始一个新项目时不用手动创建四个文件和模板一条命令就能搞定。4.4 初始化一个实际任务现在我们来跑一个实际任务。为了演示效果我选一个中等复杂度的目标“为一款待办事项 Web 应用编写完整的后端 API包含用户注册、登录、任务 CRUD并输出 API 文档”。先执行初始化脚本./scripts/init-wayfinder.sh然后打开wayfinder/state/goal.md填入目标# 项目目标 为一款待办事项 Web 应用编写完整的后端 API包含用户注册、登录、任务增删改查并输出 API 文档。技术栈为 Node.js Express SQLite要求接口有基础的认证保护。接着打开wayfinder/state/plan.md我们手动把初始计划拆出来。这一步你也可以让 AI 帮你拆但为了演示方式我直接给你看一个合理的结果# 项目计划 ## 目标 为一款待办事项 Web 应用编写完整的后端 API包含用户注册、登录、任务增删改查并输出 API 文档。技术栈为 Node.js Express SQLite。 ## 里程碑 ### M1项目基础搭建 - [ ] M1-T1初始化 Node.js 项目并安装 Express、sqlite3 依赖 - [ ] M1-T2搭建项目目录结构routes、controllers、db、middleware ### M2用户认证 - [ ] M2-T1创建用户表结构 - [ ] M2-T2实现注册接口密码加密存储 - [ ] M2-T3实现登录接口返回 JWT Token - [ ] M2-T4实现认证中间件 ### M3任务管理 - [ ] M3-T1创建任务表结构 - [ ] M3-T2实现任务的创建、查询接口 - [ ] M3-T3实现任务的更新、删除接口 ### M4文档与收尾 - [ ] M4-T1编写 README 与 API 文档 - [ ] M4-T2编写基础测试用例这个计划并不算特别复杂但它已经足以体现 wayfinder skill 的价值。你会看到 AI 在后面工作时能清晰地知道自己处于哪个里程碑。4.5 在 AI 工具中调试和验证现在把整个wayfinder-demo文件夹作为项目目录打开。在 AI 工具中开启一个新对话输入请使用 wayfinder skill。我们现在开始项目当前处于第一步。再看看 AI 的回复。理想情况下AI 会先读取SKILL.md然后读取四个状态文件并输出类似这样的内容我已加载 wayfinder skill。 当前目标为待办事项应用编写完整的后端 API包括用户注册、登录、任务 CRUD。 当前进度项目管理状态已初始化计划已拆分为 4 个里程碑、10 个任务当前还没有任务开始执行。 建议下一步处理 M1-T1初始化 Node.js 项目并安装依赖。是否现在开始如果 AI 给你的是这段话说明 wayfinder skill 已经被正确识别并激活。接下来你只需要回复“开始”AI 就会按照计划执行并在完成一个任务后更新wayfinder/state/progress.md。会话结束后你关掉对话第二天新开一个会话再次说“继续”你会发现 AI 能准确接上昨天的进度。5. 在 Claude 项目中配置 wayfinder skill如果你使用的是 Claude 项目功能还可以把 wayfinder skill 与项目级配置结合得更紧密。5.1 创建项目级 CLAUDE.md在项目根目录创建.claude/CLAUDE.md写入以下内容# 项目说明 本项目使用 wayfinder skill 进行跨会话规划。 - 如果用户提到“规划”“继续”“记录进度”“下一步”默认使用 wayfinder skill。 - 状态文件保存在 wayfinder/state/ 目录下。 - 每次会话开始先读取 wayfinder/state/ 下的状态文件。 - 会话结束前确保进度文件已更新。这样 AI 在启动时会自动把 wayfinder skill 当作项目的默认工作方式不需要每次手动声明。5.2 配置 .gitignore如果项目使用 Git 管理建议把不必要上传的内容排除掉。但注意状态文件是否入库需要根据项目情况决定。个人项目推荐把状态文件也提交到 Git这样你有一份历史记录可以回溯目标的变更过程。如果是团队项目也可以选择提交便于成员了解项目进度。如果你不希望提交可以添加node_modules/ .DS_Store但不要盲目忽略wayfinder/state/除非你明确知道自己在做什么。5.3 结合项目需求微调 plan实际情况下AI 拆解的计划不一定完全符合你的期望。wayfinder skill 的设计允许你随时修改plan.md。当你修改计划时有两个选择直接把新计划覆盖到plan.md然后告诉 AI“计划已更新请按新计划继续”把修改记录下来在decisions.md中追加一条决策。第二种方式更推荐尤其是当你改变了任务优先级、增加或删除了里程碑时。这些调整的原因如果写下来未来的你和 AI 都能理解为什么计划会变成现在这样。6. 常见问题与排查思路wayfinder skill 的使用过程中有些问题比较典型。下面整理了一张排查表。问题现象常见原因解决思路AI 不认 wayfinder skillSKILL.md 文件路径不对或格式不对检查文件是否在.claude/skills/wayfinder/下检查 frontmatter 的name字段AI 读取了 skill 但没读取状态文件状态目录不是wayfinder/state或工作目录不对确认项目根目录路径检查SKILL.md中的状态路径是否匹配计划文件越来越臃肿任务拆解粒度太细或步骤没有及时清理控制计划只保留里程碑和任务子步骤在执行会话内展开新会话接不上进度上一个会话结束前没有更新 progress.md在SKILL.md中强调会话收尾必须更新文件目标被改得面目全非用户在不同会话中换了说法AI 直接按新说法执行在goal.md中坚持原文维护修改目标必须同步更新 plan多个任务并行时状态混乱没有给任务设置明确的进行中状态在 progress.md 中标记唯一一个“进行中”任务不要同时标多个AI 跳过计划直接实现没有严格执行 SKILL.md 中的流程在 Claude 项目配置中加强约束或手动提醒 AI 先读计划再动手6.1 关于“AI 不认 skill”的深入排查最常被忽略的是文件路径。注意.claude是隐藏目录在 macOS 和 Linux 下默认不显示。如果你使用图形化文件管理器需要按键显示隐藏文件才能看到。另外SKILL.md的 frontmatter 格式必须正确。frontmatter 是位于文件最顶部的---包裹的元信息区域里面的name和description字段是 AI 识别 skill 的依据。如果---缺失或格式错误AI 可能把整个文件当作普通 Markdown 读取。最直接的验证方式是在对话中问 AI你当前知道了哪些可用技能它们的名称和功能是什么如果 AI 列出了 wayfinder说明它已经被加载。如果没有优先检查路径和格式。6.2 关于“上下文还是不够”的处理有同学可能会问跨会话规划能解决上下文不足的问题吗答案是部分解决。wayfinder skill 解决的是“项目级上下文”的持久化问题而不是“单次任务上下文”的膨胀问题。如果某个任务本身太大即使有规划文件AI 在单个会话中依然可能因为要处理的代码太多而丢失细节。这时需要进一步拆分任务或者把大文件拆成多个小文件让 AI 在单次会话中只聚焦一块内容。这也解释了为什么 wayfinder skill 要求任务粒度适中。任务太长单会话做不完任务太短管理成本又过高。找到一个合适的粒度是使用这个技能最重要的调优工作。7. 最佳实践与工程建议7.1 把 goal.md 当作文档锚点项目进行到一半时最常见的问题是“AI 已经不知道当初为什么要做这个项目”。目标文件就是为了解决这个问题。建议goal.md的内容包含几个要素一句话目标明确的技术栈可交付的成果明确不做什么这是很多人忽略的。例如# 项目目标 为一款待办事项 Web 应用编写完整的后端 API包含用户注册、登录、任务增删改查并输出 API 文档。 技术栈Node.js Express SQLite 交付物可运行的 API 项目 README 文档 基础测试 不包含前端页面开发、第三方登录、部署上线“不包含”这部分很重要。AI 经常会自主发挥做一些超出需求范围的事情。“不包含”是一个边界能有效防止范围蔓延。7.2 进度文件保持简单progress.md不需要写长篇大论。它的核心价值就在于一眼看清“现在到哪了”。建议保持以下几个区域不变当前状态任务状态阻塞与风险下一步。其中“阻塞与风险”这个区域要主动维护。AI 在执行任务时如果遇到无法解决的问题应该让它记录在这里而不是自己硬猜一个方案。这样你下次打开项目时能第一时间看到卡点在哪里。7.3 决策日志是团队协作的粘合剂如果你是单人使用 wayfinder决策日志的价值可能不如团队场景明显。但如果你和同事共享同一个项目仓库决策日志就变得非常重要。比如为什么这个任务用 JWT 而不是 session为什么优先做认证而不是任务模块这些决定如果不记录新加入的同事就得重新问一遍甚至可能推翻之前的方案。建议决策日志使用简单的表格| 日期 | 决策 | 原因 | | --- | --- | --- | | 2025-06-01 | 使用 JWT 做认证 | 前端是纯静态页面无 session 服务端 | | 2025-06-02 | 先实现认证模块 | 任务接口都依赖用户身份 |7.4 注意安全边界使用 wayfinder skill 规划项目时AI 可能会在执行中提出一些高风险操作比如批量删除数据、修改生产配置、执行数据库迁移等。在项目规划阶段就要明确需要你确认后AI 才能执行高风险动作。你可以在SKILL.md中增加一条规则- 涉及删除、清空、覆盖大量数据的操作必须先向用户确认并获得明确授权。 - 涉及生产环境的操作默认禁止执行除非用户明确给出足够的说明。这既是保护项目也是培养 AI 使用的好习惯。特别是在团队项目里未授权的破坏性操作可能带来连锁影响。7.5 不要过度依赖 skill最后一条建议可能听起来有点反直觉不要把一切任务都交给 wayfinder。如果任务只需要一次对话就能完成完全可以不用 skill。使用规划反而增加了额外的文件写入和读取成本是一种“杀鸡用牛刀”。更好的做法是在SKILL.md的description中写清楚触发条件让 AI 判断什么场景需要、什么场景不需要。比如description: 用于跨会话规划和管理任意规模的工作。当任务涉及多个步骤、可能持续多个会话或需要长期跟踪时使用。这样 AI 会在合适的场景自动选择使用 wayfinder而不是每次对话都机械地加载它。8. 总结与学习路线wayfinder skill 的本质是把“目标—计划—进度—决策”这套项目管理的基本功用文件的形式固化下来让 AI 在跨会话、跨任务时依然保持清晰的路线感。它不依赖某个神秘的模型能力也不需要复杂的代码核心就是四个 Markdown 文件加一份行为约束。如果你从零开始实践建议按这条路线推进第一步先手动创建一个项目把goal.md、plan.md、progress.md、decisions.md四个文件建好不急着写SKILL.md。自己手动维护几次体会一下“状态外置”的感觉。第二步再把SKILL.md加进去让 AI 自动维护这些文件。注意观察 AI 是否会主动更新进度如果不会就在SKILL.md中加强约束。第三步用真实的中型项目去验证。至少找一个需要多个会话才能完成的任务坚持用 wayfinder 跑完感受和之前“每次新会话都重新讲解背景”的差异。第四步根据你的使用习惯调整模板。你可以增加风险登记表、工时估算、验收标准等字段把 wayfinder 慢慢变成你自己的项目管理助手。跨会话工作流是一个值得长期实践的方向。下一次当你面对一个复杂任务与其在同一个会话里反复拉扯不如先建一个 wayfinder 状态目录把目标写进去然后一点一点推进。希望这套思路能帮你把 AI 从“单次对话的工具”升级成“长期协作的搭档”。 Wayfinder Skill实战：让AI跨会话持续跟踪项目规划
这几年做 AI 辅助开发我最大的感受是单次对话里让模型写一个函数、修一个报错很容易一旦工作规模变大——比如“把这个旧系统迁移到新架构”“实现一个包含登录、权限、订单的完整模块”——单次会话根本装不下。任务做到一半上下文就乱了新开会话又得重新解释背景模型给出的方案经常前后矛盾。最近看了 Matt Pocock 分享的 wayfinder skill 实战思路发现他处理的正是这个痛点通过一个可复用的 skill让 AI 在多个会话之间保持对目标的统一理解并且把任意规模的工作拆成一份可持续跟踪的“路线图”。这篇文章我会围绕 wayfinder skill 展开先说明它解决什么问题再带你从零搭建一套可用的跨会话规划方案最后给出常见问题和工程建议。无论你是 AI 编程的重度用户还是想用 Claude 这类智能体来管理个人项目、开源任务、团队需求这篇文章的思路都适用。1. 背景与核心概念1.1 什么是 Agent Skill在继续之前先明确一个概念Agent Skill智能体技能。你可以把 Skill 理解成“预置给 AI 的一套专业工作手册”。它不是一个普通的提示词模板而是一个带有目录结构的文件夹里面可能包含一个SKILL.md文件描述这个技能的用途、触发条件和执行步骤若干参考文档、示例代码一些可执行的脚本或工具。当 AI 识别到当前任务符合某个 Skill 的描述时它会自动加载这套手册按照手册规定的流程来工作。好处是显而易见的工作流程被固化了AI 不会每次凭感觉自由发挥产出质量更稳定。wayfinder skill 就是这类技能中的一种只不过它专注的方向是“规划”。1.2 跨会话规划要解决什么问题大语言模型的上下文窗口虽然越来越大但它并不是无限长的。当你让 AI 处理一个持续数天、甚至数周的项目时会遇到三个很现实的问题第一上下文溢出。所有历史记录都塞在一个会话里很快就会超过模型的处理上限AI 开始“遗忘”早期信息。第二状态丢失。新开会话后AI 不再记得之前的决定、已完成的步骤、待办事项你需要花大量时间重新描述背景。第三目标漂移。如果每个会话都由 AI 临时发挥很容易出现方案不一致的情况尤其是当你不小心用了不同的措辞描述同一需求时。跨会话规划的思路是不把项目的全部状态放在 AI 的记忆里而是放到外部文件中。AI 每次会话开始时读取这些文件结束时更新这些文件。项目状态从一个会话“传递”到下一个会话AI 始终知道自己做到哪一步。1.3 wayfinder skill 在其中的位置wayfinder 这个名字很有意思直译是“探路者”。它的职责就像队伍里负责看地图、定路线的那个人不具体搬砖但保证每一步都知道往哪儿走。放在 AI 工作流里wayfinder skill 的核心职责包括理解用户给出的高目标把目标拆解成可执行的阶段和任务生成一份可持续更新的项目计划文件在任务的每个节点记录进度、状态、风险新会话启动时基于计划文件快速恢复上下文。如果你熟悉项目管理会发现它很像一个轻量级的项目管理方法论有目标、有阶段、有任务、有状态追踪。只不过执行者是 AI维护者是 AI 加你共同完成。2. 环境准备与版本说明在开始搭建设计之前先把环境和准备工作理清楚。2.1 运行环境说明wayfinder skill 本身不依赖特定的操作系统它本质上是文件加规则。你可以在 Windows、macOS、Linux 上使用只要你的 AI 工具支持自定义 Skill 机制即可。以当前主流的 Claude 生态为例Agent Skills 通常放在以下目录~/.claude/skills/ # 用户级技能所有项目可用 ~/.claude/projects/ # 项目级配置 ./.claude/skills/ # 项目级技能放在项目根目录和传统插件的区别在于Skill 不需要编译、不需要安装依赖只要你把文件夹放到指定位置AI 就能识别。2.2 版本与兼容性说明注意Agent Skills 功能仍在快速演进中不同版本的客户端对 Skill 的支持程度可能不同。本文示例基于以下假设你使用的 AI 工具支持自定义 Skill 目录当前 Claude 桌面端与 CLI 环境均有对应支持你的模型版本支持读取本地文件你拥有可用的订阅或 API 权限。如果你的工具版本不支持某种写法请以官方文档为准。重点是理解 wayfinder skill 的设计模式而不是死记某一个文件夹路径。2.3 准备工作清单在动手前建议准备一个用于测试的空项目文件夹例如wayfinder-demo你常用的 AI 客户端能配置自定义 Skill一个真实的、规模适中的目标任务不要用“写个 Hello World”这种太简单的任务至少要包含三四个步骤才能感受到规划的价值基本的命令行操作能力会创建文件夹、编辑 Markdown 文件即可。3. 理解 wayfinder skill 的核心设计在写具体代码之前我们先把 wayfinder skill 的工作原理讲透。如果只复制文件不理解机制遇到问题你还是不会排查。3.1 状态外置wayfinder skill 最关键的设计原则是“状态外置”。AI 的记忆是不可靠的但文件是可靠的。我们约定一个固定的状态目录例如wayfinder/state/里面存放goal.md目标描述一句话说清楚要完成什么plan.md完整计划包含阶段划分、任务列表、依赖关系progress.md进度跟踪记录当前进行到哪一步、阻塞在哪、下一步做什么decisions.md决策日志记录重要决定的背景和结果。这四个文件的职责划分非常明确目标是锚点防止 AI 跑偏计划是地图告诉 AI 有哪些路径进度是当前位置告诉 AI 已经在哪儿决策日志是历史告诉 AI 为什么这样做。当 AI 开始工作时它先读取这四个文件当它完成一个阶段时它同步更新这四个文件。新会话启动后同样先读取再继续。状态就这样跨会话地延续下来了。3.2 任务分解的粒度控制很多人在让 AI 规划时会犯一个错误把任务拆得太粗或者拆得太碎。拆得太粗AI 面对一个“实现用户模块”的任务时依然无从下手拆得太碎比如“点击按钮”“弹出提示框”这种级别也写进计划里会让计划文件无比臃肿AI 加载效率变低。wayfinder skill 推荐一种分层结构目标goal └── 里程碑milestone └── 任务task └── 子步骤subtask可选在plan.md文件中只需要维护到“任务”级别具体到“子步骤”时让 AI 在真正执行该任务的那个会话里去展开。这样既保证了全局视野又不让计划文件过度膨胀。用实际项目来举例。目标是“把博客从 WordPress 迁移到 Astro”那么计划可以写成里程碑 M1内容迁移 任务 M1-T1导出 WordPress 文章与图片 任务 M1-T2清洗 Markdown 格式 任务 M1-T3建立文章目录结构 里程碑 M2主题开发 任务 M2-T1搭建 Astro 项目骨架 任务 M2-T2设计首页布局 ...这种粒度AI 在任何一个会话里都能清晰地知道自己正在处理哪一块又不会被大量实现细节淹没。3.3 会话启动与收尾流程wayfinder skill 要求 AI 在每次会话时执行一个固定的流程通常写在SKILL.md中。这个流程大致是这样的会话启动时读取goal.md确认项目目标读取plan.md确认整体计划读取progress.md确认当前进度读取decisions.md了解历史决策根据这些信息向用户汇报“当前状态 建议的下一步”。会话进行中每完成一个任务就更新progress.md如果发现计划不合理修改plan.md并记录原因如果做了重要决定追加到decisions.md。会话结束时更新progress.md写清当前完成到哪一步如果有遗留问题或风险写进progress.md的“风险”区域推荐下一步可以开一个新会话继续。这套流程确保了一个会话的结束不是项目的中断而是下一个会话的起点。4. 完整实战从零搭建 wayfinder skill接下来我们实际动手。我会带你创建一个最小可用的 wayfinder skill并用一个示例任务做全流程演示。4.1 创建项目目录结构首先在测试目录里创建项目结构和技能目录mkdir -p wayfinder-demo/.claude/skills/wayfinder mkdir -p wayfinder-demo/wayfinder/state cd wayfinder-demo目录说明.claude/skills/wayfinder/存放 skill 定义文件wayfinder/state/存放当前项目的规划状态文件。你也可以把 skill 放在用户全局目录~/.claude/skills/这样所有项目都能用。实际项目中更推荐先放项目目录验证没问题后再考虑全局化。4.2 编写 SKILL.md 核心文件在.claude/skills/wayfinder/下创建SKILL.md。这是 skill 的核心AI 会通过它来理解你希望它如何工作。--- name: wayfinder description: 用于跨会话规划和管理任意规模的工作。当用户提出一个复杂的、多步骤的目标或希望跟踪项目进度时使用本技能。 --- # wayfinder skill 你是一个项目规划与进度管理专家。你的目标是在多个会话之间维持对项目目标的统一理解持续跟踪进度并保证任务持续推进。 ## 工作方式 1. 在启动任何任务之前先读取状态目录中的四个文件 - wayfinder/state/goal.md - wayfinder/state/plan.md - wayfinder/state/progress.md - wayfinder/state/decisions.md 2. 如果这些文件不存在先向用户确认目标然后初始化这几个文件。 3. 每次会话开始向用户汇报 - 目标一句话复述当前目标 - 进度当前完成到哪一步 - 下一步建议接下来处理哪个任务。 4. 每次会话中完成一个任务后立即更新 progress.md。 5. 每次会话结束前更新 progress.md 与 decisions.md。 ## 计划文件格式 plan.md 使用以下格式项目计划目标来自 goal.md里程碑M1里程碑名称[ ] M1-T1任务描述[ ] M1-T2任务描述M2里程碑名称[ ] M2-T1任务描述## 进度文件格式 progress.md 使用以下格式进度跟踪当前状态开始日期预计结束日期完成里程碑当前里程碑任务状态[x] M1-T1任务描述完成日期[ ] M1-T2任务描述进行中[ ] M1-T3任务描述未开始阻塞与风险无下一步## 原则 - 不要在没有确认目标的情况下直接开始规划。 - 计划必须可执行每个任务都要有明确的完成标准。 - 如果任务规模很小且可以在一次会话中完成不必强行使用本技能。这个文件是 wayfinder skill 的行为核心。它规定了 AI 如何在会话之间传递信息。4.3 编写辅助脚本可选Markdown 文件已经足够完成大部分工作但如果你希望状态更新更规范可以写一个简单的 shell 脚本用于初始化状态目录。创建scripts/init-wayfinder.sh#!/usr/bin/env bash # 初始化 wayfinder 状态目录 set -euo pipefail STATE_DIRwayfinder/state if [ ! -d $STATE_DIR ]; then mkdir -p $STATE_DIR fi if [ ! -f $STATE_DIR/goal.md ]; then cat $STATE_DIR/goal.md EOF # 项目目标 在这里描述你的目标。要求具体、可衡量、有时限。 EOF fi if [ ! -f $STATE_DIR/plan.md ]; then cat $STATE_DIR/plan.md EOF # 项目计划 ## 目标 来自 goal.md ## 里程碑 ### M1第一个里程碑 - [ ] M1-T1第一个任务 EOF fi if [ ! -f $STATE_DIR/progress.md ]; then cat $STATE_DIR/progress.md EOF # 进度跟踪 ## 当前状态 - 开始日期 - 预计结束日期 - 完成里程碑 - 当前里程碑 ## 任务状态 - [ ] M1-T1第一个任务未开始 ## 阻塞与风险 - 无 ## 下一步 - 等待用户确认目标 EOF fi if [ ! -f $STATE_DIR/decisions.md ]; then cat $STATE_DIR/decisions.md EOF # 决策日志 记录项目中重要的决策和原因。 | 日期 | 决策 | 原因 | | --- | --- | --- | | 日期 | 决策内容 | 决策原因 | EOF fi echo wayfinder 状态目录初始化完成$STATE_DIR然后给它执行权限chmod x scripts/init-wayfinder.sh这个脚本不是必须的。它的价值在于当你要开始一个新项目时不用手动创建四个文件和模板一条命令就能搞定。4.4 初始化一个实际任务现在我们来跑一个实际任务。为了演示效果我选一个中等复杂度的目标“为一款待办事项 Web 应用编写完整的后端 API包含用户注册、登录、任务 CRUD并输出 API 文档”。先执行初始化脚本./scripts/init-wayfinder.sh然后打开wayfinder/state/goal.md填入目标# 项目目标 为一款待办事项 Web 应用编写完整的后端 API包含用户注册、登录、任务增删改查并输出 API 文档。技术栈为 Node.js Express SQLite要求接口有基础的认证保护。接着打开wayfinder/state/plan.md我们手动把初始计划拆出来。这一步你也可以让 AI 帮你拆但为了演示方式我直接给你看一个合理的结果# 项目计划 ## 目标 为一款待办事项 Web 应用编写完整的后端 API包含用户注册、登录、任务增删改查并输出 API 文档。技术栈为 Node.js Express SQLite。 ## 里程碑 ### M1项目基础搭建 - [ ] M1-T1初始化 Node.js 项目并安装 Express、sqlite3 依赖 - [ ] M1-T2搭建项目目录结构routes、controllers、db、middleware ### M2用户认证 - [ ] M2-T1创建用户表结构 - [ ] M2-T2实现注册接口密码加密存储 - [ ] M2-T3实现登录接口返回 JWT Token - [ ] M2-T4实现认证中间件 ### M3任务管理 - [ ] M3-T1创建任务表结构 - [ ] M3-T2实现任务的创建、查询接口 - [ ] M3-T3实现任务的更新、删除接口 ### M4文档与收尾 - [ ] M4-T1编写 README 与 API 文档 - [ ] M4-T2编写基础测试用例这个计划并不算特别复杂但它已经足以体现 wayfinder skill 的价值。你会看到 AI 在后面工作时能清晰地知道自己处于哪个里程碑。4.5 在 AI 工具中调试和验证现在把整个wayfinder-demo文件夹作为项目目录打开。在 AI 工具中开启一个新对话输入请使用 wayfinder skill。我们现在开始项目当前处于第一步。再看看 AI 的回复。理想情况下AI 会先读取SKILL.md然后读取四个状态文件并输出类似这样的内容我已加载 wayfinder skill。 当前目标为待办事项应用编写完整的后端 API包括用户注册、登录、任务 CRUD。 当前进度项目管理状态已初始化计划已拆分为 4 个里程碑、10 个任务当前还没有任务开始执行。 建议下一步处理 M1-T1初始化 Node.js 项目并安装依赖。是否现在开始如果 AI 给你的是这段话说明 wayfinder skill 已经被正确识别并激活。接下来你只需要回复“开始”AI 就会按照计划执行并在完成一个任务后更新wayfinder/state/progress.md。会话结束后你关掉对话第二天新开一个会话再次说“继续”你会发现 AI 能准确接上昨天的进度。5. 在 Claude 项目中配置 wayfinder skill如果你使用的是 Claude 项目功能还可以把 wayfinder skill 与项目级配置结合得更紧密。5.1 创建项目级 CLAUDE.md在项目根目录创建.claude/CLAUDE.md写入以下内容# 项目说明 本项目使用 wayfinder skill 进行跨会话规划。 - 如果用户提到“规划”“继续”“记录进度”“下一步”默认使用 wayfinder skill。 - 状态文件保存在 wayfinder/state/ 目录下。 - 每次会话开始先读取 wayfinder/state/ 下的状态文件。 - 会话结束前确保进度文件已更新。这样 AI 在启动时会自动把 wayfinder skill 当作项目的默认工作方式不需要每次手动声明。5.2 配置 .gitignore如果项目使用 Git 管理建议把不必要上传的内容排除掉。但注意状态文件是否入库需要根据项目情况决定。个人项目推荐把状态文件也提交到 Git这样你有一份历史记录可以回溯目标的变更过程。如果是团队项目也可以选择提交便于成员了解项目进度。如果你不希望提交可以添加node_modules/ .DS_Store但不要盲目忽略wayfinder/state/除非你明确知道自己在做什么。5.3 结合项目需求微调 plan实际情况下AI 拆解的计划不一定完全符合你的期望。wayfinder skill 的设计允许你随时修改plan.md。当你修改计划时有两个选择直接把新计划覆盖到plan.md然后告诉 AI“计划已更新请按新计划继续”把修改记录下来在decisions.md中追加一条决策。第二种方式更推荐尤其是当你改变了任务优先级、增加或删除了里程碑时。这些调整的原因如果写下来未来的你和 AI 都能理解为什么计划会变成现在这样。6. 常见问题与排查思路wayfinder skill 的使用过程中有些问题比较典型。下面整理了一张排查表。问题现象常见原因解决思路AI 不认 wayfinder skillSKILL.md 文件路径不对或格式不对检查文件是否在.claude/skills/wayfinder/下检查 frontmatter 的name字段AI 读取了 skill 但没读取状态文件状态目录不是wayfinder/state或工作目录不对确认项目根目录路径检查SKILL.md中的状态路径是否匹配计划文件越来越臃肿任务拆解粒度太细或步骤没有及时清理控制计划只保留里程碑和任务子步骤在执行会话内展开新会话接不上进度上一个会话结束前没有更新 progress.md在SKILL.md中强调会话收尾必须更新文件目标被改得面目全非用户在不同会话中换了说法AI 直接按新说法执行在goal.md中坚持原文维护修改目标必须同步更新 plan多个任务并行时状态混乱没有给任务设置明确的进行中状态在 progress.md 中标记唯一一个“进行中”任务不要同时标多个AI 跳过计划直接实现没有严格执行 SKILL.md 中的流程在 Claude 项目配置中加强约束或手动提醒 AI 先读计划再动手6.1 关于“AI 不认 skill”的深入排查最常被忽略的是文件路径。注意.claude是隐藏目录在 macOS 和 Linux 下默认不显示。如果你使用图形化文件管理器需要按键显示隐藏文件才能看到。另外SKILL.md的 frontmatter 格式必须正确。frontmatter 是位于文件最顶部的---包裹的元信息区域里面的name和description字段是 AI 识别 skill 的依据。如果---缺失或格式错误AI 可能把整个文件当作普通 Markdown 读取。最直接的验证方式是在对话中问 AI你当前知道了哪些可用技能它们的名称和功能是什么如果 AI 列出了 wayfinder说明它已经被加载。如果没有优先检查路径和格式。6.2 关于“上下文还是不够”的处理有同学可能会问跨会话规划能解决上下文不足的问题吗答案是部分解决。wayfinder skill 解决的是“项目级上下文”的持久化问题而不是“单次任务上下文”的膨胀问题。如果某个任务本身太大即使有规划文件AI 在单个会话中依然可能因为要处理的代码太多而丢失细节。这时需要进一步拆分任务或者把大文件拆成多个小文件让 AI 在单次会话中只聚焦一块内容。这也解释了为什么 wayfinder skill 要求任务粒度适中。任务太长单会话做不完任务太短管理成本又过高。找到一个合适的粒度是使用这个技能最重要的调优工作。7. 最佳实践与工程建议7.1 把 goal.md 当作文档锚点项目进行到一半时最常见的问题是“AI 已经不知道当初为什么要做这个项目”。目标文件就是为了解决这个问题。建议goal.md的内容包含几个要素一句话目标明确的技术栈可交付的成果明确不做什么这是很多人忽略的。例如# 项目目标 为一款待办事项 Web 应用编写完整的后端 API包含用户注册、登录、任务增删改查并输出 API 文档。 技术栈Node.js Express SQLite 交付物可运行的 API 项目 README 文档 基础测试 不包含前端页面开发、第三方登录、部署上线“不包含”这部分很重要。AI 经常会自主发挥做一些超出需求范围的事情。“不包含”是一个边界能有效防止范围蔓延。7.2 进度文件保持简单progress.md不需要写长篇大论。它的核心价值就在于一眼看清“现在到哪了”。建议保持以下几个区域不变当前状态任务状态阻塞与风险下一步。其中“阻塞与风险”这个区域要主动维护。AI 在执行任务时如果遇到无法解决的问题应该让它记录在这里而不是自己硬猜一个方案。这样你下次打开项目时能第一时间看到卡点在哪里。7.3 决策日志是团队协作的粘合剂如果你是单人使用 wayfinder决策日志的价值可能不如团队场景明显。但如果你和同事共享同一个项目仓库决策日志就变得非常重要。比如为什么这个任务用 JWT 而不是 session为什么优先做认证而不是任务模块这些决定如果不记录新加入的同事就得重新问一遍甚至可能推翻之前的方案。建议决策日志使用简单的表格| 日期 | 决策 | 原因 | | --- | --- | --- | | 2025-06-01 | 使用 JWT 做认证 | 前端是纯静态页面无 session 服务端 | | 2025-06-02 | 先实现认证模块 | 任务接口都依赖用户身份 |7.4 注意安全边界使用 wayfinder skill 规划项目时AI 可能会在执行中提出一些高风险操作比如批量删除数据、修改生产配置、执行数据库迁移等。在项目规划阶段就要明确需要你确认后AI 才能执行高风险动作。你可以在SKILL.md中增加一条规则- 涉及删除、清空、覆盖大量数据的操作必须先向用户确认并获得明确授权。 - 涉及生产环境的操作默认禁止执行除非用户明确给出足够的说明。这既是保护项目也是培养 AI 使用的好习惯。特别是在团队项目里未授权的破坏性操作可能带来连锁影响。7.5 不要过度依赖 skill最后一条建议可能听起来有点反直觉不要把一切任务都交给 wayfinder。如果任务只需要一次对话就能完成完全可以不用 skill。使用规划反而增加了额外的文件写入和读取成本是一种“杀鸡用牛刀”。更好的做法是在SKILL.md的description中写清楚触发条件让 AI 判断什么场景需要、什么场景不需要。比如description: 用于跨会话规划和管理任意规模的工作。当任务涉及多个步骤、可能持续多个会话或需要长期跟踪时使用。这样 AI 会在合适的场景自动选择使用 wayfinder而不是每次对话都机械地加载它。8. 总结与学习路线wayfinder skill 的本质是把“目标—计划—进度—决策”这套项目管理的基本功用文件的形式固化下来让 AI 在跨会话、跨任务时依然保持清晰的路线感。它不依赖某个神秘的模型能力也不需要复杂的代码核心就是四个 Markdown 文件加一份行为约束。如果你从零开始实践建议按这条路线推进第一步先手动创建一个项目把goal.md、plan.md、progress.md、decisions.md四个文件建好不急着写SKILL.md。自己手动维护几次体会一下“状态外置”的感觉。第二步再把SKILL.md加进去让 AI 自动维护这些文件。注意观察 AI 是否会主动更新进度如果不会就在SKILL.md中加强约束。第三步用真实的中型项目去验证。至少找一个需要多个会话才能完成的任务坚持用 wayfinder 跑完感受和之前“每次新会话都重新讲解背景”的差异。第四步根据你的使用习惯调整模板。你可以增加风险登记表、工时估算、验收标准等字段把 wayfinder 慢慢变成你自己的项目管理助手。跨会话工作流是一个值得长期实践的方向。下一次当你面对一个复杂任务与其在同一个会话里反复拉扯不如先建一个 wayfinder 状态目录把目标写进去然后一点一点推进。希望这套思路能帮你把 AI 从“单次对话的工具”升级成“长期协作的搭档”。