How to structure CLAUDE.md for long-running projects

lucky — Mon, 08 Jun 2026 17:21:33 +0000

Most CLAUDE.md files fail because they don't actually constrain Claude's behavior. They become too brittle and go stale the moment the project pivots. Don't treat CLAUDE.md as a brain dump. Treat it as an operating contract.

Here's a four-section structure that can hold up over months.

Why most CLAUDE.md files fail

The short version reads like this:

Project: a Next.js app for managing inventory. Use TypeScript. Prefer Tailwind. Don't use class components.

That's a starter, not an operating contract. Claude has no idea what success looks like in this project, what decisions have already been made, what to avoid suggesting. The first session is fine, but come session five, when Claude suggests refactoring the routing layer because "that's the modern Next.js pattern," there's nothing in the file telling it not to.

The too-brittle version is another problem:

The users table joins to profiles via user_id. Always cast UUIDs to strings before sending to the frontend. The Stripe webhook handler in /api/webhooks/stripe.ts requires the raw body. Don't modify /lib/auth/middleware.ts. The pages/dashboard/[id]/edit.tsx file has a known race condition with...

This is everything bolted into one file. The moment any of those facts changes (a schema migration, a webhook refactor, a new auth pattern), the file is wrong.

The fix is to think of CLAUDE.md as a contract, not a wiki. Contracts have sections, and each section answers a different question.

The four sections every CLAUDE.md needs

Section 1: Standing operating instructions

This is what you always want Claude to do, regardless of task. It's the part that should rarely change.

What goes here:

Behavior patterns. "Stop flailing. If three approaches haven't worked, stop and ask what's wrong with the original ask."

Reuse expectations. "Search the codebase for prior art before writing a new abstraction."

Working-code protection. "Don't override working code without an explicit ask. 'I'd write it differently' is not the bar."

Communication preference. "When there are multiple valid approaches, name them and let me choose. Don't silent-pick."

This section is the closest thing to a personality for Claude in your project. Once it's good, you'll port the same rules to every project you start. That's the goal: this section is mostly project-agnostic, so the writing effort compounds.

Section 2: Project context

This is what this project actually is. Why it exists. What success looks like.

What goes here:

One-line project description.

The stack. Language, framework, database, deployment target.

Where the project is in its lifecycle (pre-launch, live, mature).

The locked decisions. Architectural choices that have been made and should not be re-evaluated. ("We use Postgres, not MongoDB. Decided in October. Don't re-suggest.").

The Locked Decisions subsection is the highest-leverage piece in this section. Most session drift happens because Claude suggests a different approach to something that was already decided. Documenting the decision once with the why helps to kill that drift in subsequent sessions.

Write the section so that someone reading it cold could understand what the project is in 60 seconds. If they couldn't, the section is too vague.

Section 3: Conventions and constraints

This is the negative space. What NOT to do. What patterns to avoid. What's already been tried and rejected.

What goes here:

Don't lists. "Don't generate test files unless asked. Don't run destructive commands (drop, delete, force push) without explicit ask."

Anti-patterns specific to your stack. "Don't suggest server components for interactive UI; this project has chosen client components for the dashboard."

Things that might look wrong but are intentional. "The auth middleware doesn't return early on missing session; that's deliberate, see the comment in the file."

The reason to separate this from Section 1 is that constraints change. The standing operating instructions are mostly evergreen; the constraints accumulate as the project matures and as the team learns what patterns don't work for them.

This section is also where you document the tool noise. The things that prompt every session and waste time.

"The dev server throws hydration warnings on hot reload; ignore unless persistent." Documenting these once prevents the same explanation in every session.

Section 4: Lessons

This is the section most people skip. It's the most important one.

What goes here is a running log of what Claude has learned over time. Each entry is short:

LESSON: When blocked on one approach, immediately consider the full toolkit instead of suggesting workarounds.

THE MISTAKE: Hit a network restriction in bash, kept suggesting Python alternatives (same restriction), offered manual download workarounds repeatedly. Only used the browser tool after the user challenged.

THE FIX: When blocked, research own capabilities first. File downloads → browser tool is the direct solution. Don't suggest manual workarounds when there are tools to automate it.

APPLIED TO: SEC filing downloads, any file-from-URL task.

This format does three things. It names the failure mode so it's recognizable. It documents the fix concretely. And it tags the scope, so it's clear when the lesson applies.

The key discipline is to append, not overwrite. When understanding evolves, add an inline correction with a date:

CORRECTION (2026-05-21): The "fully automated, zero manual steps" claim doesn't hold in the scheduled-task sandbox. The host isn't on the allowlist. The pipeline is blocked until either the host is allowlisted or the task runs with a browser connected.

Two months later, when the situation evolves again:

RESOLVED for LOCAL runs (2026-06-05): The host is reachable when the script runs as a normal local process. The block was only the scheduled-task sandbox. Script now has an --auto mode for local execution.

Two dated corrections on top of the original lesson, showing how understanding evolved. Don't overwrite the original lesson. Don't try to fit the resolution into the LESSON text. The chain is the value.

This section is the institutional memory of your Claude work. Without it, every new session starts cold. With it, the first thing Claude reads after the structural sections is "what have we learned that I should know."

What changes between project types

The four-section structure is universal. What goes in each section varies.

Code-heavy projects lean Section 3 hard. Lots of constraints, anti-patterns, framework-specific gotchas. Lessons section captures debugging discoveries.

Writing-heavy projects (research vaults, knowledge bases) lean Section 1 toward editorial discipline. Read-before-write, append-only, framing locks, source hierarchy. Section 3 covers things like "no first-person language outside meta/" or "use canonical entity names, not handles."

Pipeline projects (data scrapers, automated workflows) lean Section 4 hard. The lessons section is where the dated-correction format earns its keep. Verification protocols and tool fallback ladders also live in adjacent files referenced from CLAUDE.md.

Solo vs collaborative: solo projects can use first-person voice in the contract; collaborative projects need to write in voice-agnostic instructions ("the team uses X" not "I use X").

The structure stays the same. The fill changes.

Maintenance

The rule: this file doesn't change without a reason.

Good reasons to edit CLAUDE.md:

A locked decision was made. Add it to Section 2.
A new pattern emerged that's worth treating as a standing rule. Add to Section 1.
A constraint got hit. Add to Section 3.
A lesson was learned. Append to Section 4.

Bad reasons:

"This sentence could be worded better." (Probably true. Not a good reason to touch the file mid-project.)
"I want to reorganize the sections." (You don't. Read the existing structure, work within it.)

When the file gets long enough to feel unwieldy, that's a signal to extract the heaviest sections into separate files and reference them via @import. The full kit's structure (.claude/rules/ for behavioral rules, .claude/reference/ for project-specific data) is designed for exactly this evolution.

The starter is free

There's a starter CLAUDE.md you can download free. It has this four-section structure pre-built, with placeholders ready to fill in for your project. Drop it in your project root, work through it for 15 minutes, and you'll have an operating contract that's already better than 90% of the CLAUDE.md files in the wild.

solooperator.dev

The hardened mode-specific versions (code mode with the modular .claude/rules/ structure, content mode with editorial discipline) are in the full Solo Operator Kit.

Two modes, one kit, $99. Pipeline mode coming in v2 at no additional cost to v1 buyers. Same link.

DEV Community: lucky

How to structure CLAUDE.md for long-running projects

Why most CLAUDE.md files fail

The four sections every CLAUDE.md needs

Section 1: Standing operating instructions

Section 2: Project context

Section 3: Conventions and constraints

Section 4: Lessons

What changes between project types

Maintenance

The starter is free