CLAUDE.md: The Simple File That Makes Coding Agents Better

A good CLAUDE.md does not make the model smarter. It makes the assignment less ambiguous every time the agent enters your repository.

That modest mechanism explains why a repository built around four plain-language coding rules became one of 2026's most visible agent projects. The instructions tell the agent to surface assumptions, prefer simple implementations, keep changes surgical, and define verifiable success. None is novel software engineering. Putting all four into context before every task is the useful part.

The viral headline said one file reached 91,000 GitHub stars. By August 2, 2026, the repository had moved from forrestchang to multica-ai, grown into plugins and editor rules, and reached 198,529 stars according to GitHub's API.^[1] The number will keep changing. The durable lesson is how small, persistent instructions change agent behavior.

TL;DR

• CLAUDE.md is a Markdown file containing persistent instructions that Claude Code loads as context.^[2]
• The viral repository condensed common agent failures into four rules: think before coding, simplicity first, surgical changes, and goal-driven execution.^[3]
• The file works best when it contains facts and rules needed in almost every session: commands, architecture, conventions, boundaries, and verification.
• CLAUDE.md is context, not enforcement. Use permissions or hooks for actions that must be technically blocked.^[2]
• Keep task-specific procedures in skills and file-specific guidance in .claude/rules/; loading everything globally wastes context.
• A useful file is short enough to maintain, specific enough to test, and revised whenever the agent repeats a mistake.

What is CLAUDE.md?

CLAUDE.md is Claude Code's project instruction file. It is ordinary Markdown, usually committed at the repository root, that gives the agent durable context such as:

• how to install, test, build, and format the project;
• the parts of the architecture that are not obvious from filenames;
• naming and code-style conventions;
• which generated files should not be edited manually;
• which checks must pass before a task is complete;
• repository-specific safety boundaries.

Claude Code reads the file at the beginning of a session. Anthropic describes it as one of two memory mechanisms: people write CLAUDE.md instructions, while Claude's auto memory stores patterns it learns from corrections.^[2]

That sounds like configuration, but Anthropic makes an important distinction. These instructions enter the model's context; they are not hard controls. If “never deploy production” must be guaranteed, a PreToolUse hook or permission boundary is the appropriate layer. A sentence in Markdown can guide behavior. It cannot provide a security guarantee.

Why the four-rule file went viral

The repository now called multica-ai/andrej-karpathy-skills says its guidelines were derived from Andrej Karpathy's public observations about coding-model failure modes.^[3] Its popularity is easy to overcomplicate. Each rule maps a familiar frustration to a behavior the agent can perform.

These rules do not teach TypeScript, database design, or debugging. They shape how the model approaches uncertainty and scope. That makes them reusable across repositories.

The simplicity is also social. A team can read four principles in two minutes, disagree with one, edit it, and review the change in Git. There is no hidden prompt platform to administer.

The four principles, translated into project behavior

1. Think before coding

The original guideline asks the agent to state assumptions, present multiple interpretations when necessary, push back on unnecessary complexity, and stop when genuinely confused.^[3]

Project-specific wording makes it stronger:

Before changing an API contract, identify every in-repo consumer and state
whether the change is backward compatible. If product behavior is ambiguous,
stop and ask; do not choose a behavior silently.

The generic principle sets posture. The concrete addition tells the agent where wrong assumptions are expensive.

2. Simplicity first

“Do not overengineer” is directionally useful but difficult to verify. Add the repository's local definition of simple:

Prefer an existing utility over a new abstraction. Do not introduce a service,
factory, or configuration flag for one call site. Implement only the requested
behavior; list optional follow-ups instead of building them.

This reduces a predictable model tendency: solving a hypothetical family of future problems instead of the current one.

3. Surgical changes

Agents see nearby cleanup opportunities because they read broadly. That does not mean a task authorizes every cleanup.

Every changed line must trace to the request. Preserve surrounding formatting
and naming. Remove imports made unused by your edit, but report unrelated dead
code instead of deleting it.

Small diffs are easier to review, test, revert, and assign. They also reduce the chance that an agent breaks something whose purpose it did not understand.

4. Goal-driven execution

