The Permanent Files: Memory, and the Five Primitives
That five-part brief from the previous lesson worked. It caught the name-spelling hazard on its own, closed the gap between two files down to the cent, moved the scoreboard for the first time all class. And it lives entirely inside a conversation that dies the moment someone types /clear. Next month, whoever runs Xolo's books retypes it from memory, forgets the exact join rule, and the same trap eats the report all over again. This lesson is about the fix, the one move that turns a good conversation into a durable organization, applied five separate ways.
This is the third unit of Class 3, covering the pivot from a conversation that worked once to files that work every time. Everything here gets exercised for real in the next unit, so read for the shape of each primitive, not just its definition.
The turn
Sit with the question honestly for a moment: where does a good brief actually live, once you've written it? In a conversation. And a conversation is, by construction, the single most perishable container computing has ever produced. It survives exactly as long as the session does, and not one turn longer.
The conversation is volatile. The files are permanent. Nine words, and they carry the entire second half of this class. Every agent frustration you'll ever hear, it forgot, it drifted, I had to retype everything, is a case of trusting the volatile part with something that needed to live in the permanent part. Every win that actually compounds across a project lives in the permanent part instead. Claude Code gives that permanent part real names, real locations, and real load rules, which is what the rest of this lesson walks through.
Memory: four layers, loaded every session
Four distinct memory files get loaded automatically at the start of every session, and knowing which one to write to is most of what separates a tidy project from a bloated one.
| File | Role | Shared with |
|---|---|---|
| Managed policy | Org-wide rules IT controls; wins every conflict | The whole company |
./CLAUDE.md | The project's constitution: committed, versioned, reviewed like code | Everyone who clones the repo |
./CLAUDE.local.md | Personal notes for this project, auto-gitignored | Just you, this repo |
~/.claude/CLAUDE.md | Personal preferences everywhere, language, style, pet peeves | Just you, every repo |
The row that matters most for this course is the second one. The project's CLAUDE.md is committed, versioned, and reviewed like any other change to the codebase, which means a company's actual operating rules end up with a diff history and, ideally, a review process, the same discipline you'd apply to a change in production code. Personal quirks, a preference for a particular formatting style, a note to self about a habit you want reinforced, belong in the local or global files, never in the project constitution. Mixing the two is the fastest way to end up with a CLAUDE.md nobody actually reads.
Three verbs for working with memory
/init analyzes the repository and drafts a CLAUDE.md from what it finds. Treat what comes back as a draft to edit down, not a finished constitution. It's generous by default, and generosity here is a cost, not a virtue, for reasons the next section makes concrete.
The # prefix, typed mid-session, appends a line directly to a memory file with zero friction: # always report row counts, and it's permanent from that keystroke forward. /memory opens the file for more deliberate editing when a single line isn't enough. Either way, memory should grow one burned lesson at a time, not in a single big planning session up front.
An @-style import, @docs/style-guide.md, pulls detail into the constitution on demand rather than pasting it in wholesale. The constitution stays short; the detail stays exactly one hop away when something actually needs it.
The .claude/ directory: the real file tree
Here's the whole architecture laid out as a single directory listing, Xolo's actual repository:
A handbook sits at the root. Inside .claude/, the perimeter, the buttons, the procedures, and the staff each get their own subfolder. Source records stay read-only by rule, and everything the organization actually produces lands in reports/. The next five sections name each role, and the metaphor underneath them does real work rather than decorating the page: a handbook everyone reads, procedures written down once and reused, buttons anyone can press, staff with their own desks, and reflexes that fire whether or not anyone's watching.
| Role | Primitive | Loaded |
|---|---|---|
| Handbook | CLAUDE.md | Every session, injected into the system prompt |
| SOP | Skill | Only when the task matches |
| Button | Command | Only when a human presses it |
| Staff | Subagent | Its own context window and tool list |
| Reflex | Hook | Always, at a lifecycle event, deterministically |
Skills are model-decided. Commands are human-triggered. Hooks are guaranteed. Choosing correctly among the three, deciding which piece of knowledge belongs where, is harness engineering, and it's the exact skill the rest of this lesson is building in you.
CLAUDE.md: what doesn't earn a line
Before looking at what belongs in a project's constitution, it's worth being blunt about what doesn't, because a bloated CLAUDE.md is one of the most common mistakes this course sees made with this tool in the wild.
Pasted API docs and tutorials belong in a skill, not the constitution. "Be helpful and accurate" costs tokens on every single session and changes nothing measurable about behavior. Task-specific instructions belong in the prompt for that task, not in a file every session pays for regardless of relevance. Long prose paragraphs of nuance are unenforceable and unverifiable, and read like aspiration rather than a rule a machine could check. Secrets and credentials never belong here at all; they belong in a deny-list and environment variables, nowhere near a file every session reads by default.
Every line in CLAUDE.md dilutes every other line, in every single session, because the whole file gets read every time regardless of whether a given line is relevant to today's task. That's the actual cost of treating it as documentation instead of standing orders.
CLAUDE.md: what does
Here's Xolo's real constitution-grade file, in outline. Twenty-five lines, in production, right now.
Notice the join rule specifically: it's a burned lesson, the exact lesson the naive run in the previous lesson paid for by failing. That's the discipline worth internalizing here. Mistake, line, never again, and it's the compounding engine underneath this entire course.
Skills: the SOP primitive
A skill is a folder containing a SKILL.md file: YAML frontmatter on top, the procedure itself below.
Read the description field carefully, because it isn't documentation, it's the trigger. Only the name and description ride along in every session's context; the full procedure below the frontmatter loads only when a task actually matches. That's how an organization holds fifty procedures without drowning every single session in all fifty at once, a mechanism called progressive disclosure, and it's the reason skills scale in a way that stuffing everything into CLAUDE.md never could.
A vague description is a skill that never fires. If the description doesn't clearly state what the skill does and when to use it, the model has no reliable signal for when to load the procedure below it, and the whole thing sits unused no matter how good the procedure itself is. Write the description like a routing rule, not a summary.
Skills can also bundle their own helper files, small scripts, templates, reference documents, sitting in the same folder, loaded only when the skill itself runs. And the format follows you across every Claude product that reads it, project skills in .claude/skills/, personal ones in ~/.claude/skills/, which means a well-written skill is an investment that outlasts any one project.
Commands: the button primitive
A command is the simplest of the five primitives: a markdown file whose filename becomes a slash command, with $ARGUMENTS splicing in whatever text follows it.
Typing /reconcile 2026-07 splices 2026-07 into $ARGUMENTS, and seven keystrokes fire the entire procedure. The whole file fits comfortably on a single screen, and that's not an accident; the best pattern here is a thin command that invokes a fat skill underneath it, so the button stays stable on the surface while the actual procedure evolves underneath, without anyone needing to remember to update where the button lives.
Project commands in .claude/commands/ ship with the repository and travel with anyone who clones it; personal ones in ~/.claude/commands/ follow you across every project instead.
Subagents: the staff primitive
A subagent is a markdown job description for a role with its own desk: its own separate context window, and its own restricted list of tools.
Two structural properties turn this from roleplay into something that actually works. The first is the separate context window itself: the verifier can't see the doer's reasoning, which means it can't inherit the doer's blind spots. This is precisely the structural fix for the "are you sure?" failure from the previous lesson: an entirely different context checking the work, rather than the same context re-grading its own answer. The second is the restricted tool list: no Write permission at all, least privilege enforced as one line of YAML rather than a job description hoping the role behaves.
A subagent gets invoked two ways, called by name directly, or delegated to automatically when the model matches the task to the subagent's description, the same trigger mechanism a skill uses. /agents manages the whole roster. And the use of subagents extends well past checking: research sweeps, digesting a large file, anything whose working mess shouldn't pollute the main conversation's window, are all good candidates, because only the conclusion needs to return to the main thread, not the scratch work that produced it.
The checker is never the doer. Every serious auditor already knows this rule; it used to be enforced by professional ethics and organizational separation. Context isolation enforces the identical rule by architecture instead, which means it holds even when nobody's watching to make sure the ethics were followed.
Hooks: guarantees, not suggestions
Hooks are the one primitive that isn't advice to the model at all. A hook is your own script, wrapped around a specific lifecycle event, and it runs regardless of what the model happens to be thinking at that moment.
Before any Write or Edit call executes, guard_paths.py runs. If the target path falls outside reports/, it exits with a nonzero code, the tool call is blocked outright, and the model is told exactly why. Compare this against CLAUDE.md's own line, "never modify data/": that's a request, and a stochastic model tends to honor a request reliably, but reliably is a rate, not a guarantee, and this course treats that difference as real rather than a technicality. The hook makes it always, because it doesn't ask the model to comply, it refuses the call before it can execute at all.
Lifecycle events worth knowing include PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, Stop, and PreCompact, your own code wrapped around whichever moment matters. Common uses beyond the path guard above: logging every command to an audit trail, auto-formatting a file right after it's edited, or sending a notification the moment a long run finally finishes.
Settings: the hierarchy, and the design law
Settings compose in a hierarchy: managed policy at the top, sitting above .claude/settings.local.json, above the committed .claude/settings.json, above ~/.claude/settings.json at the very bottom. IT keeps a floor under every laptop in the organization; teams share the middle layer; individual quirks live at the bottom, never affecting anyone else.
Committed settings are organizational policy expressed as code. Permissions, hooks, and environment configuration all travel with the repository itself, which means every single clone inherits the identical perimeter and the identical reflexes, with no separate setup step required and no drift between one person's machine and another's.
CLAUDE.md is a request a stochastic model usually honors. A hook is a guarantee. Never entrust a guarantee to a probability. Ask of every rule you're about to write down: must this always hold, no exceptions? If yes, it belongs in a hook or the permission perimeter. Does it hold usually, with room for judgment about the specific case? If so, it belongs in CLAUDE.md or a skill instead.
What's next
Five primitives, one governing question each time: does this need to always hold, or does it need good judgment applied to a specific case? Handbook, SOPs, buttons, staff, reflexes, five different homes for five different kinds of organizational knowledge, and the settings hierarchy that lets a team share the middle layer without stepping on each other's personal preferences.
None of this has been exercised yet. The next lesson watches it actually run: a seven-keystroke button firing a full procedure while /context makes progressive disclosure visible before and after, an independent verifier recomputing a report from raw data and returning a real verdict, and finally the organization learning an entirely new trade live, in front of you, closing the scoreboard for good.
Reply here and it goes straight to Rod. Same as replying to one of his emails.
