Part III · Configure It

Chapter 11: CLAUDE.md, context.md & Memory

For you, the human, start here. CLAUDE.md is the single most important file in your setup: it's the brain your AI loads at the start of every session. This chapter is the mechanics, how your AI writes to it without breaking your flow, how to keep stable identity separate from this-week's changing details, and the one trap (over-generalizing a memory) that quietly makes the whole thing worse. Get this file right and every future session starts smart instead of blank.

What it covers (searchable): CLAUDE.md, /memory, the # quick-pin, context.md, style guide vs taste, the pink-button over-generalization trap, scoping memories.

How to hand it off: point your AI here so it treats CLAUDE.md as a living brain it tends, not a one-time setup. The section below is written to your AI: the in-flow ways to capture a lesson the instant it appears, how to split long-lived identity from changing current-state, and why it must scope every memory so it doesn't turn one request into a forever-rule.

🤖 Everything below is for the AI. "You" means the AI being built; "your human" is the person you serve.

11.1 CLAUDE.md is your living brain

Everything from Chapters 9 and 10 lives here: who your human is, how they want answers, each project's role, their conventions. It auto-loads at session start, so it's the difference between knowing their world and guessing.

Treat it as a living document, not a one-time setup. The whole compounding loop (Chapter 20) is just: keep writing lessons into this file. Two things make that frictionless, /memory and #.

11.2 /memory and the # quick-pin

Don't make your human alt-tab to an editor every time they want to teach you something. Two in-flow moves:

• /memory opens CLAUDE.md in place to edit without leaving the session, and the change is live immediately for the rest of the session.
• # is the quick-pin: start any line with # and you append it to CLAUDE.md as a memory instruction, without breaking flow.

# always use named exports, never default
# the staging DB is read-only, never run migrations against it

The instant you notice a convention, pin it. A lesson captured in the moment beats one meant for later and forgotten.

11.3 Separate stable identity from shifting state: context.md

CLAUDE.md is for things true for a long time, identity, conventions, roles. But a lot of what's useful is current and changing: active projects, this quarter's goals, decisions in flight, who's involved, deadlines. Stuffing that into CLAUDE.md rots it.

The fix: a separate context.md for the current situation,

• active projects
• current goals
• important decisions
• tools in use
• people involved
• deadlines
• things you should not forget right now

Update it when the situation changes; load it when current-state matters. The split keeps your stable brain (CLAUDE.md) clean and your working memory (context.md) fresh. Stale context is worse than none, it confidently misleads.

11.4 Style guide vs. product sense

A useful distinction the Claude Code team draws: some of what you codify is a style guide (concrete, rule-like, naming, formatting, structure) and you pick it up readily from CLAUDE.md. But some of it is product sense / taste, "solve the problem the simplest way and delete everything else", which you don't fully have yet.

Practical consequence: write down the style-guide parts explicitly (they stick), and for the taste parts, keep your human in the loop, that judgment is still theirs to supply. Don't expect CLAUDE.md to carry taste it can't yet hold.

11.5 The trap: don't over-generalize (the pink-button rule)

The hazard with memory is scope. The canonical example: your human says "make the button pink" and you do not want to remember "make all buttons pink, forever."

So when you pin a lesson:

• Scope it. "In the billing UI, primary actions are pink", not "buttons are pink."
• Prefer patterns distilled from many instances over a single transcript (the diary-synthesis approach in Chapter 33). One conversation over-fits; a pattern across many is reliably general.
• When unsure, make it a narrow test or lint instead of a broad CLAUDE.md line: specific enforcement can't over-reach.

Larry's read: a bloated, over-general CLAUDE.md is worse than a short one, it injects confident wrong assumptions into every session. Curate it like you curate context (Chapter 13). Pin liberally in the moment, but prune ruthlessly when a rule turns out too broad. The file should be sharp, not big. And remember TELOS (Chapter 14) is referenced from here, not pasted in, it's too big to auto-load.

11.6 Your next step

Your brain file is solid. Next in order:

• Chapter 12: Prompt Libraries, Templates & Quality Bars, turn your best prompts, templates, and quality bars into reusable objects you call by name.

Then Chapter 13: Context Discipline keeps the whole thing sharp, and Chapter 14: TELOS is the big one, the deep-context layer this file points to.

Back to how.nixfred.com for the next step.

Chapter 11: Takeaways

1. CLAUDE.md is the brain that loads every session, keep it living.
2. Edit in flow: /memory to open it, # to quick-pin a line.
3. Split stable identity (CLAUDE.md) from current state (context.md), and keep the latter fresh.
4. Write down style; supply taste with your human in the loop (the model doesn't fully hold it yet).
5. Scope every lesson; an over-general memory misleads every session after it. Next: Chapter 13.