VibeWise状态文件全解：.vibe-wise目录下三个文件如何记录你的学习轨迹

VibeWise状态文件全解.vibe-wise目录下三个文件如何记录你的学习轨迹【免费下载链接】vibe-wiseA Claude Code plugin that helps you learn how to build while AI writes the code.项目地址: https://gitcode.com/gh_mirrors/vi/vibe-wiseVibeWise 是一个 Claude Code 插件让你在 AI 写代码的同时学会如何设计软件。它的学习轨迹全部保存在项目根目录的.vibe-wise/文件夹中由profile.md、progress.md和project-map.md三个状态文件组成。本文带你完整看懂这三个状态文件它们各自动态记录什么、如何在新会话中自动恢复以及重置前如何备份。为什么你需要这些状态文件VibeWise 的核心理念是「你负责设计AI 负责写代码」You build. AI writes.。在开发过程中Claude 会不断询问你的方案、评估你的推理而不是直接替你做出架构决定。但对话总会中断——重启终端、执行/compact压缩上下文、隔几天再来……如果学习记录只停留在聊天记录里Claude 下次就会「失忆」不知道你的经验水平、忘记了已确认的设计、还会重复问你一遍入门问题。.vibe-wise/状态文件就是解决这个问题的「学习记忆」它只包含三个文件文件一句话定位更新时机profile.md你的学习者档案当前快照偏好或理解水平变化时progress.md学习事件流水账按主题每学到一个新主题时project-map.md项目结构与知识地图设计讨论推进时首次运行/vibe-wise:learn完成引导onboarding后这三个文件就会自动创建在 Git 仓库根目录无 Git 时在当前目录模板定义在 state-templates.md 中。profile.md你的学习者档案快照profile.md记录的是「现在的你」而不是历史过程。它采用更新覆盖策略新信息会修正旧条目而不是无限追加。打开一个真实项目里的profile.md大致长这样状态行文件顶部的两行Learning mode和Onboarding是机器可读的关键标记。恢复钩子 session_start.py 会专门扫描Learning mode: paused来判断学习模式是否处于暂停状态所以这两行要保持在文件顶部且不换格式。Project 区块项目类型新建 / 已有 / 熟悉、在构建什么、你对代码库的熟悉程度、学习范围整个系统 / 只学涉及的部分。Experience 区块整体编程经验Beginner / Intermediate / Advanced和对所用技术栈的熟悉程度。这决定了 Claude 给你的「教学浓度」——初级会多解释概念、多用图和更小的推理问题高级则会直接挑战约束条件和失败模式。Goals 区块你的学习目标比如「从头到尾理解这个项目」。Preferences 区块检查点频率Light / Normal / Frequent、提问风格、代码编写方式默认 AI 写代码。Strong / Developing / Revisit Concepts已掌握、正在发展、需要回顾的概念清单。这是档案的精华——它让 Claude 不再重复讲解你已经掌握的知识点。progress.md按主题记录学习事件如果说profile.md是快照progress.md就是底稿。它按## 主题分节每个主题下记录三类信息Introduced哪些概念已经向你介绍过Demonstrated understanding你展现出理解的证据记录的是你的推理不是对话原文的引用Needs reinforcement还需要强化的点。有两个容易忽略的细节Pending decision 区块当某个检查点Design 或 Implementation正在等你确认时progress.md会留一个简短的「待决事项」小节记下提出的方案和等待的回复类型。解决后删除。这意味着即使你在确认前关闭了 Claude下次启动时待决状态也会被恢复——重启不等于批准。忠实记录原则产品偏好比如「笔记要支持多文件夹」只是需求不算工程理解的证据Claude 提出的建议永远标记为 proposed不会被算成你的决策。project-map.md你与 Claude 共同构建的项目地图project-map.md是三个文件中唯一描述「项目本身」的它由七个板块组成板块内容Purpose这个软件做什么Requirements用户需求与约束注意需求不会自动决定技术选型Components组件、职责和对应的文件路径Main Flow用紧凑文本图描述主流程未知关系标记为?Data and Trust Boundaries存储、所有权、认证、外部服务Build and Deployment在仓库中验证过的构建命令与配置路径Unknowns尚未解决的技术选型以及还缺什么信息关键在于它**区分 proposed提议、chosen已选定和 implemented已实现**三种状态的组件不会用假设的设计去填补未讨论的关系。对已有仓库Claude 会先实际查看入口、依赖和存储配置再画出这张有证据支撑的地图。状态文件如何被自动恢复这是.vibe-wise/最妙的机制你什么都不用做重启 Claude Code 就能续上学习。hooks.json 注册了SessionStart钩子覆盖startup | resume | clear | compact | fork五种事件每次会话启动时session_start.py 会从当前目录向上查找最近的.vibe-wise/兼容旧版.sensible-vibes/并且遇到.git边界就停止绝不借用父仓库或其他 worktree 的状态也不跟随符号链接确认profile.md存在且学习模式未暂停后钩子会向 Claude 注入一段固定的恢复指令读取profile.md和project-map.md搜索整个progress.md中的待决事项并在写代码前恢复对应检查点阶段。由于注入的指令大小固定不会随学习历史增长而膨胀长日志也不会拖慢启动。相关行为在 test_session_start.py 中有完整的钩子测试覆盖设计说明见 development.md。备份与重置学习轨迹可以重来想从零开始学这个项目运行/vibe-wise:reset先做一次只读预览展示将要重置的文件和备份位置不改动任何东西你明确选择Reset learning后reset.py 会把三个原始文件备份到.vibe-wise/backups/下带时间戳的文件夹再用空白模板替换活动笔记源代码、Git 历史和其他项目完全不受影响随后 Claude 重新开始引导。预览和确认之间使用快照指纹校验笔记在等待期间被修改会强制重新预览避免误删新内容。重置命令的完整流程见 reset/SKILL.md。使用建议与常见问答要不要提交到 Git官方建议在.gitignore中忽略.vibe-wise/让笔记留在本地。插件不会悄悄改动你的.gitignore——它会先告知、经你同意后才编辑。为什么找不到状态文件目录位于 Git 仓库根目录且只在完成首次引导后才创建目录不存在属于正常的首次安装状态不是错误。改名前叫.sensible-vibes/旧笔记原地保留、自动识别恢复无需手动迁移同名位置同时存在时.vibe-wise/优先。暂停学习怎么办直接告诉 Claude「pause learning」profile.md会标记为 paused之后运行/vibe-wise:learn即可恢复。数据安全如何没有账号、后端或遥测笔记是纯本地 Markdown随你的 Claude Code 数据设置处理。总结.vibe-wise/下的三个文件各司其职profile.md记住「你是谁、怎么学」progress.md记清「学过什么、证据何在」project-map.md描绘「项目长什么样、还缺什么」。配合 SessionStart 钩子的自动恢复机制VibeWise 的学习轨迹在重启和上下文压缩后都能无缝延续——你专注于思考设计剩下的交给文件。更多交互示例可参考 Notion 风格笔记应用演示整体使用方式见 README.md。【免费下载链接】vibe-wiseA Claude Code plugin that helps you learn how to build while AI writes the code.项目地址: https://gitcode.com/gh_mirrors/vi/vibe-wise创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考