CLAUDE.md & Session Notes

The Amnesia Problem

A coding agent starting a fresh session knows one thing extremely well: the code in front of it. It can read every file, trace every import, and grep faster than you can. What it does not know is everything that never made it into a file — that your team decided against Redux last quarter, that the staging database is shared with another team, that "done" on this project means lint-clean with tests passing, that the flaky test inpayments.spec.ts is a known issue and not something to "fix" on the way past. All of that lives in your head, in Slack threads, and in the memory of the last session — and none of those are places the agent looks.

So the default experience of working with agents is Groundhog Day. You explain the test command again. You correct the same import-style mistake again. You re-describe the architecture again. Each session starts at zero and burns its first twenty minutes climbing back to where the last one ended. Multiply that by every engineer on the team running multiple sessions a day and the waste is enormous — and entirely self-inflicted, because the fix is mechanical.

The fix is to treat context as a durable artifact. Anything you find yourself telling the agent twice belongs in a file the agent reads automatically. Anything a session learned that a future session will need belongs in a note the next session can read. The moment you do this, the economics flip: an hour spent writing durable context is not overhead on today's task, it is an investment that pays out in every future session — yours, your teammates', and every agent any of you ever launch against this repo.

That is the compounding insight this whole module rests on, so it is worth stating plainly: context files are infrastructure, not documentation. Documentation is written for humans who might read it someday. Context files are executed — loaded into every session, shaping every decision the agent makes, every single time. A wrong line in the README mildly confuses a new hire once. A wrong line in CLAUDE.md actively misleads every agent session on the team until someone deletes it. You maintain infrastructure with a different level of care than you maintain prose, and that is exactly the level of care these files deserve.

CLAUDE.md: The Standing Orders

CLAUDE.md is the file the agent loads at the start of every session, before it reads any code or any prompt from you. Think of it as the project's standing orders: the rules, commands, and warnings that apply to every task, issued once, obeyed always. It is the single highest-leverage file in the repository for agent work, because it is the only file whose contents are guaranteed to be in context for every session anyone runs.

That guarantee cuts both ways. Everything in CLAUDE.md spends tokens and attention in every session — including sessions where it is irrelevant — and everything wrong in it is wrong everywhere at once. So the bar for a line earning its place is high, and the discipline is as much about what you leave out as what you put in.

What Belongs In It

The test for inclusion: would the agent get this wrong without being told, and does it apply to most sessions? Five categories reliably pass that test.

• Commands, with exact flags. How to build, test, and lint — precisely. Not "run the tests" but the literal invocation, including the flag that skips the slow integration suite and the environment variable the dev server needs. Agents are excellent at running commands and terrible at guessing which of your six npm scripts is the real one.
• Architectural conventions. The load-bearing decisions that code alone does not announce: "state lives in the Zustand stores under src/stores, never fetch in components," "all database access goes through the repository layer," "new endpoints go in the v2 router, v1 is frozen." An agent can see what the code does; it cannot see which patterns are the sanctioned ones and which are legacy it must not imitate.
• Naming and style rules the linter cannot enforce.If a machine already enforces it, leave it out — the agent will hit the lint error and fix it. CLAUDE.md is for the rules that live only in review comments: test file naming, how migration files are titled, the team's stance on barrel files.
• Gotchas and landmines. The things that hurt when touched: "the staging DB is shared with the analytics team — never run destructive migrations against it," "legacy/importer.ts looks dead but the cron job calls it," "the e2e suite costs real money per run." One sentence here prevents an incident later.
• Pointers and definition-of-done. Where the key things live ("auth logic: src/auth; API contract:docs/api.md") so the agent starts in the right place instead of exploring — and what "finished" means: tests pass, lint clean, no type errors, migration included if the schema changed. Without an explicit definition-of-done, every agent invents its own, and they are all too lax.

What Does Not Belong

Every line in CLAUDE.md is a claim the agent will believe without checking. That makes the exclusion list just as important:

• Anything derivable from the code. The directory layout, the list of dependencies, what each module exports — the agent reads code faster and more accurately than your summary of it. A prose restatement of the codebase is pure token cost, and it drifts out of date the moment someone refactors.
• Long prose. Paragraphs of project philosophy dilute the rules that matter. Attention over a long instruction file is a budget; spend it on rules, not essays.
• Aspirational process. If the team does not actually do trunk-based development, do not tell the agent it does. The agent will follow the written process, collide with the real one, and produce work nobody wants.
• Stale facts. The command that changed, the directory that moved, the rule the team abandoned. This is the worst category, because every wrong line teaches the agent something false, and the agent — unlike a skeptical new hire — will act on it confidently in every session until it is removed.

