CLAUDE.md Generator

How repowise keeps Claude Code informed about your codebase automatically.

Table of contents

  1. What it is
  2. How it’s generated
  3. Two-section design
  4. Merge behavior
  5. What Claude does with it
  6. Auto-sync on commits
  7. Opting out

What it is

Claude Code reads .claude/CLAUDE.md at startup to understand the project it’s working in. repowise generates this file from your indexed codebase — filling it with architecture summaries, hotspot warnings, module maps, MCP tool instructions, and codebase conventions.

The result is a Claude that understands your repo’s structure, knows which files are risky to edit, and uses the right tools before making changes.

How it’s generated

The generator runs at the end of repowise init and repowise update, or on demand:

repowise generate-claude-md

It queries the already-indexed database — no LLM calls are made. All content comes from data collected during ingestion and analysis.

What goes into the generated content:

Section Source
Architecture summary Repository-level wiki page (4 sentences max)
Key modules Top modules by PageRank with purpose and owner
Entry points Detected main.py, __main__, CLI entry files
Tech stack Languages, frameworks, databases, infra
Hotspots Top 5 high-churn files with percentile rank
MCP tool instructions Mandatory usage table for the default MCP tool surface
Codebase conventions Active architectural decisions + build commands

Two-section design

The file is split into two sections with clear markers:

# CLAUDE.md

<!-- Add your custom instructions here. repowise will never
     modify anything outside the markers below. -->
<!-- Examples: coding style, test commands, constraints -->

Your custom content goes here and is never touched.

<!-- REPOWISE:START — Do not edit below this line. Auto-generated by repowise. -->

## IMPORTANT: Codebase Intelligence Instructions for my-repo

> **CRITICAL**: This repository is indexed by repowise.
> You MUST use the repowise MCP tools below instead of reading raw source files.

... auto-generated content ...

<!-- REPOWISE:END -->

Your section (above the markers): Add anything you want — coding style rules, test commands, workflow preferences, constraints. repowise never touches this.

repowise section (between markers): Fully auto-generated. Updated on every repowise update run. Never edit this manually — changes will be overwritten.

Merge behavior

The generator handles three cases:

Scenario Behavior
No existing file Creates file with empty user section + repowise section
File without markers Appends repowise section at the bottom, preserves all existing content
File with markers Replaces only the content between markers, preserves everything outside

Updates are written atomically via a temp file — if something goes wrong mid-write, the original file is not corrupted.

What Claude does with it

When Claude Code opens your project, it reads CLAUDE.md and sees:

  1. The MCP tool instructions — a mandatory workflow table telling Claude to call get_overview() first, get_context() before reading files, get_risk() before edits, etc.

  2. The hotspot warning — a table of high-churn files with their percentile ranks and owners, so Claude knows which files need extra care.

  3. The architecture summary — enough context to understand the repo without reading every file.

  4. Codebase conventions — active architectural decisions that should be respected.

This is why Claude Code performs better on indexed repos — it has the same mental model a senior engineer would have after a few weeks on the project.

Auto-sync on commits

If you’re using repowise watch, CLAUDE.md is updated automatically whenever indexed files change.

For manual sync after coding sessions:

repowise update               # Updates wiki + regenerates CLAUDE.md
repowise generate-claude-md   # Regenerates CLAUDE.md only (faster)

In Claude Code, run /repowise:update to trigger an update from within your editor.

Opting out

To skip CLAUDE.md generation entirely during init:

repowise init --no-claude-md

To generate the content without writing a file (for inspection):

repowise generate-claude-md --stdout

To write to a custom path:

repowise generate-claude-md --output ./my-custom-context.md