使用 Obsidian 作为 AI 时代的 IDE：Karpathy「Wiki as Codebase」的落地实践——Claudian、CLAUDE.md 与 Vault Lint
引子
AI 时代，代码编辑器（idea）没变，变的是「围绕代码的所有上下文」需要一个新的承载层。本文把 Andrej Karpathy 提出的「Obsidian is the IDE, LLM is the programmer, wiki is the codebase」思路落地：用 Obsidian + Claudian 插件 + vault 根 CLAUDE.md schema，把设计决策、AI 对话历史、DB schema、跨服务上下文沉淀成可 Lint 的知识网络，让 LLM 从「一次性问答机」升级为纪律性的 wiki 维护者。文末给出一次两周跨度、15 个决策、13 个 commit 的重构实战，以及两条可以直接扔给 Claudian 的 Vault Lint prompt。
一、AI 时代 idea 已经不够用了：从 IDE 到「认知承载层」
使用 idea + AI 插件遇到几个问题:
- 用问答的形式,问一句,写一段代码片段,人工 review 结果
- 和 AI 沟通过的记录,不好搜索
- 多次沟通以后上下文累加,AI 注意力不集中;重开 session 以后记忆清零,从头教他写代码
- 一个需求涉及多个微服务,代码需求不止在一个 codebase 里完成
- 在 idea 的视角里只有代码,没有数据库结构、中间件相关信息
idea 已经不能满足 AI 时代的代码迭代了。
二、Obsidian 是什么：本地优先的 Markdown 知识管理工具
Obsidian 官网：obsidian.md
Obsidian 是一个本地优先(local-first)、基于纯 Markdown 文件的知识管理工具。核心特点:
- 数据在本地:所有笔记就是磁盘上的
.md文件,不锁定在某家云服务,离线可用,自己完全掌控 - 双向链接(Wiki-links):
[[note-name]]把碎片连成网,任何一篇笔记都能被反向查询「谁引用了我」 - 图谱视图:笔记之间的引用关系可视化,一眼看出知识网络的形态
- 插件生态:开放的插件市场,社区已经把它扩展成了任务管理、日历、Dataview 查询、AI 助手等各种形态
- 纯文本 = AI 友好:文件都是 UTF-8 Markdown,对 AI 来说是可读、可写、可 diff 的一等公民,不用像 idea 那种 IDE 需要专门的插件桥接
回到上文列的 idea + AI 痛点,Obsidian 恰好每一条都对症:
| idea + AI 的问题 | Obsidian 的解 |
|---|---|
| 问答式碎片、结果难 review | 笔记是持久文档,AI 在这里改的每一笔都留痕、可回溯 |
| 沟通记录不好搜索 | 全文搜索 + 双向链接 + 标签,历史对话是可检索的知识资产 |
| 上下文累加,重开 session 记忆归零 | 用笔记显式落项目上下文,新 session 让 AI 先读笔记恢复记忆 |
| 一个需求涉及多个微服务 | 一个 vault 可以同时装 A、B、C 服务的笔记,链接跨服务打通 |
| idea 只有代码,没有数据库/中间件视角 | vault 里可以并列放代码分析、DB schema、Kafka topic、部署拓扑 |
换句话说,Obsidian 不是取代 idea 的编辑器,而是取代它的认知承载层——代码继续在 idea 里写,但围绕代码的所有上下文(设计决策、AI 对话历史、数据库结构、跨服务调用图)搬到 Obsidian 里长期沉淀。
三、环境准备：Obsidian + Claudian 插件
- 下载 Obsidian 并开启插件
- 安装 Claudian 插件（GitHub），让 Claude Code 直接读写 vault
四、理论基础：Karpathy 的「Wiki as Codebase」三层架构
理论出处：Andrej Karpathy 的这篇 gist 一句话破题(下方为原文直译):
“Obsidian is the IDE; the LLM is the programmer; the wiki is the codebase.”
—— Obsidian 是 IDE,LLM 是程序员,wiki 是 codebase。
也就是说,你写的每份笔记都不是”文档”,而是 LLM 正在维护的一份代码库——只不过存的是关于世界的结构化知识,不是可执行指令。
4.1 三层架构
Karpathy 把整个系统分成三层,恰好对应 vault 里三类文件:
| 层 | 定义 | 对应 |
|---|---|---|
| Raw sources | 不可变原始资料,LLM 只读不改 | 粘贴进来的会议纪要、PDF、代码 diff、剪藏文章 |
| The wiki | LLM 生成/维护的 markdown 页 | 你的分析笔记、决策记录、概念页 |
| The schema | 让 LLM 变成”有纪律的维护者”的配置 | vault 根 CLAUDE.md |
关键点:CLAUDE.md 不只是”避免重复告诉 AI 项目背景”的便利工具,它是 schema——它决定了 LLM 是随手回答的聊天机器人,还是纪律性的 wiki 维护者。
4.2 三个操作
LLM 在这份 wiki 上做三件事:
- Ingest —— 摄入新原始资料,更新多份 wiki 页,维护交叉引用
- Query —— 搜 wiki 综合答案,好答案回写成新页面
- Lint —— 检查矛盾、过时声明、孤儿页面、缺失链接
前两个大多数人已经在做,Lint 是新能力——给知识库跑健康检查,和给代码跑 lint 一个道理。
4.3 为什么现在才可行
人类曾经普遍放弃维护内部 wiki,因为维护成本超过收益——没人有精力持续更新交叉引用、消除矛盾、补链接。
LLM 恰好补上这个瓶颈:“人筛选原始资料、指定分析方向、问好问题”,LLM 承担所有的记账工作——一次 ingest 触碰几十份文件,成本几乎为零。
不是 Obsidian 变强了,是wiki 的维护成本从人身上转移到了 LLM 身上。
五、怎么用：一个 vault + CLAUDE.md + 四个日常动作
5.1 一个项目一个 vault + CLAUDE.md
不用一个 vault 装所有东西。每个项目建一个子文件夹,vault 根放 CLAUDE.md——技术栈、目录结构、commit 规范、常见 gotcha、每次开新对话都要重复告诉 AI 的东西,一次写清楚。Claudian 每次启动自动读它,session 重开不再从零。
5.2 需求进来的典型流程
对比过去(打开 AI 侧边栏 → 问一句 → 复制代码 → 关闭 → 记忆归零),现在的路径:
- 建需求笔记 —— 背景、目标、约束
- 让 AI 读上下文 —— 用
[[]]引架构、DB schema、历史需求笔记,Claudian 自动读 - 对话式分析 —— 出方案,追问,拍板,关键决策让 AI 写回笔记
- 回 idea 写代码 —— 笔记里的方案作为提示
- 回写决策 —— 代码写完把”为什么这么改 / 踩了什么坑 / commit hash”记回笔记
- 下一个需求 —— 老笔记 = 新对话的上下文
心态转变:AI 的输出不是「用完即弃的问答」,而是沉淀成文档。
5.3 日常高频动作
@引用文件 —— 直接把某笔记塞进对话上下文,跨服务对齐特别好用- 粘代码进笔记让 AI 改 —— 结果留在笔记里,可回看
- 决策记录(ADR) —— 每个架构决策一个笔记,
[[]]串起来,半年后不用猜”当时为什么这么设计” - daily note 记排查过程 —— 实时思路直接进当天日记,AI 基于流水推进
- 图谱视图 —— 一眼看哪些模块笔记密集(核心区),哪些孤立(遗漏区)
5.4 和 idea 的分工
| 场景 | idea | Obsidian + Claudian |
|---|---|---|
| 写代码、debug、跑测试 | ✅ | |
| 断点调试、profiler | ✅ | |
| 需求分析、方案设计 | ✅ | |
| 架构文档、DB schema | ✅ | |
| 和 AI 长对话、决策落地 | ✅ | |
| 跨服务上下文串联 | ✅ | |
| 团队共享知识、复盘 | ✅ |
一句话:idea 负责「码」,Obsidian 负责「脑」。
六、实战案例：一次两周、15 个决策、13 个 commit 的重构复盘
在本地做了一个项目 P1~P6 六个阶段主体 + 4 轮架构 refactor,涉及 15 个技术决策(D1-D15),持续两周。
如果只在 idea 里做,几乎不可能完成——每次开新 session 记忆归零,反复解释项目背景就要废掉一半时间。Obsidian 在这里做了 5 件事:
- 一份主计划笔记贯穿始终 —— 所有对话从它出发,笔记本身也被 AI 补写、修订
- 15 个决策全部落笔 —— 每个都记「背景 / 备选 / 选择 / 理由」,不留在对话里
- 跨 session 无缝续接 —— 第七天开新 session,一句”读一下这份笔记继续”就够了
- commit hash 回写笔记 —— 13 个 commit 全部登记,笔记直接变 changelog
- 最终沉淀到 CLAUDE.md —— 下一轮改造进来,新 session 直接知道现状
反过来,如果只在 idea 里做?15 个决策散落在几十次对话里搜不到、复现不了;每次新 session 浪费 20 分钟重建上下文;commit 之间的”设计意图”3 个月后自己都看不懂。
结论:改造规模越大、跨度越长,Obsidian + Claudian 的 leverage 越明显。这不是可有可无的辅助,是让”AI 参与长周期复杂改造”变得可行的基础设施。
七、实操：给 Obsidian vault 跑一次 Lint（死链 + 孤儿扫描）
理论讲完,回到最实用的一个动作:定期让 AI 给你自己的 vault 跑健康检查。这是把 wiki 当代码库来 code review。
推荐两类基础 Lint,一句 prompt 就能跑通。你在自己 vault 上跑一遍才有意义,这里给的是模板 + 结论解读。
7.1 死链扫描：找出「你以为写过但没写」的核心笔记
Prompt(直接扔给 Claudian):
扫全 vault,找所有形如
[[xxx]]但目标文件不存在的 wikilink,按引用次数排序,输出 top 30。忽略图片 embed、代码块内、Templater 变量。
跑完的报告,基本可分成 6 类:
| 类别 | 典型 | 处理 |
|---|---|---|
| A. Daily 前后日跳转 | [[2026-05-14_周四]] |
模板机制常态,可忽略;或让 Templater 只在文件存在时渲染 |
| B. 模板占位符误识别 | [[<% after_date %>]] |
假死链,忽略 |
| C. 剪藏工具事故 | 网页里带 [[]] 的评论者昵称、URL 被误转成 wikilink |
批量搜索替换清理 |
| D. 想链但没写 | 某个概念被反复引用却始终没建笔记 | 明确该行动——被引用次数越多,越该优先补写 |
| E. 拼写 / 格式错误 | 结尾多反斜杠、大小写不匹配 | 修 bug 一样直接改 |
| F. MOC 目录缺失 | 目录名被链但没同名索引页 | 建索引页 |
Lint 的价值在 D 类——高频死链等于你自己反复觉得”这里该有一篇笔记”,但一直没写。这是知识网络给你的具体行动清单。不跑这一遍,你根本不知道自己欠了多少债。
7.2 孤儿扫描：找出「知识组织结构上的洞」
Prompt:
找出没有任何其他笔记通过 wikilink 引用它的孤儿笔记。排除 daily notes、入口文件、CLAUDE.md、空笔记。按文件大小排序,大文件优先。
跑完你通常会看到三种模式:
- 成规模的孤儿集群 —— 某个目录(某本书的章节笔记、某个专题的系列文章)整批全是孤儿 → 缺一个 MOC 索引把系列串起来。这不是”补一条链接”的问题,是知识组织结构有洞。这种结构性问题只有跑 Lint 才看得出来,单独打开某一篇笔记时永远发现不了
- 孤儿入口文件 —— 名字像入口(
xx 总览、xx 看板)但没有任何入链 → 做了入口没人走,需要在其他笔记里显式引用它 - 空 / 单行笔记 —— 未命名、只写了标题就没下文 → 直接删
7.3 定期跑 Lint 的收益：把 wiki 当 codebase 来 code review
一遍 Lint 能给你四类具体产出:
- 明确的下一步行动:高频死链 = 该建的核心笔记清单
- 结构性问题的暴露:成群的孤儿集群 = 缺的 MOC 索引
- 数据清洁:剪藏事故、拼写错误、空笔记
- 入口文件的自我审计:名字是入口但没入链 = 走不通的入口
建议节奏:每月一次,或每次大批量扔资料进 vault 之后跑一次。
不做 Lint 的 vault,两三年后基本是个大坟场——链接密度看起来很高,但绝大多数是死链和孤岛。反过来,坚持做 Lint,vault 就永远保持”活的”——每一条链都能到达,每一个节点都被引用。这就是 Karpathy 说的 Lint。
八、小结：idea 负责码，Obsidian + Claudian 负责脑
- idea 是代码的编辑器,它没变,依然好用
- Obsidian 是认知的承载层,补上 idea 缺失的另一半——设计意图、AI 对话历史、跨服务上下文、决策脉络
- Claudian 是粘合剂,让 AI 直接读写你的知识网络,不再是「一次性问答机」
CLAUDE.md是 schema,让 LLM 从聊天机器人升级为纪律性维护者- Lint 操作 是自我维护的核心动作,让 vault 长期不烂
组合起来,你才真正拥有一个「AI 时代的 IDE」——不是把 AI 塞进 idea 侧边栏的拼贴,而是围绕知识组织重新设计的开发工作流。