Writing the Instructions Your Next Session Will Actually Read

This chapter explains how to write and test a CLAUDE.md file so a fresh Claude Code session knows a project's commands, layout, and definition of done without being told each time, and covers a recent change to which parts of a session actually read that file. Episode page & show notes Visit website The founding charter The core of this chapter is CLAUDE.md, the file Claude Code loads automatically at the start of every session before your first request arrives — no attaching, no pasting, just a file sitting at the project root or inside the .claude directory that gets read on its own. It walks through the four places instructions can live — the shared project file, a personal file in your home directory, an untracked local variant, and organization-wide settings — and explains that Claude Code doesn't let the narrowest file override the others; it concatenates all of them into context, broadest first, and leans on the model to treat the more specific instruction as the one that wins. From there the chapter builds an actual file for a shared-list app: starting from a /init draft, keeping only the commands that aren't obvious (the dev server, the type check, the one authoritative test command), naming the manual click-through journey that tests alone can't replace, writing down two or three real architectural constraints, and stating flatly what "finished" means. It explains why the file should stay short — it's re-injected on every turn, so bloat taxes every future question — and points to /context, /doctor, and /memory as ways to check what's loaded and trim what doesn't earn its place. It draws a hard line between guidance, which the model can still talk itself past, and real enforcement through a permissions deny list, and closes with a repeatable loop for testing whether an instruction actually changes agent behavior: fresh session, one-line request, watch what's skipped, edit one sentence, retest. What changed in how instructions get loaded A shorter section covers a real gap in that mental model: the built-in Explore and Plan subagents skip reading CLAUDE.md and skip checking Git status entirely, while custom subagents you define still inherit it. It also notes a new flag for passing subagent rules via a file instead of a command-line string, and a fix in recent releases removing an approval prompt that used to stall scripted runs using organization-delivered instructions — all catchable with the same /context check.