← Back to blog

Claude Code + Obsidian. How I stopped losing project documentation between projects.

I run seven projects in parallel across four stacks. The docs for each one are current. Not because I'm tidy. Because I no longer write them.

Claude Code writes them inside my Obsidian vault.

Why ordinary documentation dies in a week

Anyone who has run more than two projects at once recognises the picture. A "Setup" page in Confluence from last year. A README written when the stack was different. A Notion with API keys, half of them stale. A Telegram thread that ends with "ask Alex how we deploy this service".

It isn't laziness. It's economics.

To update a doc you have to: switch context, open the right tool, remember the structure, write it, link it to a ticket. Every update is 10–15 minutes of real work plus a context-switch tax. Over a year that adds up to a full month. Nobody gives that month away.

So the docs stay in someone's head. And the head goes on holiday, leaves the company, or simply forgets which folder that one docker-compose was in.

What I changed

A year ago I moved everything into one Obsidian vault. Markdown files on the local machine, a git repo for backup and history. No cloud CMS, no WYSIWYG editors. One vault per project, sometimes one vault per group of projects.

On top of that runs Claude Code in the same folder. It is a CLI agent that reads and writes files in the directory you launched it in. I run it at the vault root, and now I have an interlocutor that sees my documentation as a whole and is able to edit it.

Not "AI in a browser tab". A process living in the same filesystem as the files themselves.

After that, four simple conventions do the work.

1. CLAUDE.md as a contract

CLAUDE.md lives at the root of the vault. Claude Code reads it automatically at startup. I put "how" there, not "what":

  • which tone is allowed in texts,
  • which file names are canonical, which are deprecated,
  • where secrets live and which files must never contain them,
  • how sections are numbered, where the index is, where the log is.

It is a contract, not a stylesheet. When the agent edits a file, it checks against this and doesn't go off-piste.

The closest analogue in a normal team is the onboarding document for a new hire. Except this hire re-reads it from scratch every time, never gets tired, and never pretends to have read it.

2. agent-hint frontmatter on index files

Every index file has this block at the top:

---
type: index
section: "03 - Site"
agent-hint: >
  This section documents the Next.js site. Code is at /Users/me/projects/site.
  When updating pages, also update the Roadmap and SEO checklist in this section.
---

A short note for the agent: why this folder exists, where to look, what to update alongside. When I ask it to add a new article, the agent first reads agent-hint and understands that after the edit it has to update three related files, not one.

The result: docs stay synchronised without me prompting. I used to update the roadmap separately, the publishing log separately, the SEO list separately. Now I update one thing and Claude spreads the change.

3. Skills and memory

The two things that paid off fastest for me.

Skills are built-in capabilities loaded per task. I have a humanizer skill of my own. It strips text of typical AI markers before publishing. This post went through it too. I have a skill for brainstorming, a skill for the git workflow. Each is triggered by a short command — I don't restate the rules every time.

Memory is a persistent folder where the agent writes short notes between sessions. "User prefers first person." "Commits in repo X go under another author." "LinkedIn token lives over there." I never look in there. But in a new conversation Claude has the context and stops asking the same questions over again.

This removes the second big tax. The repetition tax.

4. Subagents for research

When a task requires reading 30 files and finding something specific, I don't do it by hand and I don't make the main conversation choke on grep output.

I dispatch a subagent through the Agent tool, type Explore. It walks the project separately, finds patterns, returns a three-line summary. The main context stays clean.

On a vault of ~400 markdown files the difference is "5 minutes to answer" versus "30 seconds".

What I measured

Holding exact numbers makes no sense — they shift every week. The order of magnitude is this.

Coming back to my own project after two months of absence used to eat an hour. Now it takes about five minutes — I open the vault, ask "where did we leave off on N", and get an answer with links to the relevant files.

The evening 20–40 minutes spent "writing up the wiki after the workday" disappeared. Not because I became more disciplined, but because the update happens in the middle of the work itself. By the end of the conversation the files are already in sync.

"Forgotten things" — needed urgently, written down nowhere — happened twice over two months. Before, it was once a week, steadily.

What doesn't work

To keep this post from turning into a brochure, a few honest spots.

Claude doesn't "understand" the project. It understands what is in the files. If the vault structure is a mess, the agent will produce a mess too. My first week went into tidying folders and indexes. Without that no AI saves you.

Claude doesn't replace an architect. Asked "which stack should I pick" it answers plausibly, but without context about your business and team. Architectural decisions stay with me. The agent just writes them down after me.

Claude sometimes writes too prettily. So the last step in my pipeline is that humanizer skill. It strips the moves that give away AI: "leverage", "delve", an em-dash in every paragraph, lists of three. Without that step the texts are recognisable in two sentences.

Bottom line

I no longer have a separate "write the docs" window. The docs get written while I do my normal work in the same vault.

The stack is simple: markdown in Obsidian, Claude Code running in the same folder, and on top of that the four conventions described above. No new SaaS, no subscriptions to an "AI knowledge base at $30 a seat per month".

If you already have an Obsidian vault and you've never run Claude Code in it, try it on one small project. An evening to install, another evening to lay out CLAUDE.md and agent-hint. From there the system starts supporting itself, and it stops being discipline — it becomes inertia.