Turn an Obsidian Note into a Claude Code Brief That Doesn't Wander

Last week I left a 2,000-word note sitting in Obsidian, and the next morning I told Claude Code: “fix that checkout button, would you?”

What came back was the button fix plus a margin tweak in the header, a reordering of the footer links, and, for good measure, a cleanup of the CSS naming convention across three files of diff. I asked for none of it. The reason was simple: I had pasted the whole note. A throwaway “this bugs me too” from three days earlier got read with exactly the same weight as today’s instruction.

The note wasn’t the problem. The problem was me thinking a note was something I could hand over as-is. A long note is great for recording. It is terrible as a set of instructions. Today I’m writing down the format that closes that gap: how to turn an Obsidian note into a short, sharp brief.

Key takeaways

• Paste a long note whole and the AI can’t tell an old aside from today’s instruction, so it widens the job into work you never asked for.
• You hand over four things only: the facts you know, the decisions you’ve made, what’s still unknown, and the next step. Add two more: places not to touch, and the evidence that says you’re done.
• Keep the “done” condition small. One file, one screen, one command. Build it and look at the screenshot before moving on.
• Copy the template prompt and the short conversion code below and use them as-is.
• Delegate “writing, finding, fixing” to the AI. You decide “scope, priority, ship or not.” Blur that line and you get accidents.

Why pasting it whole makes things sprawl

Claude Code moves fast. That’s exactly why, when the first input you hand it is broad, it runs at full speed while staying broad.

A note has a time gap baked in. Today’s fact (“the button wraps”) and a week-old impression (“come to think of it, the colors look dated too”) sit side by side as the same bullet point. A human reads them apart using dates and context. The pasted-in AI can’t tell which line is a live instruction. So, trying to be helpful, it touches all of them.

There’s a second issue. A note mixes “what I’ve decided” with “what I’m still unsure about.” When the unsure parts get read as instructions, the AI quietly picks one side and runs with it. That’s the scariest part. So before you hand anything over, a human has to sort it once.

You hand over four things only

The sorting rule is simple. Drop each line into one of these four:

1. Facts: things you actually confirmed. “On a 375px screen the button wraps to two lines,” “the live URL is correct” — anything anyone would agree with on sight.
2. Decisions: things already settled. “The free PDF goes ahead of the paid course” — a policy that’s been argued out and won’t move.
3. Unknowns: things you don’t know yet. “Not sure which component owns the button’s margin” — gaps you don’t want the AI filling in on its own.
4. Next step: the one thing for this round. Be specific, down to “find the component, apply the smallest CSS change, verify at mobile width.”

Then add two. Places not to touch (e.g. don’t go near the auth files this time) and the evidence that says you’re done (e.g. the build passes, a screenshot at mobile width). Those six items are the body of the brief.

The one thing to watch while sorting: don’t delete the unknowns. Leave what you don’t know honestly on the page, and the AI will ask about it. Erase an unknown and write it like a fact, and the AI plows ahead on a wrong premise.

What to delegate, and what you decide

Draw the line first between what you let the AI handle and what you keep. If this line is fuzzy, the brief won’t save you — you’ll drift anyway.

Stage	Delegate to the AI	You decide
Scope	-	Which file or screen to narrow to
Investigation	Find the component or code	What to prioritize finding
Implementation	Write the smallest change	The ceiling on what may change
Verification	Run the build and tests	The final call on whether to ship

As the table shows, “find, write, run” is what the AI is good at. “How far to go” and “is this OK to ship” stay with you. Write that line into the brief, and when the AI starts to widen the scope, it stops itself.

A copy-paste prompt template

First, select your note and paste it under this request. This use makes the AI do the sorting itself.

Turn the following Obsidian note into a short brief for Claude Code.
Output only the headings below; discard everything else.

- Facts: only what has been confirmed
- Decisions: policies that won't move
- Unknowns: leave as unknown, do not fill in
- Next step: the one thing to do this round, specifically
- Do not touch: files or features to leave alone this time
- Proof: how we'll know it's done (build, screenshot, etc.)

Group old impressions and chatter separately as "reference notes"
and keep them out of the instructions.

Reread the brief it produces, and check only two things: that no unknown has turned into a fact, and that the next step is narrowed to one thing. If it’s clean, paste it straight into CLAUDE.md or an issue comment and ask for the implementation. I’ve written up how to structure CLAUDE.md in detail in claude-md-best-practices.

Code to convert a note into a brief

Before doing it by hand, here’s a small piece of code to get the structure into your body. It runs on Node.js. It holds the note split into the six items above, then assembles the single-sheet brief you hand to Claude Code.

// Hold the note split into facts, decisions, unknowns, next step
const note = {
  title: "Checkout button wraps on mobile",
  facts: ["button wraps to two lines on a 375px screen", "live URL is correct"],
  decision: "the free PDF goes ahead of the paid course",
  unknowns: ["not sure which component owns the button margin"],
  nextAction: "find the component, apply the smallest CSS change, verify at mobile width",
  doNotTouch: ["the auth-related files"],
  proof: ["the build passes", "a screenshot at 375px width"],
};

