What should I put in CLAUDE.md?

What Claude can't work out from the code and needs on every task: how to run tests and checks, misleading parts of the code, and decisions not recorded elsewhere. Keep it short.

How long should CLAUDE.md be?

Anthropic's documentation recommends staying under 200 lines, and shorter is better, because the file is loaded into every session.

What is the difference between CLAUDE.md and AGENTS.md?

CLAUDE.md is the file Claude Code loads. AGENTS.md is a similar file read by other coding assistants. A project using several assistants can keep both, and hunch-board init leaves a note in each.

Should architecture documentation go in CLAUDE.md?

Generally not. It costs attention on every task, including unrelated ones. Put it in its own file and leave one line in CLAUDE.md saying where it is.

CLAUDE.md or an architecture board: what goes where

November 5, 2026 · 3 min read

In short: CLAUDE.md is loaded in every session, so keep it to commands, gotchas and rules that apply to every task. Repeatable procedures go in a skill. The design of the system and why it's that way go in a separate plan the assistant reads when the task needs it.

CLAUDE.md tends to grow. Someone adds the deploy steps, then the data model, then a long description of each service, and soon it's a design document that every session has to carry. Anthropic's guide has a clear reason not to do this, and the fix is simply to give each kind of knowledge its own place.

Why CLAUDE.md should stay short

From Anthropic's best practices: Claude Code loads CLAUDE.md into every session, so every line takes a little attention on every task, relevant or not. The guide's memory documentation recommends staying under 200 lines. A description of your payment flow costs something even when the task is fixing a button's color.

What goes where

Kind of knowledge	Where it goes	When the assistant sees it
Test, lint and typecheck commands	`CLAUDE.md`	Every session
Misleading code, and things to not copy	`CLAUDE.md`	Every session
A repeatable procedure, like a release	A skill	When the task calls for it
The parts of the system and how they connect	A plan, like `board.hunch`	When it reads the file
Why a design was chosen, and what was rejected	A plan, like `board.hunch`	When it reads the file
What's out of scope	A plan, like `board.hunch`	When it reads the file
Layout, conventions, frameworks	Nowhere: it's in the code	When it reads the code

The test before you write anything

The guide suggests asking two questions: could Claude find this by reading the code, and would it actually go and look? If both are yes, leave it out. Most of an over-long CLAUDE.md fails this test.

A CLAUDE.md that points to the plan

Keep one line about where the design lives, and let the assistant open the file when the work calls for it. npx hunch-board init adds a note like this for you, and leaves whatever you already wrote alone:

CLAUDE.md

# Commands
- Install: pnpm install
- One test file: pnpm vitest run path/to/file.test.ts
- Typecheck: pnpm tsc --noEmit

# Gotchas
- src/legacy/ is still live, but don't copy its patterns

# Plan
- The plan lives in board.hunch. Read it before changing how parts connect.

And the design in its own file

The board carries what didn't belong above. It can be as short as this, and it's still a real diagram you can open and drag around:

The design, the decision and the scope: everything CLAUDE.md shouldn't carry.

board.hunch

title Appointment reminders

clinic: Web app "Clinic panel" "Next.js"
api: Monolith "Reminders" "Next.js" "Pages and API in one deploy"
db: PostgreSQL "Appointments"
jobs: Scheduled job "Send reminders" "" "Every 15 minutes"
wa: WhatsApp "Patient messages"

clinic => api "books"
api => db "SQL"
jobs => db "due soon?"
jobs => wa "reminder"

note "One deployable until something needs to scale on its own." [decision status=accepted]
note "Can a patient reschedule by replying?" [question]

When to use a skill

A skill is a procedure or piece of team knowledge at .claude/skills/<name>/SKILL.md. As Anthropic's guide explains, Claude sees its name and description in every session and only reads the full file when the task calls for it. That makes skills the right place for a long procedure, such as a release or an incident runbook. Hunch uses one to teach its own file format, so the format's full reference doesn't sit in your CLAUDE.md.

Moving an over-long CLAUDE.md

Delete whatever Claude can read from the code.
Move each repeatable procedure into a skill.
Move the system's design, decisions and scope into board.hunch.
Leave the commands, the gotchas and one line pointing to the plan.
Run /doctor, which Anthropic's guide says suggests cuts for anything Claude can already work out from the code.

Then set up the board with Claude Code, or see why decisions written down change what the AI builds.

Questions

What should I put in CLAUDE.md?: What Claude can't work out from the code and needs on every task: how to run tests and checks, misleading parts of the code, and decisions not recorded elsewhere. Keep it short.
How long should CLAUDE.md be?: Anthropic's documentation recommends staying under 200 lines, and shorter is better, because the file is loaded into every session.
What is the difference between CLAUDE.md and AGENTS.md?: CLAUDE.md is the file Claude Code loads. AGENTS.md is a similar file read by other coding assistants. A project using several assistants can keep both, and hunch-board init leaves a note in each.
Should architecture documentation go in CLAUDE.md?: Generally not. It costs attention on every task, including unrelated ones. Put it in its own file and leave one line in CLAUDE.md saying where it is.