把 Obsidian 笔记整理成 Claude Code 指令书的方法

上周，我在 Obsidian 里留了一篇两千来字的笔记，第二天就直接跟 Claude Code 说：「那个结账页的按钮，帮我修一下。」

结果它回给我的，除了按钮本身，还顺手调了页头的留白、重排了页脚的链接顺序，外加把 CSS 命名规范也「整理」了一遍——三个文件的改动，没一个是我要的。为什么会这样？因为我把整篇笔记原样贴了进去。三天前那句「这里好像也有点怪」的随手吐槽，被它当成和今天的指令一样重要的事来读了。

笔记本身没问题。有问题的是我——我以为笔记是「能直接交出去的东西」。长笔记适合做记录，不适合做工作指令。今天就来补上这个落差，写一写把 Obsidian 笔记变成一篇短指令书的具体步骤。

本文要点

• 把长笔记整篇贴进去，AI 分不清三天前的吐槽和今天的指令，会把没让它做的活儿也一并做了。
• 只交四样东西：「已知的事实」「已经定下的事」「还不清楚的事」「下一步」。再加上「不许碰的地方」和「判断做完的证据」。
• 把完成条件做小。锁定一个文件、一个页面、一条命令，跑完构建、看完截图再往下走。
• 模板 prompt 和把笔记转成指令书的简短代码，复制就能直接用。
• 交给 AI 的是「写、找、改」；人来决定的是「范围、优先级、能不能上线」。这条线一旦混了就出事。

整篇贴进去为什么会跑偏

Claude Code 动手很快。正因为快，你一开始给的信息越宽，它就越会照着这个宽度全力往前冲。

笔记里是有时间差的。「按钮折行」是今天的事实，「话说配色好像也旧了」是一周前的感想，可它们作为同一组项目符号并排躺在那里。人会用日期和上下文去分辨，但被原样贴进去的 AI 看不出哪条是还活着的指令。于是它出于好意，全都动手了。

还有一点。笔记里「已经定下的事」和「还在犹豫的事」是混在一起的。一旦连犹豫的部分都被当成指令读进去，AI 就会擅自替你选一个方向往前走。这才是最吓人的。所以在交出去之前，得由人这一侧先做一次分拣。

只交这四样

分拣的标准很简单，就是往下面这四个框里塞：

1. 事实：实际确认过的东西。「375px 的屏幕上按钮折成两行」「公开 URL 是对的」——这种谁看了都会点头的内容。
2. 决定：已经定了的事。比如「免费派发的 PDF 排在付费教材前面」，这种讨论过、不再变动的方针。
3. 未确认：还不清楚的事。比如「不知道是哪个组件持有按钮的留白」，这是不想让 AI 擅自填上的空。
4. 下一步：这一次只做的那一件事。具体到「定位组件、打上最小的 CSS 改动、在手机宽度下确认」为止。

在这之上再加两样。不许碰的地方（例如认证相关的文件这次不动）和判断做完的证据（例如构建能过、手机宽度的截图）。这六项就是指令书的全部内容。

分拣时最该注意的，是别把「未确认」抹掉。把不清楚的事老老实实留着，AI 会主动就那一点向你提问。反过来，要是把未确认抹掉、写得像事实一样，AI 就会带着错误的前提一路冲下去。

交给 AI 的范围，和人来决定的范围

先把「能交出去的」和「必须自己攥着的」划清楚。这条线一含糊，就算做了指令书，最后还是会飘。

工序	交给 AI	人来决定
范围	-	锁定哪个文件、哪个页面
调查	去找组件和代码	找的对象的优先级
实现	写最小的改动	允许改动的上限
确认	跑构建、跑测试	能不能上线的最终判断

如表所示，「找、写、跑」是 AI 的强项。而「做到哪一步」「能不能公开」由人攥着。把这条线写进指令书，AI 就算想扩大范围，也会自己停下来。

复制就能用的 prompt 模板

先把笔记整段选中，贴在下面这段请求文的后面。这是让 AI 来替你做分拣本身的用法。

请把下面这篇 Obsidian 笔记，整理成给 Claude Code 用的一篇短指令书。
输出只保留以下这几个标题，其余一律丢弃。

- 事实：只写确认过的内容
- 决定：已经不再变动的方针
- 未确认：不要擅自填补，原样保留「不清楚」
- 下一步：把这一次要做的一件事写具体
- 不许碰的地方：这次不动的文件或功能
- 证据：判断做完的确认手段（构建、截图等）

把旧的感想和闲聊另外归到「参考笔记」里，不要混进指令中。

拿到指令书后再读一遍，只确认两件事：未确认有没有被写成了事实，下一步是不是收敛成了一件事。没问题的话，就把它原样贴进 CLAUDE.md 或者 issue 的评论里，让它去实现。CLAUDE.md 怎么写，我在 claude-md-best-practices 里有详细整理。

把笔记转成指令书的验证代码

在动手之前，先放一段小代码，把这个结构「装进身体里」。用 Node.js 就能跑。它做的事，就是把笔记按上面六项分好，再拼成一张交给 Claude Code 的指令书。

// 把笔记分成「事实・决定・未确认・下一步」来保存
const note = {
  title: "结账页的按钮在手机上会折行",
  facts: ["375px 的屏幕上按钮折成两行", "公开 URL 是对的"],
  decision: "免费派发的 PDF 排在付费教材前面",
  unknowns: ["不知道是哪个组件持有按钮的留白"],
  nextAction: "定位组件、打上最小的 CSS 改动、在手机宽度下确认",
  doNotTouch: ["认证相关的文件"],
  proof: ["构建能过", "375px 宽度的截图"],
};

