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-wise
VibeWise 是一个 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），仅供参考
