Raising Claude Code - Part 3: Persuasion

In Part 2 I covered enforcement (permissions.deny for prohibition + Hooks for automation). But enforcement only catches things that can be matched mechanically on a command string. Code-level judgment and design policy — “present a review checklist before changes,” “avoid over-engineering,” “always pair prohibitions with alternatives” — can’t be matched mechanically. From here, you’re in the territory of persuasion = CLAUDE.md.

This post is about what to write in CLAUDE.md, what not to, and at what granularity.

Start small with CLAUDE.md

CLAUDE.md is injected into every turn of the conversation. Make it long, and you waste tokens and dilute attention.

Rule of thumb:

👉 Start under 50 lines. Once it crosses 200, consider splitting.

A long CLAUDE.md tends to:

• Have rules near the bottom drop out of Claude’s attention
• Pile up tokens every turn
• Accumulate contradictory rules

“Just write it all down for safety” is counterproductive. The right pattern: add when an incident shows you should.

What to write in CLAUDE.md

Worth writing:

• Role definition — pick one (partner / butler / reviewer) and stay there
• Decision axes — prefer KISS, avoid over-abstraction, don’t swallow errors, etc.
• Project-specific preconditions — language, framework, deploy target, test runner
• Deviations from convention — the unusual parts of this project (and why we chose to differ from the standard)

The “deviations from convention” point is especially important. Claude has learned standard coding patterns, so if your project does something differently for a project-specific reason, you have to write it down — otherwise Claude will pull you back to the standard.

What NOT to write in CLAUDE.md

Better left out:

• Things you can read from the code — directory layout, naming conventions, import order
• Long procedures — push them to Skills
• Event-driven processing — push it to Hooks
• State — progress, TODOs, who is doing what → goes in git or your issue tracker
• Histories of past incidents — write only the conclusion. The narrative belongs in git log or a PR description

“Better safe to write it” is a trap. A rule that doesn’t get read is the same as no rule.

Write rules at a “decidable” granularity

Bad example:

Write good code.
Be careful about security.

→ Claude can’t decide on this. “Good” and “careful” are subjective.

Good example:

- Before editing auth/authorization code (auth/, middleware/auth*),
  state the changes and their scope, and get user confirmation.
- For dependency additions (package.json, requirements.txt, go.mod),
  state the reason before running.
- For DB schema changes (migrations/), present them paired with a
  rollback procedure.

Two principles:

• Specify what to look at with file paths or patterns
• Don’t just write “forbidden” — pair it with “do this instead"

"Forbid only” makes Claude stall

I want to underline this one.

- Don't swallow exceptions in try/except.

→ …so what should it do? Claude stalls with no path forward.

Rewrite:

- Don't swallow exceptions in try/except.
  When a catch is necessary, log the error and re-raise,
  or rethrow with a meaningful type at a higher layer.

With the “prohibition + alternative” pair, Claude can finally move. Write only the prohibition, and you’ll get either “stalls” or “ignores it.”

Pin the role to one

If you write “butler / teacher / partner / reviewer” all into CLAUDE.md, Claude will average them out and end up as a “lukewarm partner.”

Pin the main agent to a single role. If you genuinely want a different behavior somewhere, separate it into a Subagent (covered in Part 4).

Example:

# Role

You are not just an implementer. You are a development partner
who weighs design, maintainability, and safety.

Before any change that is unclear, dangerous, or hurts maintainability,
state your concerns first. But avoid over-engineering — prefer KISS.

That much is enough.

Wrap-up

CLAUDE.md is the layer of persuasion. Whether Claude actually follows it depends on Claude. So:

• Start under 50 lines
• Don’t write things you can read from code
• Write rules at a decidable granularity
• Pair “forbid” with “do this instead”
• Pin the role to one

Don’t expect 100% compliance the moment you write something. Persuasion has limits, so enforcement (prohibition + automation) backs it up. And enforcement can’t reach what isn’t mechanically decidable, so persuasion is needed. Both wheels.

Next is Part 4: Extension. Where Skills and Subagents fit, and how to write them.