From /init Output to a CLAUDE.md That Actually Steers Claude — A 4-Step Refinement

When you start Claude Code on a new project, running /init to generate a CLAUDE.md is usually the first move. I do the same. But have you ever kept that auto-generated file as-is and quietly wondered why Claude isn't behaving as smartly as you expected?

I run four sites as a solo developer with Claude Code, and I've hit this wall more than once. The conclusion I've landed on is simple: the output of /init is a draft, not a finished file. How carefully you refine that draft determines the quality of the next several hundred sessions.

This article walks through the four refinement steps I run on every new project. It's not a generic explainer — I'll share the actual order of operations and concrete before/after examples, so you can try the same workflow on your own repo today.

What /init Actually Does

People often describe /init as "the command that reads your project and generates a CLAUDE.md." That description is half-right. In practice, Claude Code skims the file tree under the repo root, the manifests like package.json, and the contents of README.md, then summarizes the typical workflows it can infer.

The important nuance: /init only sees what's already written down. Implicit rules — "branch from develop, never main", "split DB migrations into their own PR" — never make it into the output. The freshly generated CLAUDE.md is filled with safe, generic statements like "the build command is X" and "the test command is Y."

In other words, the /init output is roughly the level of an onboarding handout you'd give a new hire on day one. There's nothing wrong with that, but as a foundation for "Claude making judgment calls on your behalf," it's nowhere near enough.

Step 1: Cut the Stuff Claude Can Already Figure Out

The first move is deletion, not addition. This often surprises people, but about half of what /init writes should be cut to make Claude perform better.

Lines like these can almost always go:

• "This project uses TypeScript and Next.js" — Claude can read package.json itself
• The generic file-structure section explaining src/ and public/
• Build commands that are completely standard (npm run dev, npm test)

CLAUDE.md gets read on every session, so loading it with self-evident information just burns through your context window. In my experience, trimming the generated file by 30–50% before doing anything else noticeably sharpens Claude's focus.

# Right after /init
wc -l CLAUDE.md
# e.g. 180 lines
 
# After a confident pass of cuts
wc -l CLAUDE.md
# e.g. 95 lines — and that's still enough

Step 2: Spell Out What Claude Must NOT Do

This is where you get the biggest return. If you want to control Claude Code's behavior, "don't do this" rules are far more reliable than "please do this" instructions.

Here's a slice of what I keep in CLAUDE.md across my projects:

## Things to never do
 
- Don't run `git push` directly inside the workspace repo
  → Causes permission errors. Always work in /tmp/repos/.
- Don't propose "rewrite the whole file" when editing existing code
  → Use the Edit tool with minimal diffs.
- Don't hardcode API keys in code examples
  → Use placeholders like YOUR_API_KEY.

Since adding sections like this, my rate of repeated mistakes has roughly halved. The trick is to add a one-line reason to each rule. Without the reason, the rule reads as arbitrary, and Claude can't extrapolate to edge cases. With it, Claude can make reasonable judgment calls in situations the rule doesn't literally cover.

Step 3: Add the Project-Specific Judgment Calls

Now you write the things /init could never know — the calls that reflect how you, personally, want this project run. Examples I actually keep in my files:

• "Every article must be created as a Japanese + English pair" (Dolice Labs operations rule)
• "Stabilizing existing features takes priority over adding new ones" (this site's stance)
• "Tests are behavior-based — never test implementation details" (team agreement)
• "Before changing a file, copy it to _backup/ first" (incident prevention)

None of this is in the code. Whether or not it's in CLAUDE.md changes the quality of Claude's suggestions dramatically.

The writing tip here is to make the decision criteria explicit. Instead of "try to do X," write "if A, do X; if B, do Y." Branches like this let Claude choose without hesitation.

Step 4: Show the Pattern with a Real Example

The last step isn't prose — it's a code sample, a commit message example, or a real file structure that demonstrates the pattern you want Claude to follow.

I keep one or two "good past work" examples at the bottom of CLAUDE.md:

## Reference: a good past task
 
### Issue #74 — splitting article HTML into assets
- Problem: articles.json grew past 62 MiB and broke the Worker limit
- Fix: HTML moved to per-file in public/content/, JSON kept metadata only
- Lesson: Cloudflare Workers limits hit on total bundle size, so anything
  loadable on demand should be separated from the bundle.
 
Apply the same approach to other size-related issues.

Rules-as-prose leave Claude wobbling on edge cases. A concrete example sharpens the resolution instantly. When I start a new project, I make a habit of picking one representative task from the first week and recording it in this format.

If you want to go deeper on shaping CLAUDE.md as a whole, the CLAUDE.md design productivity guide covers the broader architecture of project-level steering.

My Minimal CLAUDE.md Template

With the refinement direction clear, here's the bare-minimum template I actually use when bootstrapping a new project. It's typically 30–60 lines, and that's enough to make Claude behave noticeably better.

# {Project Name} — CLAUDE.md
 
## What this project is
(1–2 lines: purpose, who it's for)
 
## Things to never do
- {Concrete rule 1}
  → Reason: {one line}
- {Concrete rule 2}
  → Reason: {one line}
 
## Decision criteria
- {Situation A} → {do this}
- {Situation B} → {do this}
- When unsure → {default}
 
## File-change rules
- Edit existing files with the Edit tool, minimal diff
- New files follow {naming convention}
- {Special-case rule}
 
## Reference: a good past task
(One real task, written as before/after)

I use this template across all four of my sites. It looks too short at first, but the parts you genuinely need will grow naturally as the project evolves. Adding sections only when you actually feel the lack of them is more efficient than over-specifying upfront.

Pairing CLAUDE.md with proper tool permissions in .claude/settings.json makes day-to-day operations even smoother. The Claude Code settings.json complete guide covers that side.

Closing — Just Try the Cutting Step Today

To recap the four steps: cut, write what's forbidden, add decision criteria, show real patterns. In my experience this order works best.

The one thing I'd ask you to try today is Step 1 — the cutting. Take whatever /init produced and slim it down to roughly half the length. You'll feel Claude's responses tighten up almost immediately. The other three steps can grow into the file gradually as you actually run the project.

If you want to tune how Claude phrases things, the Claude Code output styles guide is a good companion read. Combined with CLAUDE.md, output styles let you fine-tune Claude's "personality" inside your project.

Next time you run /init on a new repo, I hope these four steps come back to mind.