A good CLAUDE.md shouldn't re-explain the product

When you first start using Claude Code, it’s easy to keep adding to CLAUDE.md.

The agent makes a mistake once, and you add a line.

You build a new feature, and you copy the background in.

The architecture changes, and you paste in the latest description.

In the end the file keeps growing and looks very complete, but the agent’s behavior isn’t necessarily more stable.

The reason is:

CLAUDE.md’s job isn’t to store all project knowledge, but to tell the agent how it should work in this repo.

What problems should it solve most?

Useful agent instructions mainly solve four things.

1. Where to find the right facts

For example:

- Product definition: docs/PRODUCT.md

- Current feature specs: docs/specs/

- Architecture: docs/ARCHITECTURE.md

- Design rules: docs/DESIGN.md

- Important decisions: docs/adr/

That’s more reliable than copying the contents of these files again.

Because once the product changes, you only need to maintain the canonical source, not update five duplicate descriptions at once.

2. How to work in this repo

For example:

• which package manager to use
• the common commands for development, testing and lint
• where new files should go
• which modules may depend on which
• how the database schema is changed
• how environment variables are managed
• whether generated files may be edited by hand

These should be specific enough to execute.

An ineffective rule:

Always write clean, maintainable code.

A more effective rule:

Before completing a task, run: pnpm lint pnpm typecheck pnpm test Do not mark the task complete if any command fails.

3. What it mustn’t decide on its own

Coding agents often aren’t “unable to do it”; they overdo it.

You can make explicit:

• don’t change the product scope on your own
• don’t rename core business concepts
• don’t refactor unrelated modules to fix a local problem
• don’t delete files that look unused but whose purpose is unclear
• don’t change global design tokens on your own
• don’t bypass type, test or permission checks
• don’t add new dependencies without approval

Boundaries should be built around real risks, not written out for every possibility.

4. Which mistakes have happened repeatedly

This is the part most worth adding to over time.

For example, the agent has repeatedly:

• put temporary scripts in the project root
• created duplicate components
• overwritten real data with mock data
• changed global CSS while fixing one page
• updated code but forgot to sync the schema
• guessed what a feature does from file names instead of reading the relevant spec

Only mistakes that keep recurring deserve to become long-term rules.

A one-off accident doesn’t necessarily need to be written into the instructions permanently.

What shouldn’t go in?

Long passages of product background

Who the product serves, what problem it solves and what the core flows are belong in PRODUCT.md.

The agent instructions only need to say when to read it.

Detailed requirements for the current feature

The current task should have its own spec.

Otherwise, once the feature is done, this content stays in CLAUDE.md and becomes outdated context.

All past decisions

The historical reasons belong in a decision log or ADRs.

CLAUDE.md only keeps the conclusions that still need to be followed now.

Copies of other documents

Maintain the same rule in two places and sooner or later they’ll disagree.

Requirements that can’t be executed

For example:

Make the best possible UX. Think carefully. Write production-quality code.

These have no standard to check against, and can’t solve repo-specific problems.

How do CLAUDE.md and AGENTS.md divide the work?

When using several coding agents at once, I lean toward:

picking one of them to hold the working rules common across tools:

• repo structure
• canonical sources
• testing requirements
• boundaries for changes
• general development conventions

The other only adds behavior or usage specific to it.

For example:

• which directories to read first
• particular tool-calling habits
• known Claude- or Codex-specific problems

Don’t maintain two sets of product facts in two separate files.

Otherwise Claude Code, Codex and human developers will each see a different version of the project.

A structure that’s good enough

# Agent Instructions

## 1. Canonical Sources

## 2. Repository Structure

## 3. Development Commands

## 4. Implementation Rules

## 5. Validation Requirements

## 6. Do Not

## 7. Known Failure Modes

Every line should directly affect behavior.

For example:

Before editing a feature:

1. Read the relevant spec in docs/specs/.

2. Check related decisions in docs/adr/.

3. Reuse existing components before creating new ones.

4. Run lint, typecheck and relevant tests.

5. Update documentation only when the canonical fact changes.

Don’t chase “the shorter the better”

A CLAUDE.md that’s too long brings noise, but one that’s too short may have no force.

The real test is:

will this information help the agent make a different decision?

If yes, keep it.

If not, delete it or move it to a more suitable document.

I now see CLAUDE.md as a work map, not a product encyclopedia.

It doesn’t need to give the agent every answer.

It needs to tell the agent:

• where the right answers are
• which rules must be followed
• which things mustn’t be guessed
• how to prove, before finishing a task, that it hasn’t broken the project