Generate a CLAUDE.md from your repo’s ADRs and wiki

We keep seeing the same failure mode: an agent lands in a repo, reads a few files, and then spends the next 20 minutes rediscovering decisions that were already made months ago. If you want to generate claude.md that actually changes behavior, the trick is not to summarize the whole codebase. It is to turn ADRs and the living wiki into a short operating manual for agent setup for codebase context — one that says what matters on day one, what is forbidden, and where to read more when the first pass is not enough. how Claude remembers your project

The useful mental model is simple: ADRs tell the agent why the system is the way it is; the wiki tells it what is currently true. Put those together, and you get a file that is specific enough to steer code changes, but not so bloated that the model ignores it after the first screenful.

ADR TO CLAUDE.MD PIPELINE

Start with ADRs: extract decisions, constraints, and exceptions before you write a single rule

ADRs are the right source for durable agent instructions because they encode intent, not just implementation. If a decision has survived review, it belongs in the file that guides an agent on first contact. If it is merely a convenient detail of one service, it probably does not.

A good ADR triage pass is boring, and that is exactly what you want. Use this checklist:

• Keep: boundary decisions, data flow constraints, ownership rules, and explicit exceptions.
• Translate: “We chose X because Y” into a direct instruction the agent can follow.
• Drop: historical alternatives, meeting context, and implementation trivia.
• Drop: anything that can be inferred from code better than from prose.

Examples of ADR-derived rules that deserve a place in CLAUDE.md:

• Service boundaries: “Payments code must call billing-api through the public client; do not import internal handlers.”
• Data flow constraints: “Writes to the ledger go through the event stream, not direct table updates.”
• Naming or layering exceptions: “legacy_* modules are the only place where domain logic may cross persistence boundaries.”
• Review policy: “Any change touching auth, billing, or schema migrations needs an explicit owner review.”

That last point matters because agents are very good at following a rule that is stated plainly. They are much worse at reconstructing policy from a wiki page titled “Notes from the Q3 platform sync.”

If you are pulling from ADRs, favor the sentence that starts with “We decided…” or “We will…” and rewrite it into an imperative. That is the shape an agent can act on.

ADRs for agent context

Use wiki freshness to decide what belongs in CLAUDE.md and what should stay in the wiki

The wiki is where current state lives. That does not mean every page deserves to be promoted into CLAUDE.md.

Promote only wiki pages that are both high-freshness and high-confidence. If a page is stale, experimental, or clearly tied to a temporary migration, keep it out of the memory file and leave it in the wiki where humans can inspect the history. This is the simplest way to prevent an agent from learning a command that stopped working two sprints ago.

A practical rule:

• Promote a wiki page into CLAUDE.md only if it is fresh, confidence-scored highly, and still matches the repo’s current workflow.
• Keep runbooks, temporary migration notes, and one-off incident procedures out of CLAUDE.md unless they are now the canonical path.
• If the wiki says “use this during the migration only,” that is a warning label, not a candidate instruction.

We got this wrong initially by treating “documentation” as a single bucket. The result was a CLAUDE.md full of correct historical facts and wrong operational advice. Agents followed the wrong thing with admirable confidence.

FRESHNESS GATE FOR DOCS

The filtering step should also be opinionated about what not to promote. A wiki page that documents a temporary migration, an obsolete CLI command, or a decommissioned path through the system should remain discoverable in the wiki, but not in the agent’s first-read file. The file should describe how to work here now, not how to survive the last cleanup.

A minimal CLAUDE.md structure agents will actually read on first contact

A good CLAUDE.md is short enough to read before the model starts improvising. Not “tiny,” just short enough that a first pass feels cheaper than guessing.

A practical length is usually one screenful to a couple of screenfuls, depending on repo complexity. If it starts looking like a handbook, it is already too long for first contact.

Prefer instructions over exposition. “Use make test before opening a PR” is useful. “This repo values test discipline” is not.

Copy this section order:

1. Repo summary
2. How to work here
3. Do not do
4. Key commands
5. Architectural guardrails
6. Useful links

That order is doing more than aesthetics. It front-loads orientation, then behavior, then constraints, then escape hatches.

A few things to keep in the file:

• The repo’s purpose in one sentence.
• The default way to run tests, lint, and type checks.
• The one or two paths that are safe for most changes.
• The handful of things the agent should never do without checking first.
• Links to deeper docs, ADRs, and the wiki.

This is where a generated file should feel a little sparse. If every paragraph is trying to explain the system, the agent has no room left to act.

Worked example: synthesize ADRs + wiki into a repo-specific CLAUDE.md draft

Here is what the synthesis step looks like in practice. One ADR gives you the durable rule; one wiki page gives you the current command or convention; the output is a single instruction that the agent can follow.

