AI Guides › Step-by-step guides
By Nigel Guy · 6 min read
Most people fix a coding agent one irritation at a time. It rewrites a function you did not ask about, so you complain. It builds a framework where a ten-line script would do, so you complain again. Each complaint lives in one chat and vanishes with it. The better move is to write the corrections down once, in the file Claude Code reads at the start of every session.
The rule: put four behaviour rules and three short project sections in one CLAUDE.md, keep it under 200 lines, and check it actually loaded.
A popular open-source repository, forrestchang/andrej-karpathy-skills (MIT licence), publishes a single CLAUDE.md built around four principles: think before coding, simplicity first, surgical changes, and goal-driven execution. It says it is based on a post by Andrej Karpathy about common LLM coding mistakes. I could read the repository, but I could not retrieve the post itself (X returned an error), so I am not quoting or paraphrasing what he said. This guide uses the four principles as a structure and writes the wording from scratch. That is deliberate: a file you have read and edited behaves better than one you pasted blind.
You need:
Claude Code's memory documentation lists the locations. For one project, use ./CLAUDE.md or ./.claude/CLAUDE.md; it can be shared with your team through source control. For preferences across all your projects, use ~/.claude/CLAUDE.md. For private notes you do not want committed, use CLAUDE.local.md in the project root and add it to .gitignore.
Start with the project file. Claude Code treats its contents as context, not enforced configuration, so the file shapes behaviour but cannot guarantee it.
Either run /init inside Claude Code, which analyses your codebase and drafts a CLAUDE.md with build commands and conventions it finds (if one exists, it suggests improvements instead of overwriting), or create an empty CLAUDE.md yourself. If you want the repository's version as a starting point, the README gives this command:
curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md
It also documents a plugin route (/plugin marketplace add forrestchang/andrej-karpathy-skills, then /plugin install andrej-karpathy-skills@karpathy-skills). Plugin names and commands change, so check the README before running either. Read whatever lands in your folder before you trust it.
Write these in your own words, short and testable. Here is a version to adapt:
# How to work in this repo
## 1. Think before you code
- If the request has more than one reasonable reading, list them and ask me which I mean.
- State your assumptions in one or two lines before editing anything.
- If a simpler approach exists than the one I described, say so first.
## 2. Keep it simple
- Write the smallest change that solves the stated problem.
- No new abstractions, options or config for needs I have not mentioned.
- No error handling for situations that cannot happen here.
## 3. Make surgical changes
- Touch only the lines the task requires.
- Match the existing style even where you would do it differently.
- If you spot unrelated problems, list them at the end. Do not fix them.
- Remove only the unused code your own change created.
## 4. Work to a clear finish
- Before starting, restate what "done" looks like as a check you can run.
- Run it. Report what passed and what did not.
- Do not call the task finished while a check is failing.
Why these four: each answers a habit you can see in a diff. Silent guessing, bloat, drive-by edits and "it should work" are the usual ones. The fourth matters most, because a test you can run turns a vague request into something Claude can loop on.
The generic rules do half the job. The other half is facts Claude cannot discover. Append short sections:
## My stack
- [LANGUAGE AND VERSION], [FRAMEWORK], [DATABASE]
- Run tests with: [TEST COMMAND]
- Run the linter with: [LINT COMMAND]
## My conventions
- [NAMING, FOLDER LAYOUT, IMPORT STYLE, ANYTHING YOU CORRECT REPEATEDLY]
## Never do this
- Never edit [GENERATED OR PROTECTED PATHS].
- Never add a dependency without asking me.
- Never run [DESTRUCTIVE COMMAND] without asking me.
Fill in the square brackets. Leave out anything Claude can read from the code itself; /init already catches build commands and obvious conventions.
The documentation recommends targeting under 200 lines per CLAUDE.md, because longer files use more context and reduce adherence. Specific, concise instructions are followed more consistently. If something applies only to one part of the codebase, move it into a path-scoped rule under .claude/rules/. Note that @path imports tidy a long file but do not reduce its cost, since imported files load at launch too.
/context and look under Memory files. If your CLAUDE.md is not listed, Claude cannot see it. /memory also lists the locations and opens files for editing.