Style: Rules, Not Essays

Write CLAUDE.md the way you would write a runbook for a competent engineer with zero history on the team: short, imperative, specific. "Use the repository layer for all DB access" beats a paragraph about the team's data-access philosophy. "Never edit generated files in src/gen" beats an explanation of the codegen pipeline. One rule per line, grouped under short headings, concrete nouns and file paths instead of abstractions. If a line does not change what the agent would do, cut it.

A Worked Example

Here is a complete, realistic CLAUDE.md for a typical web app — about 25 lines, and note how much of the project it covers in that space. Every line is either a command, a rule, a warning, or a pointer.

Notice what is absent: no directory tree, no dependency list, no history, no philosophy. The agent can derive all of that. What it could never derive is that v1 is frozen, that the importer is alive, and that staging is shared — and those are exactly the lines that prevent the expensive mistakes.

Scoping: Root, Directory, Personal

CLAUDE.md files nest, and the scoping rule is the same one you use for code: put each rule at the narrowest scope where it applies.

• Root CLAUDE.md — rules that apply repo-wide: commands, cross-cutting conventions, the definition-of-done. This is the file every session loads.
• Per-directory CLAUDE.md — subsystem rules that would be noise everywhere else. The payments/ directory's idempotency requirements, the e2e/ suite's fixture conventions. The agent picks these up when working in that part of the tree, and the root file stays lean.
• Personal global file (in your home directory) — your own preferences across all projects: how you like explanations, your commit-message style, tools you prefer. Never put team rules here; a rule only you can see is a rule the team does not have.

Maintenance: The Twice Rule

The maintenance loop is a single habit: when the agent makes the same mistake twice, the fix is a CLAUDE.md line. The first wrong guess about your conventions is the agent's fault. The second identical one is yours — it is proof of missing context, and correcting it again in chat fixes exactly one session while writing the rule down fixes all of them. Treat every recurring correction as a bug report against your context files, and close it the same day.

The other half of maintenance is pruning. Put a quarterly pass on the calendar: read the file top to bottom, delete rules the team abandoned, fix commands that changed, tighten lines that grew flabby. Twenty minutes a quarter keeps the file trustworthy, and a trustworthy file is the only kind worth loading into every session.

Session Notes: The Agent Writes Its Own Handoff

CLAUDE.md solves the amnesia problem for facts that are always true. It does nothing for the other half of lost context: what happened in the last session. The refactor that got two-thirds done. The approach that was tried and rejected, and why. The weird coupling discovered at 4pm that the next person will rediscover the hard way. By default all of that evaporates when the session ends.

The house practice: at the end of every substantial session, the agent writes a session note before you close it. Not you — the agent. It has the entire session in context: every file touched, every decision made, every dead end explored. Ask it to summarize and it produces in thirty seconds the handoff document that would take you fifteen reluctant minutes, written while your own memory of the session is already compressing. Your job is to review the note — correct anything it got wrong, cut anything irrelevant — which takes a minute. The review-not-write economics again, applied to memory itself.

What goes in a note — the five headings, in order:

• What was done and why — the changes made and the intent behind them, two or three sentences. Not a diff recap; the PR has the diff. The why is what the diff cannot say.
• Decisions made, alternatives rejected — the most valuable section and the one humans always skip. "Chose optimistic updates over refetch-on-mutate; refetch caused visible flicker on slow connections." This is the line that stops next month's session from relitigating a settled question.
• Unfinished work — exactly what remains, at the level of files and functions, so the next session can start executing instead of re-investigating.
• Landmines discovered — surprises found along the way: hidden coupling, misleading names, a test that passes for the wrong reason. If one recurs across notes, promote it to CLAUDE.md.
• Suggested next step — the single best starting point for whoever picks this up. The difference between a note that gets used and one that gets skimmed.

Where they live: a dated, searchable place in or beside the repo — docs/notes/2026-07-25-checkout-refactor.md, or a comment thread on the tracker ticket if that is where your team looks. The location matters less than the properties: dated, so sequence is obvious; searchable, so "have we dealt with this before" is a grep; and discoverable, which is why the worked CLAUDE.md example above contains a pointer to the notes directory. That single pointer line closes the loop — every future session is standing-ordered to read the latest note before starting.

