Most “AI workflow” content is about prompts. The real leverage isn’t
in any single prompt — it’s in the workflow surrounding the prompts. The
format you capture in. The structure your notes already have. The tools
you can chain together. The way revisions roll back cleanly.
Claude Code is the
first AI tool that lets you build that workflow on top of plain markdown
— files on disk, version-controlled, agent-readable, durable. This is
the markdown workflow we use and recommend, end to end. If you’re new to
the broader integration, start with our Claude Code +
Obsidian guide; this post zooms in on the workflow itself.
Why Markdown
Is the Right Format for AI Workflows
Markdown is unglamorous, which is most of why it works. It’s plain
text, human-readable, agent-readable, diff-friendly, and it doesn’t lock
you into any single app. Every tool worth using — Obsidian, Notion exports, static-site
generators, AI agents — speaks markdown natively.
For AI workflows specifically, markdown wins on three axes:
- Lossless round-tripping. Claude Code can read a
markdown file, edit it, and save it back without mangling formatting.
Try that with a Word doc. - Structure without rigidity. Headings, lists, tags,
frontmatter — Claude can parse and respect all of it without you needing
to enforce a schema. - Versionable. Markdown plays perfectly with git,
which means every AI-touched edit is a diff you can review and roll
back.
If your work eventually becomes documents, articles, or code — and
most knowledge work does — markdown is the format AI agents can do the
most useful work in.
The Claude Code
Markdown Workflow Stack
Three tools, in roughly this order:
- A markdown editor with a vault. Obsidian is our default — its plain-file
storage and graph features make it ideal. But anything that stores
markdown on disk works (VS Code with a notes folder, iA Writer, Bear,
plain folders). - Claude Code. The agent that reads, writes, and
reasons over your markdown. - Git. Optional but strongly recommended. Turn your
vault into a git repo and you get a free undo button on every
AI-assisted edit.
That’s it. No plugins required. No SaaS subscriptions. No vendor
lock-in.
Stage 1: Capture (Raw In,
Don’t Filter)
The first stage of the workflow is the most important to get right
and the easiest to get wrong. The rule: when you have a thought, capture
it in markdown immediately, with zero structure overhead.
In practice:
- Keep a
/Inbox/folder in your vault. Every new note
lands here first. - Title can be lazy (“idea about onboarding”). It’ll get fixed
later. - No tagging, no linking, no formatting at capture time. That’s a
separate job. - Use templates only where the friction is low — daily notes, meeting
notes. Skip templates for ideas.
The point of capture is volume and speed. Anything you filter at
capture time, you’ll lose. AI processing in stage 2 is what turns the
firehose into something usable.
Stage 2: Process
(Let Claude Code Do the Sorting)
Once a week (or daily, if your vault moves fast), open Claude Code in
your vault and run a processing pass. The prompt is roughly:
“Read every note in
/Inbox/. For each one, decide: is
this a content idea, a project note, a reference, or noise? Move content
ideas to/Content/Ideas/. Move project notes into the
appropriate/Projects/{name}/folder, creating one if
needed. Move reference material into/Reference/{topic}/.
Archive anything that’s noise. Add tags based on content. Don’t ask
before moving — just do it and report what you moved.”
This single prompt is the hinge of the whole workflow. It does the
work that, done manually, is what kills note-taking systems for most
people. With Claude Code, processing 30 inbox notes takes about a minute
of agent runtime.
A few tips:
- Run it in a git-clean state so you can diff and
revert if Claude Code mis-routes things. - Refine the prompt over time. Add edge cases as you
find them: “if a note mentions Acme Corp, route it to
/Clients/Acme/.” - Have Claude Code ask before deleting. Moving and
tagging are reversible; deletion isn’t. Make that explicit.
Stage
3: Compose (Drafts From Existing Notes, Not From Scratch)
By the time you sit down to write something — a blog post, a
proposal, a strategy doc — you usually have most of the raw material
already in your vault. The composition stage is about pulling that
material together into a draft, not generating content from a blank
prompt.
The pattern:
- Pick a target. “I want to draft a 1,500-word post
on [topic].” - Point Claude Code at the relevant source notes.
“Read everything in/Reference/[topic]/and any note tagged
#research/[topic].” - Give it the structure you want. “Outline a
4-section post: hook, three main points with supporting evidence from my
notes, CTA.” - Iterate on the outline before drafting. “Strengthen
point 2. Cut point 4 — it’s weak. Add a counter-argument section.” - Then draft. “Now write the full post against this
outline. Pull direct quotes and examples from the source notes wherever
they sharpen the argument.”
The output isn’t a finished post. It’s a draft that knows your
existing thinking. The composition stage is dramatically faster — and
the writing is more grounded in what you actually believe — when the
agent is pulling from your vault instead of inventing from scratch.
Stage 4: Polish (Revise, Lint,
Ship)
Polishing is where most AI workflows go off the rails — people accept
a first draft because revising prose feels harder than generating it.
Don’t. The polish stage is where the post becomes yours.
Run Claude Code through this revision sequence:
- Tighten. “Cut 200 words without losing any
substance. Target the intro and the conclusion first.” - Specify. “Find every sentence that’s vague or
hedged. Either make it specific or cut it.” - De-jargon. “Read the post as if you’re a smart
reader who’s not in the industry. Flag anything that would lose them.
Rewrite or cut.” - Voice check. “Read the CLAUDE.md voice rules in the
root of this vault. Now revise the post to match — no first-person,
agency tone, no fluff.” (Or whatever your voice rules are.) - Lint. “Find any remaining clichés, redundancies, or
filler phrases. Cut them.”
Each pass is a separate prompt. You’re using Claude Code as a
sequence of focused editors, not asking one prompt to do everything. The
result is dramatically tighter than what any single-shot generation can
produce.
When the post is ready, ship it. Because everything is markdown on
disk, “shipping” can mean anything: pasting into a CMS, pushing through
a static site generator, kicking off an automated publish pipeline.
CLAUDE.md Is the Glue
The whole workflow above assumes Claude Code knows your conventions —
folder structure, tag scheme, voice rules, what to never touch. That’s
what CLAUDE.md is for. Drop a CLAUDE.md in the
root of your vault and Claude Code reads it automatically every
session.
A markdown workflow without CLAUDE.md works, but you’ll spend half
your prompts re-explaining context. With CLAUDE.md, every session starts
pre-loaded. We cover what to put in it in the Claude
Code + Obsidian guide.
Frequently Asked Questions
Do I need Obsidian to use the Claude Code markdown
workflow? No. Any setup that stores markdown files on disk
works — a plain folder, VS Code with a notes directory, iA Writer, Bear
with markdown export. We recommend Obsidian because of its graph
features and plain-file storage, but the workflow doesn’t depend on
it.
How is this different from using ChatGPT with file
uploads? Claude Code edits files in place, can run multi-step
workflows, and chains with your existing CLI tools (git, scripts, etc.).
ChatGPT-style chat interfaces require copy-pasting and don’t persist
edits. For ongoing workflows on a notes vault, the agent-in-terminal
model wins easily.
Will this work for code, not just writing? Yes — the
same workflow pattern (capture, process, compose, polish) maps directly
to a coding workflow. Markdown notes become design docs, capture notes
become tickets, drafts become PRs. Many Claude Code users run identical
patterns for prose and for code.
How do I keep AI-assisted edits from corrupting my
notes? Two safeguards: (1) keep your vault in git so every edit
is reversible, (2) include a “things to avoid” section in your CLAUDE.md
telling the agent which folders are off-limits and that destructive
operations require confirmation.
Should I worry about Claude reading my whole vault?
Claude Code reads files locally and only sends excerpts to Anthropic’s
API as needed for your prompts — same as any LLM-powered tool. If you
have notes that should never be in any prompt, exclude their folders or
instruct Claude Code in CLAUDE.md to ignore them.
Where to Go From Here
This workflow is enough to transform how you write, plan, research,
and ship. The compounding effect over months is hard to overstate — your
vault becomes a workspace your agent actually understands, and the cost
of producing finished work drops dramatically.
If you want the deeper integration setup (including the Obsidian
MCP server for graph-aware operations), or more day-to-day patterns,
see our Claude Code +
Obsidian pillar guide and our daily
workflows for Claude Code + Obsidian power users.
If you’d like help building this into a content or knowledge system
for your team or business, let’s design
your system.