An instruction such as “make it work” leaves the end state undefined. Translate the task into a result the agent can check:

For bug fixes, reproduce the failure with a test before changing production
code. Run the narrowest relevant checks during iteration and the required
project checks before completion. Report commands and outcomes.

This is where autonomy becomes useful. When success is observable, the agent can iterate on failures instead of stopping after the first plausible edit.

What belongs in CLAUDE.md

Anthropic recommends keeping facts in CLAUDE.md that Claude should hold in every session, and moving multi-step or narrow procedures to more targeted mechanisms.^[2] A useful test is: “Would I repeat this during onboarding for almost every task?”

Put these in the root file

• one-paragraph project and architecture description;
• package manager and canonical install, dev, test, type-check, and build commands;
• directory ownership and generated-file boundaries;
• rules that apply across languages or packages;
• definition of done;
• high-frequency mistakes and their correction;
• where to find deeper instructions.

Put these somewhere else

A concise CLAUDE.md template

Copy this as a starting point, then replace every bracketed item. Delete sections that do not constrain your project.

# Project instructions

## Project

[One paragraph: what this repository ships, its main runtime, and the most
important architectural boundary.]

## Commands

- Install: `[command]`
- Develop: `[command]`
- Focused test: `[command with file or pattern]`
- Full test: `[command]`
- Type-check: `[command]`
- Build: `[command]`

## Before editing

- Read the nearest existing implementation and tests before proposing a change.
- State assumptions that affect public behavior, data, security, or compatibility.
- If the request has multiple materially different interpretations, ask.

## Scope

- Implement only the requested behavior.
- Prefer existing patterns and utilities over new abstractions.
- Keep diffs surgical; do not refactor adjacent code unless required.
- Remove only dead code created by your change.

## Project boundaries

- `[path]` is generated; change `[source path or command]` instead.
- `[package]` owns `[responsibility]`; do not duplicate it in `[other package]`.
- Never expose `[secret or private data category]` in logs or fixtures.

## Style

- [Two to five rules that differ from formatter defaults or are easy to miss.]
- Match the surrounding file when no explicit rule applies.

## Verification

- For a bug fix, add or update a test that fails before the fix.
- During iteration, run the narrowest relevant check.
- Before completion, run: `[required commands]`.
- Report changed files, commands run, outcomes, and any unverified risk.

## Deeper instructions

- API work: `.claude/rules/api.md`
- Database changes: `[skill or documentation path]`
- Releases: `[skill or documentation path]`

The template is intentionally plain. A CLAUDE.md should not read like a motivational manifesto. It should reduce decisions the agent would otherwise have to guess.

How Claude Code loads multiple instruction files

Claude Code walks up the directory tree from the current working directory and loads CLAUDE.md and CLAUDE.local.md files it finds. Instructions closer to the launch directory appear later in context. Nested files below the working directory load when Claude reads files in those subdirectories.^[2]

For a monorepo, that allows a useful hierarchy:

repo/
├── CLAUDE.md                 # Organization-wide project facts
├── .claude/
│   └── rules/
│       ├── testing.md        # Unscoped shared rule
│       └── api.md            # paths: packages/api/**
├── packages/
│   ├── web/
│   │   └── CLAUDE.md         # Web-specific architecture and checks
│   └── worker/
│       └── CLAUDE.md         # Worker runtime constraints
└── CLAUDE.local.md           # Developer-only local notes

Files are concatenated as context rather than behaving like a strict configuration override. Contradictory rules may therefore produce inconsistent behavior. Review the hierarchy periodically and remove stale instructions.

How to improve the file from real failures

Do not attempt to predict every possible mistake on day one. Start small and use repeated friction as the backlog.

1. Record the failure. What did the agent do, and what did you expect?
2. Find the right layer. Is this a universal instruction, path-specific rule, task procedure, or hard safety control?
3. Write an observable rule. Replace “be careful” with the action and condition.
4. Test it on a similar task. Confirm behavior improves without blocking trivial work.
5. Delete stale rules. Context has a cost; an obsolete instruction can be worse than no instruction.

