One Claude Code Tip a Day: Bootstrap the Repo Map

This post is part of the “One Claude Code Tip a Day” series — a daily guide to using Claude Code more effectively.

A lot of Claude Code sessions go wrong in the first two minutes. The developer opens a terminal somewhere near the project, asks for a feature, and the agent starts confidently editing files with only a vague model of the repo. Today’s tip is to slow that moment down: use `/init` to bootstrap a repo map, then manually turn the generated `CLAUDE.md` into a field guide for real work.

The real failure: Claude edits the right idea in the wrong place

Imagine a typical frontend bug: the pricing page shows the correct API response in logs, but the card renders blank in production. If you ask Claude Code, “Fix the invisible price,” it may search for obvious component names, patch a nearby file, and miss that the real issue is a shared CSS utility using `background-clip: text` with a theme token that changed after deployment. The failure is not that Claude cannot code. The failure is that it did not have the repo’s operating map: where UI components live, how to run the dev server, which test command is trustworthy, and which deployment logs matter.

Use `/init` as the first inspection pass

In Claude Code, run `/init` at the root of the actual repository, not in a parent workspace and not in a random package directory. Anthropic’s docs describe `/init` as a way to generate a starting `CLAUDE.md`; Claude analyzes the codebase and records build commands, test instructions, and conventions it discovers. That is useful, but the first draft is only a hypothesis.

A good opening sequence looks like this:

`pwd`

`git status --short`

`claude`

`/init`

Then use a read-only prompt before editing:

`Read CLAUDE.md, package.json, the app entry points, and the files related to the pricing page. Do not edit anything yet. Summarize how this repo is organized, which command starts the app, which command runs tests, and what files probably control the visible price card.`

This turns `/init` from a documentation shortcut into a session-control habit.

Verify the generated instructions before trusting them

The generated `CLAUDE.md` often captures the obvious commands, but it may miss the commands that actually work on your machine or in CI. For example, it may list `npm test` even though the useful command is `pnpm test -- --runInBand`, or it may mention `npm run dev` while the project expects `pnpm --filter web dev`. Do not let those inaccuracies become permanent memory.

Ask Claude Code to verify the file against the repo:

`Before editing source code, critique the new CLAUDE.md. Which instructions are inferred rather than proven? Which commands should we run to confirm them? Which sections are missing for debugging frontend rendering issues?`

Then run the safe checks through the shell, either yourself or by letting Claude use shell commands if permissions are appropriate:

`!pnpm install --frozen-lockfile`

`!pnpm --filter web test`

`!pnpm --filter web dev`

If a command fails, the failure should not disappear into chat history. Put the correction in `CLAUDE.md` so the next session starts smarter.

Add the notes Claude cannot infer from static files

The best repo guide is not a pretty overview. It is a collection of operational facts. For a frontend app, include things like: “Use Playwright screenshots to verify visual fixes,” “Check browser console after changing theme utilities,” “The production Railway service uses DATABASE_URL, not localhost,” or “The flaky integration test depends on the eBay sandbox and should be retried once before debugging application code.”

Here is a useful follow-up prompt:

`Update CLAUDE.md with only durable project knowledge. Include verified commands, known failure modes, log locations, and the shortest verification path for UI changes. Do not add generic advice.`

That last sentence matters. Generic advice bloats memory. Durable project knowledge saves future sessions.

The second pass: make Claude challenge the map

After `/init` and cleanup, do one more pass before implementation. Ask Claude Code to challenge its own context:

`Using CLAUDE.md and the current repo, what could still be wrong about your understanding? Name the files you would inspect before changing the pricing page, the tests or screenshots that would prove the fix, and the easiest way this plan could fail.`

This mirrors a strong real-world agent workflow: plan, inspect, challenge, execute, verify. It also catches many false starts. Claude may realize that the visible card is rendered by a shared `PriceBadge` component, that mobile styles override desktop styles, or that the bug only appears after a production build because the dev server does not minify the same CSS.

Failure modes to watch for

First, do not commit the first generated `CLAUDE.md` without review. It may contain commands that happen to exist but are not the team’s preferred path. Second, do not store secrets, temporary debugging notes, or one-off assumptions in it. Third, do not let the file become a wall of process. If a section grows into a long tutorial, move it to separate documentation and keep `CLAUDE.md` focused on what Claude needs during coding sessions.

Finally, remember that `/init` does not replace reading code. It gives Claude a map; the agent still needs to inspect the actual neighborhood before changing a house.

Key takeaway

Use `/init` to create the first repo map, then immediately verify and sharpen it. The rule of thumb: if a future Claude Code session would waste ten minutes rediscovering a command, a test, a log source, or a failure mode, put that fact in `CLAUDE.md`; if it is generic programming advice, leave it out.