Agent Upstart

Cool things people are building with agents — and practical help getting the most out of them.

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

  1. Start from a starter file, then cut it. Run /init in the project to generate a starter CLAUDE.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.
  2. Keep the file short and verifiable. The memory docs advise keeping each CLAUDE.md under 200 lines, because longer files consume more context and get followed less reliably. Write instructions concrete enough to check: "Run npm test before committing" instead of "Test your changes," and "API handlers live in src/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 in CLAUDE.local.md at the project root and add that file to .gitignore, so it is never committed.
  3. 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 like testing.md. Rules can be scoped to file paths with a paths field 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: a CLAUDE.md in a subdirectory loads when Claude reads, writes, or edits a file there, not at session start.
  4. 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.
  5. 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.
  6. 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.
  7. Audit for stale and conflicting lines. Run /doctor prompt-audit in 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.
  8. Confirm the file actually loaded, then re-test. Run /context in 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

What can go wrong

Limits

Related playbooks

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