Anthropic's practical trigger is memorable: add something when Claude makes the same mistake a second time, when code review catches knowledge the agent should have had, or when you repeat the same correction across sessions.^[2]

Five CLAUDE.md mistakes to avoid

Writing aspirations instead of instructions

“Write excellent, robust code” gives no new information. “Run pnpm test --filter api after changes under packages/api” can be followed and checked.

Copying a giant generic rulebook

A public template can provide ideas, but every unconditional line consumes context and may conflict with the project. Keep the four broad behavioral principles if they help; replace generic technology advice with local facts.

Encoding facts the agent can cheaply discover

You rarely need to list every directory. Explain boundaries that filenames do not reveal, such as which package owns authorization or which source generates a checked-in client.

Treating instructions as security controls

Never rely on “do not read secrets” or “do not deploy” as the only protection. Use scoped credentials, permissions, sandboxing, and hooks for hard boundaries.

Never reviewing the file

Commands change, packages move, and old exceptions become default behavior. Assign ownership and review CLAUDE.md like code.

How to know whether it is working

Avoid judging the file by whether one demo looks impressive. Measure work the team already reviews:

• median changed lines per completed task;
• unrelated files touched;
• review comments caused by repository-convention violations;
• first-pass test success;
• tasks reopened after a claimed completion;
• repeated clarifications that should become persistent context.

The viral repository suggests the same outcome-level tests: fewer unnecessary diff changes, fewer rewrites caused by overcomplication, and clarification before implementation rather than after mistakes.^[3]

FAQ

Where should CLAUDE.md go?

For team-shared project instructions, place it at ./CLAUDE.md or ./.claude/CLAUDE.md and commit it. Use ~/.claude/CLAUDE.md for personal instructions across projects and CLAUDE.local.md for personal notes in one project.^[2]

Does CLAUDE.md work with Cursor or other coding agents?

CLAUDE.md is a Claude Code convention. The viral repository also ships Cursor rules and a plugin, while other agents may use files such as AGENTS.md or product-specific rule directories. Keep a canonical source and adapt it deliberately rather than assuming every tool loads the same file.

How long should CLAUDE.md be?

There is no universal line count. It should contain only information valuable in nearly every session. If a section applies to one directory or one workflow, move it to a path-scoped rule or skill.

Can CLAUDE.md stop destructive commands?

It can instruct Claude not to run them, but Anthropic explicitly describes the file as context rather than enforced configuration. Use permissions or hooks for reliable prevention.^[2]

How do I create the first file?

Run /init in Claude Code to generate a starter CLAUDE.md, or create the Markdown file manually. Then run /context to confirm it loaded and /memory to inspect or edit memory files.^[4]

The file is simple because the problem is repetitive

Coding agents do not need a 500-line constitution before they can fix a bug. They need a few project facts they cannot infer, a clear boundary around the requested change, and a check that distinguishes completion from confidence.

That is why four ordinary rules traveled so far. They address mistakes developers see every day, live in a format the whole team can edit, and load before the agent starts making decisions. Begin there. Add project knowledge only when it prevents a real failure, and enforce critical boundaries outside the prompt.

If you are new to the tool itself, start with the broader guide to using Claude Code. Use this article when the installation is finished and the next question is what your agent should know every time it enters the repo.

References

1. GitHub REST API. multica-ai/andrej-karpathy-skills repository metadata. Retrieved August 2, 2026. api.github.com
2. Anthropic. How Claude remembers your project. Claude Code Docs. Retrieved August 2026. code.claude.com
3. multica-ai. Karpathy-Inspired Claude Code Guidelines. GitHub. Retrieved August 2026. github.com
4. Anthropic. Claude Code commands. Retrieved August 2026. code.claude.com
5. Sumit Pandey. A Single CLAUDE.md File Went Viral. The Reason Is Embarrassingly Simple. Towards Deep Learning, May 2026. towardsdeeplearning.com

Further reading

• reAPI. How to use Claude Code. reapi.ai/blog/how-to-use-claude-code
• reAPI. How to get a Claude API key. reapi.ai/blog/how-to-get-claude-api-key
• reAPI. Claude model catalog. reapi.ai/models