如何用 Claude Code 接管你的 Obsidian 知识库

作为一名开发者，你大概率也有这样的困扰：代码写得很嗨，文档却烂成一坨。
虽然现在有了 AI 编码助手（比如 Claude Code），你可以让它帮你“顺手补个文档”。但如果你是一名重度 Obsidian 用户，你会发现直接让 AI 写文档简直是个灾难：

AI 喜欢用原生的 Bash、Grep 或者 Read 工具去扫你的硬盘，效率极低且缺乏上下文。
AI 写出来的 Markdown 就是纯文本，它不懂什么是 Obsidian 的“双向链接（[[ ]]）”、不懂“Callouts 语法（> [!info]）”，更不懂帮你维护 YAML 属性。
它偶尔还会用正则去暴力替换你的文件内容，一不小心就把格式搞炸了。

今天，我花时间打通了一个堪称完美的 “代码开发 + 知识库维护双工作流”，借助官方社区的 obsidian-skills 和极其严苛的提示词工程，彻底让 Claude Code 变成了我的 Obsidian 专属架构师。

以下是我的实战经验分享。

核心解法：引入 Obsidian Skills 与 CLI 代理

要让 AI 懂 Obsidian，我们需要给它装上“专用手臂”。
我引入了 kepano/obsidian-skills 这个开源项目。它包含了一组教 AI 如何与 Obsidian 生态交互的指令。

但在实际落地中，我发现仅仅给 AI 加技能是不够的。最大的坑在于：AI 太依赖自己的“原生工具”了。
当你对它说“帮我查一下知识库里提到了 XxxQueryFacade 的文档”，它第一反应是去用 Grep 或者 SearchCodebase 扫盘，这导致它完全丧失了 Obsidian “标签检索”、“反向链接”的高级能力。

为了解决这个问题，我摸索出了以下关键配置。

关键实践 1：建立清晰的目录存放规范 (docs 目录守则)

让 AI 帮忙写文档的前提是，人类必须先建立良好的归置习惯。如果把所有资料都丢在同一个文件夹里，AI 整理起来也会缺乏维度。

我们在项目中约定了严格的 /docs/ 目录规范，并将其写入了 CLAUDE.md 强制 AI 遵守，这也同样要求开发团队在日常工作中养成好习惯：

/docs/
├── raw/                 # 📦 原始资料输入区 (Read Only)
│   ├── 01-prd/          # 产品需求文档 (PRD) / 业务流程说明
│   ├── 02-architecture/ # 架构设计草案 / 技术方案评审文档
│   ├── 03-api_docs/     # 接口定义文件 (如 Swagger 导出的 Markdown/JSON)
│   ├── 04-database/     # 数据库字典 / 原始 SQL 建表脚本
│   ├── 05-domain/       # 业务领域模型 / 属性字典映射表
│   └── 09-archive/      # 已处理/过期的文件归档，禁止 AI 读取
├── wiki/                # 🧠 正式知识库输出区 (Write/Read)
│   ├── sources/         # AI 整理后的结构化知识点
│   ├── index.md         # 知识库入口导览
│   └── log.md           # 自动追加的更新日志
├── lib/                 # 📚 公共依赖层 (Submodule / Read Only)
└── assets/              # 🖼️ 静态资源区
    └── architecture.canvas # 图片、白板架构图等

📁 /docs/raw/ (原始资料输入区 - Read Only)
这里是我们日常开发的“草稿箱”和“集装箱”。无论是产品丢过来的 PRD、架构评审的草案、Swagger 导出的 API 列表，还是数据库的建表 SQL，先按 01~05 的分类丢进对应的子目录，不需要排版，不要直接在这里写业务逻辑。
📁 /docs/wiki/ (正式知识库输出区 - Write/Read)
这是真正的 Obsidian 知识库。所有这里的文档，都必须是由 Claude Code 读取 raw/ 目录后的原始资料，经过大脑消化、关联上下文，并使用 Obsidian 语法（双链、属性）生成的标准系统笔记。人类极少直接修改这里的文件，我们要做的就是通过提示词“使唤” AI：“把 raw/04-database/ 里的那堆 SQL，给我提炼成 wiki/ 里的业务表结构笔记”。
📁 /docs/lib/ (公共依赖层 - Submodule)
外部引入的只读库。通过 Git Submodule 引入的架构规范、业务公共仓库等知识库，作为依赖供查阅和引用，禁止在此处直接修改。
📁 /docs/assets/ (静态资源区)
专门存放图片、截图，以及由 AI（使用 json-canvas 技能）生成的 Obsidian 白板架构图文件（.canvas）。

