Claude Code + Obsidian：用本地 Markdown 搭任务看板与架构监控
把 Obsidian 仓库当作 Claude Code 的外部记忆，让任务看板、架构文档和变更日志都保存为本地 Markdown 文件，从而支撑多会话并行开发。本文整理这套组合的落地步骤、多会话协作的几种形态、防止上下文漂移的探针做法，以及并发写入和移动端使用中的常见问题。
把 Claude Code 当成一个能读写本地文件的执行者，把 Obsidian 仓库当成它和人类共用的工作台——这是这类玩法能跑起来的核心。任务、架构说明、变更记录全部以 Markdown 形式落在磁盘上，既不锁死在某个 SaaS 里，也能被人直接阅读和修改。
讨论中的实践者用这套方式搭出了两个东西：一个是带看板和列表视图的任务管理系统，另一个是会自动更新的架构文档，并配了一套「探针」来检查文档与代码是否已经对不上。真正让效率提升的并不是这两个系统本身，而是它们解决了一个老问题：新开的会话不知道之前发生了什么，于是乱改。
核心思路：状态落盘，而不是留在上下文里
单次会话的上下文再长也是临时的，关掉就没了；多开会话时，彼此更是完全看不见对方。所以可行的做法是把「当前项目长什么样」「哪些任务在进行中」写成文件，并约定每个会话开始时先读、结束时写回。
一个最小可用的目录约定大致如下：
vault/
├── CLAUDE.md # 给 AI 的硬性规则
├── ARCHITECTURE.md # 模块、目录职责、依赖方向
├── CHANGELOG.md # 会话级变更日志
├── tasks/
│ ├── board.md # 看板视图入口
│ └── T-0001.md # 单个任务，带 frontmatter
└── probes/
└── drift.md # 防漂移检查清单
CLAUDE.md 里只写必须遵守的规则，例如：新建任务必须带 status、owner、updated 三个字段；状态只能在 todo → doing → review → done 之间流转；改完代码必须往 CHANGELOG.md 追加一行。规则写得越长越容易被忽略，控制在十几条以内比较现实。
任务系统：看板 + 列表怎么搭
插件层面，被验证有效的组合是 Kanban（提供看板视图）+ Tasks（任务查询、截止日期）+ Dataview（自定义表格与汇总）。Kanban 负责「看着舒服」，Dataview 负责「查得清楚」，两者互补。
任务文件用 frontmatter 承载结构化字段，正文写描述和验收标准：
---
id: T-0001
status: doing
owner: claude
updated: 2025-01-01
---
## 目标
把会话日志接入架构变更检测。
## 验收
- 每次会话结束有记录
- 新文件出现在 ARCHITECTURE.md 中
需要跨任务的视图时，用 Dataview 查：
TABLE status, owner, updated
FROM "tasks"
WHERE status != "done"
SORT updated DESC
需要注意的是，Kanban 类插件在依赖关系、工时统计、多级子任务上普遍偏弱。如果你的任务已经复杂到需要这些能力，说明它更接近真正的项目管理工具，继续在 Markdown 里硬撑反而费劲。可以先接受「看板只做粗粒度状态管理，细节靠文档」这个取舍。
架构监控与「防漂移探针」
架构漂移的典型表现是：代码里多了一个模块，文档里没有；依赖方向反了，没人发现；上一个会话做的改动，下一个会话完全不知道。解决办法不复杂，靠三件事：
- 维护一份
ARCHITECTURE.md，写清每个目录的职责、模块之间的依赖方向、不能打破的边界。 - 会话级变更日志。每次会话结束，让 Claude 往
CHANGELOG.md追加一条：改了哪些文件、为什么改、有没有动架构。这条记录比代码 diff 更容易被下一个会话读懂。 - 探针清单。
probes/drift.md里列一组可逐条核对的问题，会话开始时让 Claude 先自检一遍。
探针不需要写脚本，一份清单就能起作用，例如：
- 新增的顶层目录是否已在 ARCHITECTURE.md 中出现
- 是否存在跨层直接调用（如 UI 层直接读数据库）
- 本次改动是否触碰了 CLAUDE.md 中禁止修改的路径
- CHANGELOG.md 是否包含本次会话的记录
如果希望更自动一些，可以让 Claude 自己设计实现方案，提示词可以是这样：
多会话并行开发时，新会话不了解已有架构，经常改坏东西。请设计一套机制：会话开始时自动读取架构说明，会话结束时自动检查并更新架构变动，并给出需要我人工确认的部分。
让 AI 出方案是省事的，但方案本身要人审一遍再落地，尤其涉及自动改写文档时，最好保留 diff 或 git 提交，方便回滚。
多会话并行的三种形态
| 形态 | 具体做法 | 适合场景 | 代价 |
|---|---|---|---|
| 会话内派生子 agent | 主会话把子任务分出去，自己汇总 | 任务边界清晰、可并行探索 | 子任务结果质量不稳定，需复核 |
| 交接提示词 | 主会话产出一段上下文摘要，人复制到新会话 | 想让每一步都可控 | 需要人工搬运，节奏偏慢 |
| 外部会话管理器 | 用终端管理工具同时开多个会话 | 长任务、多个仓库并行 | 对本地机器和稳定性有要求 |
无论哪种形态，共同前提都是同一套：每个会话开工前读架构文档和任务文件，收工后写回变更。另外尽量避免两个会话同时改同一个文件，可以用目录分区（一个会话只管一个目录）或者 git 分支、worktree 做隔离。
如果本地机器同时开好几个 Claude Code 实例会卡，或者需要让它长时间挂着跑任务，把运行环境放到一台长期在线的远端 Mac 上也是可选做法，例如新加坡机房的独享 Mac mini，通过远程连接使用，网络环境相对稳定，本地只负责看结果。
容易踩的坑
- 工具升级不等于效率提升。搭系统本身很爽，但真正的收益要看一两周后的实际产出。建议先记录一下改造前后的完成量，再决定要不要继续加功能。
- 规则膨胀。
CLAUDE.md从十条涨到一百条时，约束力会明显下降，定期删减比不断追加更有效。 - 并发写冲突。多个会话写同一个 Markdown 文件，轻则内容被覆盖，重则互相污染上下文。用 git 管理 vault，或至少养成提交前先看的习惯。
- 敏感信息。仓库里别放密钥、内网地址、客户数据，AI 读取的范围往往比你预期的大。
- 移动端代码块换行。iOS 上 Obsidian 的代码块默认自动换行，想改成横向滚动需要自定义 CSS 片段。桌面端在「设置 → 外观 → CSS 片段」里打开片段文件夹，放入
.css文件后回到该页面启用即可；较新版本的移动端也提供了 CSS 片段入口，但能否直接打开文件夹取决于版本与系统，找不到时可以把文件放进 vault 的.obsidian/snippets目录再刷新列表。具体行为以官方文档和当前版本为准。
一个务实的起步清单
- 建一个独立 vault，先只放文档和任务，不急着接代码仓库。
- 写
CLAUDE.md，列十到十五条规定动作，重点是「开始前读什么、结束后写什么」。 - 装 Kanban、Tasks、Dataview 三个插件，定义任务 frontmatter 字段。
- 写一份
ARCHITECTURE.md，哪怕一开始只有半页。 - 写
probes/drift.md检查清单，先手动机跑通。 - 用 git 管理整个 vault，每次会话结束提交一次。
- 跑一到两周后复盘：哪些规则真的被遵守了，哪些视图真的被打开过，删掉没用的部分。
小结
这套组合的价值不在于「用 AI 写文档」，而在于把人和 AI 之间的约定变成可读、可版本控制、可被下一次会话继承的文件。看板和架构文档只是载体，真正的关键动作只有两个：开工前读，收工后写。先把这两步坚持下来，再考虑加探针、加自动化、加并行会话，收益会稳得多。
