How to Generate a CLAUDE.md File for Your Repository

To generate a CLAUDE.md, run /init inside Claude Code for a first draft from what Claude finds in your repository, or run repowise generate-claude-md to render one from a real dependency graph, git history and recorded decisions. The repowise file needs no LLM call and no API key, and repowise update keeps it current as the code changes.

Part of the Auto Wiki guide. New to these files? Read the CLAUDE.md and AGENTS.md complete guide first.

The quick answer

Both routes produce a file Claude Code reads at the start of every session. They differ in where the content comes from and whether it stays current.

Use /init for a quick start on a small repository. Use repowise when the repository is large enough that a model's one-time exploration misses things, or when the file must follow the code. The two combine: write your team's rules by hand, and let repowise own the structural half.

What a CLAUDE.md should contain

A CLAUDE.md is persistent context that loads into every session, so it should hold only what the agent cannot cheaply discover and would otherwise get wrong. Anthropic's memory documentation lists project-level standards: build and test commands, coding standards, architectural decisions and naming conventions. It also advises a target of under 200 lines per file, because longer files consume more context and reduce adherence, and it treats the file as context rather than enforced configuration (as of October 2026).

That makes selection the hard part. A useful file answers five questions:

1. What is this system and how is it shaped?
2. Which files matter most, and where does execution start?
3. Which files are fragile?
4. How do I build, test and lint?
5. Which decisions were made on purpose and should not be undone?

A hand-written file answers them on the day it is written. By the next refactor it points at directories that moved. Generating the structural answers from the code removes that drift.

Step 1: Generate it with repowise

Install repowise, index the repository, and the CLAUDE.md is written as part of the run.

pip install repowise
cd your-repo
repowise init --no-prose -y

--no-prose builds the index and a structural wiki with no LLM calls and no key. Drop it to add model-written wiki pages on top. Either way init registers the repowise MCP server with Claude Code and writes the managed CLAUDE.md after indexing finishes.

To regenerate the file on its own, or to preview it:

repowise generate-claude-md              # write .claude/CLAUDE.md
repowise generate-claude-md --stdout     # print it, write nothing
repowise generate-claude-md -o docs/CLAUDE.md

Pass --no-claude-md to init to skip the file; the preference is saved to .repowise/config.yaml as editor_files.claude_md: false. All flags are in the CLI reference.

Step 2: Read what it wrote

The generated section has three parts, targeted at 150 to 250 lines in total. It sits between two markers; everything above them is yours.

# CLAUDE.md

<!-- Add your custom instructions below. repowise will never modify anything outside the REPOWISE markers. -->

[your own rules: style, test commands, workflow]

<!-- REPOWISE:START - Do not edit below this line. -->
## Codebase Intelligence
...
<!-- REPOWISE:END -->

Two details matter for quality. Entry points are ranked on execution-start evidence, not on how many files import them, because centrality rewards a widely imported barrel file over the real front door. And every list has a stable sort order with the path as the final tie-break, so regenerating on an unchanged index produces an identical file and clean diffs.

The repowise wiki for the repowise repository: the repository overview page with its architecture section and linked files

The overview page above is where the architecture summary comes from. The generator takes its first sentences, so the file and the wiki never disagree.

Step 3: Add your own rules

Put team conventions above the REPOWISE:START marker, where repowise never touches them. Good candidates are rules the code cannot reveal: a naming convention, a "never edit generated files" instruction, the PR checklist, which test command to run before pushing. Keep each rule specific enough to check. "Run npm run test before committing" beats "write good tests".

If a file already exists without markers, repowise appends its section at the bottom and leaves your content as it was. Anything you type inside the markers is overwritten on the next run.

Step 4: Keep it current

repowise update re-analyzes only what changed and regenerates the managed section afterwards. It is incremental, so it fits a post-merge hook or a CI job.

repowise update

Because the content is derived from the index, there is nothing to remember to edit. Move a service from /lib to /core and the next update changes the key modules list to match.

Step 5: Connect the MCP server

CLAUDE.md orients the agent; the MCP server answers specific questions. The file covers what fits in 200 lines. For everything else, Claude Code calls the ten repowise MCP tools on demand, and the generated workflow guide tells it when:

The rest are get_overview, get_health, get_symbol and search_codebase. See the AI context feature page and the MCP tool reference.

Large repositories and monorepos

Keep one root file small and split by scope. Claude Code loads a subdirectory's CLAUDE.md only when it works on files there, and supports path-scoped rules in .claude/rules/ for guidance that applies to part of the tree (Anthropic docs). Put architecture and commands at the root, and package-specific rules next to the package.

For several repositories, repowise generate-claude-md --workspace writes a workspace-level file at the workspace root with cross-repo contracts, co-changes and per-repo summaries.

Using AGENTS.md or another agent

Claude Code can read a repository's AGENTS.md in place of a CLAUDE.md. repowise writes a managed AGENTS.md for Codex with repowise init --codex, using the same marker scheme, so one index can feed both. Other hosts are wired with repowise agents add. The CLAUDE.md and AGENTS.md guide covers choosing between them.

Pitfalls

• The file is too long. Past about 200 lines, adherence drops. Trim your own section first; the generated one is already capped.
• Rules go inside the markers. They are overwritten on the next run. Write above REPOWISE:START.
• Treating it as enforcement. Anthropic describes CLAUDE.md as context, not configuration. To block an action outright, use a hook.
• Claude is not loading it. Run /context in a session and check the Memory files list. Project files live at ./CLAUDE.md or ./.claude/CLAUDE.md.
• A stale index. The file reflects the last init or update. Run repowise update after a large change.