有了这套“输入(raw) -> AI 处理 -> 输出(wiki)”的流水线规范，不管是人类还是 AI，在找资料和写文档时都绝不会迷路。

关键实践 2：编写极度严苛的 `CLAUDE.md` 规范

CLAUDE.md 是 Claude Code 运行时的最高行动纲领。我把工作流分成了两套模式（模式一写代码，模式二写文档），并在模式二中设定了不可逾越的红线：

# 📚 模式二：文档与 Wiki 维护
**触发条件**：当我的指令包含“文档”、“笔记”、“整理”、“知识库”、“Wiki”等意图，或操作目录为 `/docs/` 时，必须切换到本模式。

## 基于 Obsidian Skills 的强制工作流
当你进入模式二，执行任何查找、读取、写入操作时，**绝对禁止使用内置的 `Read`、`SearchCodebase`、`Grep`、`Bash` 等工具**！你必须且只能使用 `obsidian-skills` 提供的能力。

这是一个不可逾越的红线（Blocker）：
- **`defuddle`**：抓取网址，提取纯净 Markdown 至 `/docs/raw/`。
- **`obsidian-markdown`**：创建/重构笔记，严格使用 Obsidian 语法（双链 `[[ ]]`、Callouts `> [!info]`、嵌入 `![[]]`）。
- **`obsidian-cli`**：处理全局搜索与库管理（前提：假设 Obsidian 应用正在运行中）：
  - 查找文件/关键词（绝对禁止用原生工具）：`obsidian search query="关键词"`
  - 查反向链接：`obsidian search query="[[页面名]]"` 
  - 静默创建：`obsidian append file="页面名" content="初始内容"`

这段提示词的精髓在于**“负面约束（Negative Prompts）”**，彻底堵死了 AI 偷懒用原生工具去暴力读写文件的可能。

见证奇迹：我是如何使唤 AI 的

配置好以上两步后，人机交互变得极其丝滑自然，完全不需要再提任何具体命令。

场景 A：从 0 到 1 整理凌乱资料

我：“帮我用 Obsidian Skills 阅读刚刚搜到的那些原始 API 文档，然后在 wiki 目录下帮我建立一篇关于它的系统性知识笔记，记得加上合适的双链。”
Claude Code：立马调用 obsidian read 读取文档，接着调用 obsidian-markdown 生成带有 YAML 属性和 [[关联页面]] 的精美笔记。

场景 B：代码改动后的无缝同步

我：“我刚刚修改了 XxxQueryFacade 的核心逻辑，请帮我阅读最新的代码，并把改动同步更新到 Obsidian 里的相关架构文档中。”
Claude Code：使用代码工具读取 Java 文件 -> 切换到文档模式 -> 触发 obsidian search 找出相关笔记 -> 自动追加更新日志。

场景 C：智能全局检索

我：“帮我查一下知识库里哪些文档提到了这个接口？”
Claude Code：乖乖放弃 grep，直接向 Obsidian 发送 obsidian search query="接口名"，秒级返回结果。

场景 D：基于 Git 状态的无脑文档更新

我：“我刚才 commit 了一波代码重构，请检查一下我最近修改了哪些文件，评估一下我们的 Obsidian 知识库里有哪些文档需要同步更新？如果有，请直接帮我更新它们。”
Claude Code：读取 Git diff -> 发现修改了某个类 -> 切换到文档模式 -> 用 obsidian search 查出引用了该类的笔记 -> 直接重写该笔记的相关章节，并更新最后修改时间。

总结

AI 不缺智商，缺的是清晰的边界和顺手的工具。

通过组合 obsidian-skills、 obsidian CLI，以及一份极其严格的 CLAUDE.md 约束规范，我们成功地把 Claude Code 从一个只会用 Bash 蛮干的“糙汉子”，调教成了一个懂得遵循 Obsidian 语法的“精致架构师”。

以后，只管痛快写代码，文档维护的事，就交给它去跑吧！