And that loop is the payoff. Tomorrow's session opens, loads CLAUDE.md, reads yesterday's note, and starts with the decisions, the unfinished work, and the next step already in context — no human re-explaining anything. The same works when it is not you: a teammate picks up your thread mid-feature, or a second agent takes over a task the first one started, and the note is the handoff in both cases. Each session ends by writing the briefing for the next one. That is what "context that compounds" means mechanically: the cost of continuity is paid once, by the party best equipped to pay it, and collected by every session after.

In-Session Context Hygiene

Durable files are half the discipline. The other half is what you put into the live session, because the context window is a working set: everything in it shapes every subsequent decision, signal and noise alike. Four habits keep it clean.

Point at the right files. "Fix the discount calculation in src/server/pricing/discounts.ts" starts the agent in the right place with a clean context. "Fix the discount bug" starts a search expedition that fills the window with candidate files — most wrong, all lingering as noise that can steer later edits toward the wrong module. You know where the code lives; thirty tokens of path saves thousands of tokens of wandering and the misdirection that comes with them.

Paste errors verbatim. Paraphrasing an error ("it says something about a null user") strips exactly the bits the agent needed — the stack frames, the line numbers, the error class. The agent is better at reading a raw stack trace than you are at summarizing one. Full text, unedited, every time; the same rule as chunking's "give the agent the real input."

Recognize the polluted session, and reset. A long session that has gone sideways — three abandoned approaches, contradictory instructions, a wrong turn corrected twice — does not recover by pushing harder. All of that residue stays in context, and old failed attempts keep bleeding into new ones. The professional move is the one that feels like giving up but is not: have the agent write a session note capturing what was learned, which approaches died and why, and where the good state is — then start a fresh session that reads the note. Two minutes, and the new session has all of the knowledge and none of the noise. The note is the checkpoint; the reset costs nothing because the memory survives it.

One task per session. The parallel-agents module gave you one-task-per-agent; this is the same law applied to time. Letting a session drift from the refactor into a drive-by bug fix into a dependency upgrade leaves you with a context window full of three tasks' worth of cross-contaminating detail and a diff no one can review cleanly. Finish, note, close, start fresh. Sessions are cheap; untangling a three-task session is not.

Context Is a Team Asset

Everything so far works for one engineer. The reason it is house practice rather than personal preference is what happens at team scale, where the same files stop being productivity tricks and become shared infrastructure with shared failure modes.

CLAUDE.md is code-reviewed like code — because it runs like code. A change to it changes the behavior of every agent session of every teammate from the moment it merges. A bad rule is a bug with perfect distribution: silently deployed into every session on the team, misleading each one the same way. So changes arrive as PRs, and reviewers hold them to the same bar as the worked example above — is it true, is it at the right scope, is it phrased as a rule the agent can actually follow, is it worth its permanent tax on every session's context? A one-line CLAUDE.md diff deserves a more careful review than a one-line code diff, because no test suite will ever catch it being wrong.

Session notes make handoffs work across people.Within one engineer's week, notes are continuity. Across the team, they are the mechanism that lets anyone pick up anyone's thread: the engineer who goes on holiday mid-feature leaves behind not a mystery branch but a dated note with decisions, remaining work, and a suggested next step — and whoever inherits it starts an agent session that reads the note and continues as if the handoff never happened. Agent threads stop being private property the moment their state lives in files instead of heads.

Onboarding now starts with the context files — read CLAUDE.md, skim the last few weeks of session notes, and a new engineer absorbs in an hour what used to take weeks of tribal osmosis: the real commands, the sanctioned patterns, the landmines, what the team has been deciding and why. This doubles as the cheapest audit you will ever run: if the new hire finds CLAUDE.md confusing, thin, or wrong, then every agent session on the team has been running on confusing, thin, or wrong context all along — the new hire is just the first reader who noticed out loud. Their first PR being a fix to the context files is a healthy sign, not an embarrassing one.

The end state is worth naming. A team that does this well has turned its collective knowledge — conventions, decisions, scars — into files that every agent loads and every person can read, review, and version. The team's memory stops living in heads and Slack scrollback and starts living in the repo, where it compounds. That is the real answer to the amnesia problem: not remembering harder, but building the place where remembering is automatic.

Knowledge Check