How to set up a project wiki for AI agents in 30 minutes

A setup checklist beside a terminal showing the docs/wiki folder tree, and the same notes as a small graph.

In Our project wiki: memory that AI agents can read and write we explained what our wiki is and why it matters: a fresh agent session reads a few short pages and knows how the system works, instead of crawling the code or guessing. This post is the hands-on part. Follow it and in about 30 minutes you will have a working wiki in your own repository.

The short version: a project wiki is an Obsidian vault added to a git repository, plus a rules file that tells the agent how to use it.

What you need:

  • a git repository with some code in it;
  • Claude Code (any agent that reads CLAUDE.md-style rules files works the same way);
  • Obsidian, free, for you and your teammates to browse the wiki.

Step 1. Install Obsidian

Download Obsidian from obsidian.md and install it. Obsidian is a Markdown editor that works on a plain folder of files. A folder it opens is called a vault. Nothing is stored in a cloud or a database: your notes stay .md files that git, your editor and the agent can all read.

Step 2. Create the vault in your repo

Decide where the wiki lives. Two options both work:

  • Inside the code repo, for example at docs/wiki/. Simplest: one repo, and a code change and its wiki update can ship in the same pull request.
  • In its own repo, cloned into docs/wiki/ of the code repo and listed in the code repo's .gitignore. Useful when non-developers edit the wiki a lot, or when several code repos share one wiki.

If you are not sure, start inside the code repo. You can move it later.

Create the folder and the subfolders:

mkdir -p docs/wiki/{concepts,features,decisions,conventions,sources}

Now open it in Obsidian. Click the vault profile icon at the bottom left of the sidebar (or run Open another vault from the command palette) and choose Manage Vaults.... Next to Open folder as vault, click Open, pick docs/wiki, and confirm. (On first launch Obsidian shows the same screen right away.)

Obsidian creates a hidden .obsidian/ folder inside the vault for its settings.

Step 3. Put it under git

If the wiki is inside your code repo, git already tracks it. For a separate repo, run git init inside docs/wiki/.

Commit the notes and the .obsidian/ folder, so everyone gets the same settings. But ignore the layout files: Obsidian rewrites them every time you open a note, which would make noise in every diff. Create docs/wiki/.gitignore:

# Obsidian window layout, changes on every click
.obsidian/workspace*.json

Step 4. Teach the agent Obsidian's format

Obsidian Markdown has a few extras: [[wikilinks]] between pages, callouts, and frontmatter properties. The kepano/obsidian-skills repository is a set of agent skills that teach these formats. A skill is a short instruction file that Claude Code loads only when it needs it.

Install it from inside Claude Code:

/plugin marketplace add kepano/obsidian-skills
/plugin install obsidian@obsidian-skills

The one you will use most is obsidian-markdown. The set also covers Bases (.base), JSON Canvas (.canvas), the Obsidian CLI, and defuddle, which turns a web page into clean Markdown so you can save it as a source.

Step 5. Write the rules for the vault

The skills teach the format. The rules teach the content: what goes where and how pages change. Save this as docs/wiki/CLAUDE.md and adjust it to your project:

# Wiki rules

This folder is the project wiki. Its pages describe how the system works today.
Agents read it before a task and update it after a change. People read it in Obsidian.

## Folders
- `concepts/`: main ideas and parts of the system (billing, users, permissions).
- `features/`: what a user-facing feature does and how it is built.
- `decisions/`: one decision per page: what we chose, why, what we rejected.
- `conventions/`: how we write code here (naming, tests, errors).
- `sources/`: raw input from people (specs, meeting notes). Read only. Never edit.
- `index.md`: the map, one line per page.
- `hot.md`: changes from the last 7 days, newest first.
- `log.md`: one short entry per wiki update.

## Frontmatter
Every page in the four page folders starts with:

```yaml
---
type: concept | feature | decision | convention
status: draft | active | deprecated
sources: []        # links to sources/ pages this page is based on
updated: YYYY-MM-DD
tags: []
---
```

## Writing pages
- A page states the current design on the main branch. One subject per page.
- Rewrite, don't append. When a change makes a sentence false, rewrite that sentence.
  Never add "Update:" or "Changed in ..." sections. History lives in git and log.md.
- Keep every page under 30 KB. Condense or split a bigger one.
- Link related pages with wikilinks, e.g. `[[concepts/billing]]`. Every page links
  to at least one other page, and every link must resolve.
- When code is removed or renamed, turn its page into a short stub:
  `status: deprecated` and one line, `Superseded by [[new-page]]`.
  Never delete a page: old links must keep working.
- A plan that is not built yet is a decision page marked
  "accepted, not yet implemented". Never describe it as current.
- Don't invent. If the code, the sources and the pages don't answer it, ask.

## index.md, hot.md, log.md
- index.md: one line per page, under ~160 characters:
  `- [[concepts/billing]]: how customers are charged`.
- hot.md: one line per change, newest first. Drop entries older than 7 days.
- log.md: append `## [YYYY-MM-DD] update | <title>`, a one-line summary,
  and links to the pages touched.

## Updating the wiki after a code change
1. Read the diff.
2. Find the pages that describe what changed: index.md, then links, then search.
3. Rewrite the sentences the change made false. Add a page only for a new subject.
4. Update index.md, hot.md and log.md.
5. List the pages you touched.

Claude Code picks up a CLAUDE.md in a subfolder when it works with files there, so these rules are in front of the agent whenever it touches the wiki.

Step 6. Point the main rules at the wiki