Notice what disappeared: rationale, historical alternatives, and implementation detail. The agent does not need the full story to do the next correct thing.

A merged instruction can be as blunt as this:

## Do not do
- For invoice changes, use `invoice-service`; do not write directly to the invoices table.
- Keep new domain logic out of persistence layers; `legacy_billing/` is the only exception.
- Before touching deployment manifests, run `make smoke`.

That is the shape you want: one line, one behavior.

If you want a concrete implementation path for the synthesis itself, tools that build repo memory often combine docs and graph signals. Repowise’s decision intelligence and wiki freshness scoring are one example of how to keep the source material current without turning CLAUDE.md into a dump of everything the repo knows. generate a CLAUDE.md from a real repo

Where graph context belongs, and where it does not

Graph context is useful, but it is supporting evidence, not the source of truth for CLAUDE.md.

Include graph-derived context when it helps the agent choose a safe path:

• Ownership hints for high-risk modules
• Entry points and primary call paths
• Blast-radius hints for changes in shared code
• Module relationships that explain where to look first

Do not include graph-derived context when it turns the file into a directory atlas:

• Full symbol graphs
• Exhaustive file maps
• Search results
• Every caller and callee for every function
• Token-heavy inventories of modules

The right boundary is simple: if the graph detail helps the agent decide what to touch next, keep it. If it only proves the repo is large, leave it out and link to deeper context instead.

This is also where a workspace-level memory file can help. In multi-repo setups, a workspace CLAUDE.md can hold cross-repo conventions, while repo-local files stay focused on the codebase under the current change. workspace CLAUDE.md

Copy this into your repo, then prune the obvious lies

Here is a starter CLAUDE.md you can paste into a repo and then trim.

# CLAUDE.md

## Repo summary
[One sentence: what this repo does and who uses it.]

## How to work here
- Read this file first.
- Prefer small, local changes unless the task clearly spans modules.
- Follow the current wiki instructions for setup, test, and release workflows.
- If an ADR exists for the area you are changing, follow it before anything else.

## Key commands
- Install: `[command to install dependencies]`
- Test: `[command to run tests]`
- Lint: `[command to run lint]`
- Typecheck: `[command to run typecheck]`
- Start local dev: `[command to start the app or service]`

## Do not do
- Do not bypass approved service boundaries.
- Do not introduce new patterns when an ADR already standardizes the path.
- Do not copy temporary migration commands into permanent workflows.
- Do not edit generated files unless the task explicitly requires it.
- Do not make large refactors without checking ownership and blast radius.

## Architectural guardrails
- [Decision from ADR #1, rewritten as an instruction.]
- [Decision from ADR #2, rewritten as an instruction.]
- [Exception or boundary rule from ADR #3.]
- [Current convention from a fresh, high-confidence wiki page.]

## Useful links
- ADR index: [link]
- Living wiki: [link]
- Ownership / module map: [link]
- Release or ops runbook: [link]

After the first pass, prune with this checklist:

• Remove any command that is stale, deprecated, or only used during a migration.
• Remove duplicate guidance that is already obvious from the command section.
• Remove rules that belong in deeper docs, not in the first-read file.
• Remove anything the agent can learn better from code than from prose.
• Remove exceptions that are no longer exceptions.
• Remove links that point to dead pages or temporary docs.
• Keep only the rules that would change what an agent does on day one.

If you are generating the file from a repo with structured memory, the output should be a draft, not a decree. Let the synthesis be opinionated, then let the pruning make it honest.

FAQ

How do I generate a CLAUDE.md from ADRs and wiki pages?

Start by extracting durable decisions from ADRs and current workflow from fresh wiki pages. Translate each into short, imperative rules, then merge overlaps so the file stays compact. The goal is a first-contact operating manual, not a document archive.

What should go into a CLAUDE.md for an AI coding agent?

Put in the repo summary, the commands the agent should run, the architectural guardrails that matter, the things it must not do, and links to deeper docs. Favor instructions over exposition. If a sentence does not change behavior, it probably does not belong.

How long should a CLAUDE.md be for Claude Code?

Short enough to read immediately, usually around a screenful or two. If it starts to feel like a handbook, it is too long for first contact. Keep the file optimized for the first task, not for completeness.

Should I put graph context in CLAUDE.md or leave it out?

Include only the graph context that helps an agent choose safely: ownership, entry points, and blast-radius hints. Leave out full symbol graphs, exhaustive file maps, and search results. Those belong in deeper tooling, not in the memory file.

How do I keep CLAUDE.md from going stale?

Promote only high-freshness, high-confidence wiki pages, and review the file whenever an ADR changes. If you can automate stale-doc detection after commits, do that. The fastest way to make a memory file useless is to let temporary instructions harden into policy.