// Assemble the six items into a single-sheet brief
function toBrief(item) {
  return [
    `Goal: ${item.nextAction}`,
    `Facts: ${item.facts.join(" / ")}`,
    `Decision: ${item.decision}`,
    `Unknown (do not fill in): ${item.unknowns.join(" / ")}`,
    `Do not touch: ${item.doNotTouch.join(" / ")}`,
    `Proof: ${item.proof.join(" / ")}`,
  ].join("\n");
}

// A gatekeeper that mechanically checks for missed sorting
function checkBrief(item) {
  const missing = [];
  if (item.facts.length === 0) missing.push("facts");
  if (item.unknowns.length === 0) missing.push("unknowns");
  if (!item.nextAction) missing.push("next step");
  if (missing.length) {
    throw new Error(`Sorting is incomplete: ${missing.join(", ")}`);
  }
  return true;
}

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

checkBrief is the plain but important part. If you try to emit a brief with empty facts, empty unknowns, or no next step, it stops you right here. Banning “just paste it” at the code stage cuts down on the accident where a sloppy note flows straight to the AI. Paste the output into an issue comment or a handoff note and you can reuse the same judgment on the next task. For how to build a handoff note, claude-code-session-handoff-template is a useful reference.

Where this pays off

1. Asking for an article improvement

Throw “make this article better” over the wall and the AI tends to rewrite the whole body. So in the brief, write “hand over search intent and CTA policy only” and “rewriting the entire body is forbidden.” Sort it: facts are the current headings, the decision is the funnel policy, the unknown is the weak paragraph, the next step is fixing one heading only. The diff shrinks, and reverting takes a second. The setup for Obsidian integration itself is covered in claude-code-obsidian-integration.

2. Fixing a bug

The trick is to hand over the reproduced fact and the still-unknown cause separately. “The button wraps at 375px” is a fact; “which component owns the margin” is an unknown. Blur those and write “the cause must be the CSS,” and the AI starts fixing on a wrong hunch. Hand over an unknown as an unknown, and the AI investigates it first.

3. Taking a consulting request

Don’t show a client’s operations note as-is. Split it into “what we’ll touch this time,” “what we will never touch,” and “what to confirm next time.” Don’t let production data or billing get touched automatically while it’s still unknown. Just writing that line into the brief lets you share your screen during the meeting without worry.

Common mistakes and how to fix them

The mistakes I made at the start mostly land in these three.

The first was pasting the whole vault. Old decisions and current constraints got mixed up, and the AI couldn’t tell which to trust. The fix is simple: sort into the six items above before pasting. Quarantine the three-day-old aside into “reference notes.”

The second was handing over only the decisions. When I wrote just “put the PDF first,” the AI didn’t know why, and did the opposite in another spot. Leave the fact and the reason together and it generalizes well.

The third was making the “done” condition too big. Ask for “tidy it up overall” and the AI helpfully widens the scope. Narrow to one file, one screen, one command, and look at the build and screenshot before moving on. That alone cuts your revert time without slowing you down. For narrowing prompts, see claude-code-prompt-engineering-advanced too.

FAQ

Q. Isn’t building a brief more work than just pasting the whole note? The first few times, yes. But the time spent rereading and reverting the sprawl from a blind hand-off is heavier in the long run. Sorting takes about a minute once you’re used to it.

Q. Can I let the AI do the sorting too? Yes. The prompt template above is exactly that use. But read the resulting brief once as a human, and check only that no unknown has turned into a fact.

Q. How is CLAUDE.md different from a brief? CLAUDE.md is the place for rules that don’t change across the project; a brief is one request for one round of work. If a brief’s “decision” keeps showing up again and again, that’s the signal to promote it into CLAUDE.md.

Q. Does this work without Obsidian? It does. Notion or a plain text note is fine. What matters isn’t the tool — it’s the habit of splitting into facts, decisions, unknowns, and the next step.

Q. How far should I delegate, and where do I decide? “Find, write, run” is safe to delegate. “How far to widen the scope” and “is this OK to ship” stay with you. The trick is writing that line into the brief. The basics of delegating to the AI are explained in claude-code-for-non-engineers.

What I confirmed when I tried it

After the “three-file accident I never asked for” from the intro, I started always sorting a note into the six items before pasting.

I ran the same checkout-button fix again, this time as a brief. The diff was one file, a few lines of CSS. The header and footer — anything I hadn’t asked for — went untouched. checkBrief stopped me once for trying to emit with an empty unknown, and adding “which component owns the margin” before handing it over seemed to help: the AI went and found that component first.

I confirmed two things. That leaving an unknown on the page makes the AI investigate instead of guessing. And that narrowing the next step to one thing keeps the diff small and easy to revert. The honest takeaway is that the one minute of sorting before you hand it over beats hunting for a cleverer prompt.

Once you’re used to sorting notes and want to run the same format across a whole team, there’s training and consultation where we design the rollout with you.

You can check the official prerequisites at Anthropic Claude Code getting started.