Vault 结构和调试

将 Markdown 库组织为可搜索的第二记忆。当 Claude 做了意想不到的事情时，对四种故障模式进行分类。

STATE.md 和 MEMORY.md 包含了每个会话所需的内容。一个 Markdown 库（Obsidian 或任何文件夹）则包含了所有其他内容：策略笔记、会议记录、项目日志、研究、竞品分析。

这个库逐渐成为机构记忆：你六个月前做出的决策及其原因，为当前工作提供信息的参考资料，以及跨项目的模式。通过 Obsidian 或文件系统 MCP 连接它，Claude 可以按需搜索整个库。没有这个库，这些知识只存在于你的脑海中或埋藏在旧文档中。

为什么 Markdown 优于数据库： 纯文本文件可 grep、可使用 git 版本控制、可在任何编辑器中打开，并且能在所有工具变更中幸存。一个可行的结构：

~/notes/

├── STATE.md # 始终加载

├── MEMORY.md # 索引，始终加载

├── STRATEGY-DIGEST.md # 策略文档摘要

├── strategy/ # 完整文档，按需读取

├── projects/ # 带日期的项目笔记

├── resources/

└── reference/扩展的关键是摘要模式：当你编写一个 1,000 字的策略文档时，同时编写一个 3 句话的摘要，并将摘要索引到 MEMORY.md 中。Claude 在会话开始时读取大约 50 个 token，而不是完整文档的大约 1,500 个 token。对于 25 个策略文档，这是 1,250 个 token 对比 37,500 个 token，会话保持快速。

当 Claude 做了意想不到的事情时，按顺序检查四种故障模式，从最常见到最不常见：

陈旧记忆： STATE.md 说一件事，现实说另一件事。Claude 完美地遵循了你的指令；指令是错误的。每次都先问“给我看看你的 STATE.md”。

缺少上下文： 相关文件从未加载，所以 Claude 做出了合理的猜测。明确加载文件并重新提问。

工具不可用： MCP 关闭或钩子阻止了命令，Claude 糟糕地绕过了它。在指责推理之前，检查工具可用性。

幻觉： 最罕见的原因。首先验证：grep 函数，检查端点是否存在。大多数“幻觉”最终都是前三种情况之一。

每种故障模式一个诊断问题：

陈旧记忆：“你的 STATE.md 对 [主题] 说了什么？” 三个会话前的内容意味着状态陈旧。

缺少上下文：“你加载了哪些关于 [主题] 的文件？” 没有相关文件意味着加载正确的文件。

工具不可用：“你现在有哪些可用工具？”

幻觉：“grep [函数/端点] 并告诉我你找到了什么。”

这个序列需要两分钟，几乎每次都能找到原因。直接跳到“Claude 产生了幻觉”通常会通过重写不需要重写的代码来延迟真正的修复。

预防胜于调试。 习惯：

会话结束时更新 STATE.md。 消除 80% 的陈旧记忆问题。

将已发布项目存档到带日期的 project_* 文件中。

每月 MEMORY.md 审计： 确认每个指针仍然指向现有文件。

摘要所有超过 500 字的文档。

在做出决策时立即记录决策， 而不是在周末。事后捕获会丢失推理。

在存档项目笔记之前， 将持久化经验提取到 feedback_* 条目中。项目成为历史；经验保持活跃。

一个包含 10 个维护良好的文档的库胜过一个包含 200 个陈旧文档的库。质量和时效性胜过数量。

通过 Obsidian 或文件系统 MCP，库成为一个实时知识库：

决策考古： “搜索库，了解我们为什么选择 Postgres 而不是 MySQL。”手动搜索 10 分钟变成 15 秒。

模式检测： “查找跨项目所有提及速率限制问题或 429 错误的地方。”Claude 发现了一个跨五个项目文件传播的常见根本原因。

参考查找： “在供应商笔记中查找联系信息。”从未索引的文件中即时检索。

搜索质量取决于命名一致性：project_[name]_[date].md 和 feedback_[rule].md 优于当时觉得自然的任何命名。命名约定是你需要之前构建的索引。

所有四种模式都检查干净，但输出仍然错误？ 两种看起来像幻觉但不是的原因。

上下文排序： 当加载的文件冲突时，后加载的内容往往会胜出。如果旧的项目笔记与 STATE.md 冲突，明确指定权限：“STATE.md 是当前的真实情况。它取代项目笔记中的任何内容。”

约束冲突： CLAUDE.md 说“参数化所有 SQL”，所以 Claude 在你本意只是风格重构时重写了 SQL。这不是 bug；明确范围：“仅限风格，不要更改 SQL 模式。”

两者的诊断方法：“你遵循了哪些指令来管理 [这个决策]？按优先级顺序列出规则。”你会发现一个陈旧的来源、一个冲突的规则或一个 CLAUDE.md 漏洞。所有这些都可以修复。

一个带有摘要文件的 Markdown 库可以扩展你的第二记忆；摘要保持会话快速，完整文档按需加载。当 Claude 行为异常时，按顺序分类：陈旧记忆、缺少上下文、工具不可用、幻觉，并且始终从“给我看看你的 STATE.md”开始。在做出决策时立即填充库，它每周都会增值。