// 把六项拼成一张指令书文本
function toBrief(item) {
  return [
    `目的: ${item.nextAction}`,
    `事实: ${item.facts.join(" / ")}`,
    `决定: ${item.decision}`,
    `未确认(不要擅自填补): ${item.unknowns.join(" / ")}`,
    `不许碰的地方: ${item.doNotTouch.join(" / ")}`,
    `证据: ${item.proof.join(" / ")}`,
  ].join("\n");
}

// 用机器检查分拣有没有漏的「守门员」
function checkBrief(item) {
  const missing = [];
  if (item.facts.length === 0) missing.push("事实");
  if (item.unknowns.length === 0) missing.push("未确认");
  if (!item.nextAction) missing.push("下一步");
  if (missing.length) {
    throw new Error(`分拣不完整: ${missing.join(", ")}`);
  }
  return true;
}

checkBrief(note);
console.log(toBrief(note));

checkBrief 看着不起眼，却是关键。一旦你想在事实为空、未确认为空、下一步为空的情况下交出指令书，它就会在这里把你拦住。把「先随手贴了再说」在代码这一层就禁掉，潦草的笔记直接流向 AI 的事故就少了。把输出结果原样贴进 issue 评论或交接笔记，下一次工作时同一套判断还能复用。交接笔记怎么写，可以参考 claude-code-session-handoff-template。

这些场景下特别管用

1. 让它改一篇文章时

你要是丢一句「把这篇文章改好」，AI 往往会把正文整篇重写。这时在指令书里写清楚「只交检索意图和 CTA 方针」「禁止重写整篇正文」。事实是现有的标题，决定是导流的方针，未确认是写得弱的段落，下一步只改一个小标题——这么分拣下来，改动就小了，要回退也是一瞬间的事。Obsidian 联动本身的设置，我整理在 claude-code-obsidian-integration。

2. 修 bug 时

诀窍是把「能复现的事实」和「还不清楚的原因」分开交。「375px 下按钮折行」是事实，「是哪个组件持有留白」是未确认。要是把这两者混起来写成「原因应该出在 CSS」，AI 就会带着错误的方向开始修。把未确认就当未确认交出去，AI 反而会先去把那一点查清楚。

3. 接到导入咨询时

把客户的业务笔记，别原样给它看，而是分成「这次要碰的范围」「绝对不碰的范围」「下次要确认的事」再交出去。生产数据和计费相关的东西，别在未确认的状态下让它自动去碰。光是把这条线写进指令书，咨询现场就能放心地共享屏幕。

容易踩的坑，以及怎么修

我最初栽的跟头，基本就这三个。

第一个，是把整个 vault 都贴了进去。旧的决定和现在的约束混在一起，AI 不知道该信哪个。修法很简单，贴之前先往上面六项分拣一下，三天前的感想隔离到「参考笔记」里。

第二个，是只交了决定。我只写了「PDF 排在前面」，AI 不明白为什么要这样，换个场景就做了相反的事。把事实和理由成对地留着，才用得灵活。

第三个，是把完成条件做大了。一说「整体整理一下」，AI 就会出于好意把范围铺开。锁定一个文件、一个页面、一条命令，跑完构建、看完截图再往下。光这一条，就能在不降速的前提下减少回退的时间。prompt 怎么收窄，可以一并参考 claude-code-prompt-engineering-advanced。

常见问题

Q. 比起整篇贴，做指令书不是更费事吗？ 头几次确实会有这种感觉。但把丢出去后铺开的改动重新读一遍、再回退的时间，长远看反而更重。分拣熟练之后一分钟就搞定。

Q. 分拣也能交给 AI 做吗？ 可以。上面那段 prompt 模板，就是这个用法。只是拿到的指令书，人要再读一遍，只确认未确认有没有被写成事实。

Q. CLAUDE.md 和指令书有什么区别？ CLAUDE.md 是整个项目里不变的规则库，指令书是这一次工作的一回请求。要是指令书里的「决定」反复出现，那就是把它升格进 CLAUDE.md 的信号。

Q. 不用 Obsidian 也能用吗？ 能。Notion 也好，纯文本笔记也好都行。重要的不是工具，而是把内容分成事实、决定、未确认、下一步的那套想法。

Q. 到哪一步交给 AI，从哪一步该人来决定？ 「找、写、跑」交出去没问题，「范围铺到哪」「能不能公开」由人攥着。诀窍就是把这条线写进指令书。把活儿交给 AI 的基础，我在 claude-code-for-non-engineers 里讲过。

实际试下来的结果

那次「没让做却改了三个文件」的事故之后，我就改了习惯：贴笔记之前，必定先往六项里分拣。

我真的把同样那个结账页按钮的修改，这次做成指令书再交出去。改动就一个文件，CSS 几行而已。页头页脚，凡是没让它碰的，一概没动。中途 checkBrief 还拦了我一次——我想在未确认为空的状态下就交，被它逼着补上「是哪个组件持有留白」之后再交，我觉得这一步也起了作用。因为 AI 先去把那个组件找出来了。

我确认到的就两件事：「把未确认留着，AI 不会擅自填补，而是会去查」；以及「下一步收敛成一件事，改动就小、好回退」。比起去搜什么聪明的 prompt，交出去之前花一分钟分拣，到头来才是最快的——这是我现在的真实体会。

笔记分拣熟练之后，如果你想把同一套方法在整个团队里跑起来，我也准备了一起设计推进方式的培训・咨询。

官方的前置条件可以在 Anthropic Claude Code getting started 里确认。