Playbooks · Coding tasks
Document a codebase so a stranger can work in it
Written October 26, 2026 · Edited October 31, 2026
For a solo developer × documenting a codebase × Claude Code, ending with a short project file that lets a fresh session answer the questions a new hire would ask — and a stranger test that proves it, instead of a long document nobody reads.
Before you start
You need a codebase you already work in and Claude Code running in that project. The document you are writing is not a tour of the code. It is the short list of facts a stranger needs before touching anything: what the project is, how to build and test it, where the main parts live, which conventions are not obvious from reading the code, and which areas are off limits or easy to break. Claude Code reads this file at the start of every session, so what you write here is also what every future agent session will assume about your project. That is why the file earns its place by passing a test, not by looking complete. The file rules below are Claude Code's own memory documentation, and the stranger test is a workflow built on top of them.
The one discipline the whole workflow rests on: a fact goes in the file only if a stranger would get stuck without it. Everything else stays in the code, where it belongs.
Before step 1, make sure Claude Code itself is ready: install it following Claude Code's quickstart, then check with claude --version that you have version 2.1.283 or later. If the version is lower, update it before step 7, because the audit in step 7 does not exist in earlier versions. Native installs update themselves in the background; claude update applies an update at once, and Homebrew, WinGet, and Linux package-manager installs update through the package manager, per the setup docs.
What "done" looks like
At the end of one sitting you have a project file under 200 lines, plus path-scoped rule files for the parts of the codebase that need their own notes, and a stranger-test log: the questions you asked a fresh session, the answers it got wrong or could not give, and the file edits that fixed each gap. A second stranger test then passes without new edits. That log is the documentation; the file alone is only a claim.
Steps
- Start from a starter file, then cut it. Run
/initin the project to generate a starterCLAUDE.md, or write one by hand if you prefer. Either way, the first draft is not the document: read it line by line and delete anything a competent reader could learn from the code in two minutes. What survives is build and test commands, coding standards that are not the language default, the layout of the main parts, decisions that look wrong until explained, and gotchas that have bitten someone before. Claude Code's own memory docs say to add to this file when you catch yourself re-explaining something, when Claude makes the same mistake a second time, or when a review catches something Claude should have known about the codebase. - Keep the file short and verifiable. The memory docs advise keeping each
CLAUDE.mdunder 200 lines, because longer files consume more context and get followed less reliably. Write instructions concrete enough to check: "Runnpm testbefore committing" instead of "Test your changes," and "API handlers live insrc/api/handlers/" instead of "Keep files organized." If two instructions contradict each other, Claude may pick one at random, so a contradiction found later is a file edit, not a shrug. Personal preferences do not belong in the shared file: put them inCLAUDE.local.mdat the project root and add that file to.gitignore, so it is never committed. - Move part-specific notes out of the main file. When a note matters only for one part of the codebase, move it to a rule file under
.claude/rules/— one topic per file, with a descriptive name liketesting.md. Rules can be scoped to file paths with apathsfield in frontmatter, so they load only when Claude works with matching files. That keeps the main file short while the detailed notes still show up exactly where they apply. Files in subdirectories work the same way: aCLAUDE.mdin a subdirectory loads when Claude reads, writes, or edits a file there, not at session start. - Run the stranger test in a fresh session. Start a new session and, without giving any hints, ask it the questions a stranger would ask on day one: what does this project do, how do I build and test it, where does a new feature of each kind go, which files must I not touch without asking, and what happens if I change this one module? Write down every answer that is wrong, vague, or missing. Do not correct the agent mid-test — a correction during the test hides the gap you are trying to find. Each wrong answer maps to one missing or unclear line in the file, and that mapping is the work list for the next step.
- Fix the file, one gap at a time. For each gap, add or rewrite exactly the lines that would have produced the right answer, in the concrete style from step 2. If a gap belongs to one part of the codebase, it goes in that part's rule file, not the main file. If a gap is really a procedure with several steps, it belongs in a skill or a rule file, not in the short project file. Resist the urge to add background: every line you add costs context in every future session, so a line that does not prevent a wrong answer is a line to cut.
- Work domain by domain on a large codebase. If one stranger test covers the whole project, it will be shallow. Instead, run one short session per domain — one for the API layer, one for the data layer, one for the frontend, and so on — each with questions only about that domain. This also keeps each session short enough to stay useful: a session that has to hold the entire codebase in context will start dropping details, and dropped details look exactly like documentation gaps. Record which domain each session covered, so the next round does not re-test the same ground while another domain stays untested.
- Audit for stale and conflicting lines. Run
/doctor prompt-auditin a session and read its report: it looks for instructions written for older models, references to files or commands that no longer exist, and files that contradict each other. Nothing in your files changes until you ask Claude to apply the proposed edits, so treat the report as a review, not an automatic fix. Apply the edits that match reality, reject the ones that do not, and note that this audit needs Claude Code version 2.1.283 or later. - Confirm the file actually loaded, then re-test. Run
/contextin a session and check the memory files list to confirm your file is among the loaded files. Then run the stranger test again with the same questions. The workflow is done when the fresh session answers them without new edits. If a question still fails, the file is still wrong — the test, not your judgment of the file, decides.
Check the agent's work
- Check that every stranger-test answer is backed by a line in the file or a rule file. An answer the agent guessed right is not a pass; it is a gap waiting for a harder question.
- Check that no line in the file contradicts another line, or a rule file. Contradictions are the one defect the memory docs call out by name.
- Check that personal preferences live in
CLAUDE.local.md, not the shared file, and that the local file is gitignored. - Check that the file is under 200 lines. If it is over, something in it belongs in a rule file or in the code.
- Check that the audit report from step 7 was read, not just run. An unread report is the same as no audit.
What can go wrong
- Writing a tour instead of a rulebook. A file that explains what the code does, in the order the code appears, duplicates the code and teaches nothing a reader could not learn faster by reading it. Cut anything the code already says clearly.
- Treating the file as enforced configuration. Claude Code treats these files as context, not as rules it must obey. If an action must be blocked no matter what the agent decides, that needs a hook, not a line in this file — the memory docs say so directly.
- Letting the file rot. A file that names a command that no longer exists is worse than no file, because every session will confidently repeat the stale fact. The audit in step 7 exists for this; run it whenever the project changes shape.
- Testing with hints. If you steer the stranger test toward the right answers, you have tested your own knowledge, not the file. Fresh session, no hints, questions written before the session starts.
Limits
- This workflow documents a codebase; it does not prove the documentation is complete. A stranger test passes the questions you thought to ask, and a real stranger will ask one you did not.
- The file rules here are Claude Code's published memory rules. Other tools read their own files, and may not honor this file.
Related playbooks
- Start work on a codebase you inherited without breaking what already works
- Lazarus: ten neurons can backdoor an agent
- Onboard onto an unfamiliar codebase with an agent
- Clean data can strengthen a hidden backdoor
Sources
Sources: Claude Code memory docs, Claude Code quickstart, Claude Code setup docs, Claude Code cheatsheet.
Back to: Coding playbooks hub · Also: Run three independent lines of research at the same time in Claude Code, then combine the short summaries