The agent should read the wiki before every task, not only when it edits it. Add this to the CLAUDE.md at the root of your code repo:

## Project wiki
Before a task, read `docs/wiki/index.md` and `docs/wiki/hot.md`,
then open the pages the task needs and follow their links.
The wiki describes how the system should work. If the task conflicts
with a wiki page, stop and ask which one is right.
While coding, treat the wiki as read-only. To change it, follow `docs/wiki/CLAUDE.md`.

That last line matters. If the agent edits the wiki in the middle of a coding task, it tends to describe what it hopes the code does. Updating the wiki as a separate step, from the real diff, keeps it honest.

Step 7. Draw the map

index.md is the first thing the agent reads, so keep it short: one line per page, grouped by folder. A starter:

# Wiki index

Start here. One line per page. Recent changes: [[hot]].

## Concepts
- [[concepts/billing]]: how customers are charged: plans, invoices, retries
- [[concepts/users]]: accounts, roles and sign-in

## Features
- [[features/checkout]]: the path from cart to paid order

## Decisions
- [[decisions/store-money-in-cents]]: amounts are integers in cents, never floats

## Conventions
- [[conventions/testing]]: what we test and where tests live

Also create an empty hot.md and log.md with just a heading. Here is what one page looks like, concepts/billing.md:

---
type: concept
status: active
sources: ["[[sources/pricing-spec]]"]
updated: 2026-10-23
tags: [billing]
---

# Billing

Billing turns a customer's plan into invoices and payments.

## How it works
- Every customer has one active plan. Plans belong to accounts, see [[concepts/users]].
- On the 1st of each month a scheduled job creates an invoice for every paid account.
- The payment provider charges the saved card. A failed charge is retried
  3 times over 7 days, then the account becomes read-only.
- All amounts are integers in cents, see [[decisions/store-money-in-cents]].

## Where it lives in the code
- `src/billing/invoice-job.ts`: the monthly job
- `src/billing/payments.ts`: calls the payment provider

## Related
- [[features/checkout]]: where a plan is first bought

Notice what the page doesn't say: no "added in March", no list of past tasks. It states how billing works now, in a few kilobytes, and links out for the rest.

Step 8. The first pass: let the agent bootstrap pages

You don't write the first twenty pages by hand. Put any existing specs or notes into sources/, then ask the agent for a plan before it writes anything:

Read docs/wiki/CLAUDE.md. Then explore this repository: the README,
docs/, and the main source folders. Propose 10–20 wiki pages: the main
concepts, the user-facing features, and the conventions you can see.
Show me the list with one line per page. Don't write any pages yet.

Trim or rename the list, then:

Write the pages we agreed on, following docs/wiki/CLAUDE.md.
Describe only what the code does today. Where you are unsure,
add a "> [!question]" callout instead of guessing. Then fill index.md
and add one log.md entry.

Open the vault in Obsidian and read what came out. Answer the question callouts and fix what is wrong. Pay special attention to decisions: code shows what was chosen, almost never why. Write the important decision pages yourself, or ask the agent to interview you about them.

Commit the result like any other change.

Step 9. Keep it true after every change

A wiki that is wrong is worse than no wiki, because the agent believes it. So make one habit part of your workflow: once a change is reviewed, ask the agent to bring the wiki in line with it.

Read docs/wiki/CLAUDE.md, then the diff of <branch, pull request or commit range>.
Update every wiki page this change made false. Add a page only for a new subject.
Update index.md, hot.md and log.md, then list the pages you touched.

Then review the wiki diff like code:

git diff -- docs/wiki

Check that sentences were rewritten, not appended; that nothing describes code that no longer exists; and that the agent didn't invent a "why". With the wiki in the code repo, this diff goes into the same pull request as the change. With a separate repo, it gets its own small pull request.

Step 10 (optional). Lint the wiki

Every few weeks, ask for a health check:

Lint the wiki in docs/wiki. List broken [[links]], pages over 30 KB,
pages with missing frontmatter, pages not listed in index.md, pages
nothing links to, and claims that contradict each other or the code.
Don't fix anything yet.

The mechanical checks are easy to script, so you can run them in CI or a pre-commit hook. A minimal Python version for size and broken links:

# wiki_lint.py: python3 wiki_lint.py docs/wiki
import re, sys
from pathlib import Path

root = Path(sys.argv[1])
pages = {p.relative_to(root).with_suffix("").as_posix(): p for p in root.rglob("*.md")}
names = {Path(key).name for key in pages}
problems = 0

for key, path in sorted(pages.items()):
    text = path.read_text(encoding="utf-8")
    size = len(text.encode("utf-8"))
    if size > 30_000:
        print(f"{key}: {size // 1000} KB, over the 30 KB limit")
        problems += 1
    prose = re.sub(r"```.*?```|`[^`\n]*`", "", text, flags=re.S)  # skip code
    for link in re.findall(r"\[\[([^\]|#]+)", prose):
        target = link.strip().removesuffix(".md")
        if Path(target).suffix:  # images and other attachments
            continue
        if target not in pages and target not in names:
            print(f"{key}: broken link [[{target}]]")
            problems += 1

print(f"{len(pages)} pages, {problems} problems")
sys.exit(1 if problems else 0)

Leave the judgement calls, like contradictions and stale claims, to the agent and to you.

That's it

An Obsidian vault in git, two rules files, a map, and one habit after each change. None of it is tied to a specific tool, and you can start small: even twenty good pages save your agent a lot of guessing. If you want the reasoning behind each rule, read the companion article.

All articles