The .claude/ Directory Is the Organization
This lesson is the architectural center of this course. Everything before it, the loop equation, briefing as a discipline, Claude Code's hardened version of the same four terms, was building toward one question: if a conversation is volatile and gets wiped by a single /clear, where does an organization's durable structure actually live? The answer is a directory, and this lesson is a tour of exactly what belongs inside it and why.
The previous lesson ended by naming the question this lesson answers: a /clear'd conversation loses nothing that mattered, because nothing that mattered was ever stored there. This lesson covers the anatomy of the .claude/ directory, five roles a piece of durable configuration can play, and the discipline that keeps the whole thing from becoming exactly the bloated mess it's designed to prevent.
Why files, not chat
Start from the property that makes this lesson necessary at all. A conversation is volatile. It exists for the duration of a session, and a single /clear, a crash, or simply starting a new session wipes it completely. Nothing about a chat transcript is designed to survive past the moment it's read. Files are the opposite. They persist on disk, they can be diffed, versioned, reviewed, and handed to a new session exactly as they were left by the last one.
An organization that lives in chat history doesn't really exist between sessions. It has to be re-explained, re-negotiated, re-discovered every single time someone opens a new conversation, which is precisely the failure mode a zero-employee organization can't afford: real institutional knowledge that evaporates the moment nobody happens to be looking at the right transcript. An organization that lives in files exists continuously, whether or not anyone is currently talking to it. That difference, continuous existence versus session-bound existence, is the entire reason this lesson is built around a directory instead of a conversation.
The anatomy: an org chart in files
Here's what a real, working project's .claude/ directory and its neighbors actually look like, using a small consulting firm as the running example this class has used throughout.
CLAUDE.md: the handbook, always loaded into every session's system prompt.CLAUDE.local.md: private notes, gitignored, never shared with the team or committed to the repository..claude/settings.json: permissions and hooks, the permission perimeter from the previous lesson made concrete and the reflexes covered later in this lesson..claude/commands/reconcile.md: a command,/reconcile, a button a human presses..claude/skills/invoice-reconciliation/SKILL.mdand.claude/skills/weekly-report/SKILL.md: standard operating procedures, loaded only when a task matches..claude/agents/verifier.md: a subagent, a controller with its own separate context window.data/andcontracts/: source records, treated as read-only by convention and often by an actual permission rule.reports/: everything the organization actually produces.~/.claude/CLAUDE.md: global preferences that apply across every project, not just this one.
That's a lot of pieces for one directory, and the temptation is to treat them as a feature list to memorize. Resist that. Each one is answering a specific organizational question, and the five roles below are the actual structure worth carrying forward.
Five roles, one design axis
CLAUDE.md rides in the system prompt of every single session, which means you pay for every line it contains, in every conversation, whether or not that line is relevant to the current task. That cost is exactly why it holds only constitution-grade material: rules that are always true, never rules that only apply sometimes. This isn't a stylistic preference. It's a direct consequence of the context window being finite and degrading, the property established in this class's first lesson. A CLAUDE.md padded with material that's only sometimes relevant is a tax on every session, paid whether or not that session needed it.
Skills use something worth understanding by name: progressive disclosure. Only a skill's name and one-line description load by default, at essentially no cost. The full procedure, the actual detailed instructions, loads only when a task actually matches, at which point it enters the context window the same way any other piece of context does. This is the direct answer to "my instructions don't fit in CLAUDE.md": they don't need to, because a skill lets detailed procedural knowledge sit nearly free until the moment it's actually needed, rather than taxing every session the way a bloated handbook would.
A command is a human-triggered entry point, typically with arguments: /reconcile 2026-06 rather than a paragraph typed out fresh each time. Where a skill is model-decided, loaded automatically when the model recognizes a matching task, a command is explicitly invoked by a person who knows exactly which procedure they want run and doesn't want to re-type the brief for it every time. The distinction matters: a command is a deliberate human choice to trigger something specific, not the model inferring what's needed from context.
A subagent is a role with its own context window and its own tool set, spun up as a fully separate instance of the loop equation, not a stylistic subdivision of the same conversation. The isolation is the entire point, not an implementation detail. Recall the "are you sure?" problem from the second lesson this class: asking a model to grade its own work in the same context that produced it is asking it to check its own blind spot with the exact reasoning that created it. A subagent with a fresh context literally cannot see the doer's prior reasoning, which means it can't inherit the doer's blind spots. A verifier subagent isn't a politer way of asking "are you sure." It's a structurally different question, asked by something that never saw the original answer being produced.
A hook is a shell command that fires automatically at a defined lifecycle event, and the word "automatically" is doing real work in that sentence: a hook is not a model decision at all. It's a guarantee the harness enforces regardless of what the model requests or decides. When something must always happen, blocking writes to a read-only data directory, logging every command that runs, no matter what, that guarantee belongs in a hook, never in a request phrased politely to the model and hoped for.
Notice the real dimension running through these five roles, because it's the actual design discipline, not the five labels themselves. Some behavior is model-decided: a skill loads because the model recognized a matching task. Some behavior is human-triggered: a command runs because a person explicitly invoked it. And some behavior is guaranteed: a hook fires because the harness enforces it, with no room for the model to skip it even if it wanted to. Choosing correctly among these three, deciding whether a given piece of behavior belongs to the model's judgment, a human's explicit action, or an unconditional guarantee, is what harness engineering actually is. The organizing principle worth carrying forward from this whole lesson: never entrust a guarantee to a probability. If something must always happen, it goes in a hook. If it should happen only when a human decides it should, it's a command. Everything else, the model's own judgment about when a procedure applies, is a skill.
CLAUDE.md discipline: what earns a line, what doesn't
CLAUDE.md deserves its own closer look, because it's the single most commonly misused piece of this whole architecture. The most common real-world mistake with Claude Code isn't a missing feature. It's a bloated CLAUDE.md, written by someone treating it as project documentation rather than as standing orders that bill every session.
| Doesn't earn a line | Where it actually belongs |
|---|---|
| Pasted API docs and tutorials | A skill, loaded only when relevant |
| "Be helpful and accurate" | Nowhere; costs tokens, changes nothing |
| Task-specific instructions | The prompt for that specific task |
| Prose paragraphs of nuance | Nowhere; unenforceable and unverifiable, so it's dead weight even when true |
| Secrets and credentials | Never in a file at all; a deny-list plus environment variables |
Every line in that left column dilutes every other line, in every single session, because CLAUDE.md is paid for in full regardless of whether the current task needs it. The right column is a real home for real material, which is the important part: nothing on the left column is being discarded as worthless, it's being routed to the place where its cost is actually proportional to how often it's used.
What does earn a line looks different, and it's worth seeing an actual example rather than a description of one. Here's what a real, working CLAUDE.md for a small consulting firm actually contains.
Where things live, where output goes. Enough for a fresh session to orient in one read.
Rules that are always true, no exceptions: "never modify data/," "MXN unless stated otherwise."
"Match on IDs, never on names." This reads like an arbitrary rule until you learn it exists because someone got burned by a name-matching join once, and wrote the lesson down so it never happens twice.
Every number that ships has to come with proof, the same evidence requirement from the five-part brief, now a standing rule instead of something re-typed per task.
What to do when instructions are contradictory or a file can't be read: flag it and stop, rather than guessing and proceeding.
@docs/style-guide.md and similar, which pull in detail from elsewhere without bloating the file that's loaded into every session.
What changes when the handbook disappears
The clearest way to see that all of this is real mechanism and not decoration is to remove it and watch what happens. Take a working project, rename CLAUDE.md away entirely, clear the session, and re-run yesterday's exact same one-line prompt: "reconcile the invoices against the bank deposits."
The model is identical. The prompt is identical, character for character. What's different is that the organization is gone, and the output tends to show it right away.
Matching drifts toward client names instead of invoice IDs, because the rule that used to prevent that was never loaded. The report might land somewhere other than the expected path, because nothing specified it. Evidence and control totals might be thin or absent, because nothing required them. Restore the file, clear again, and the same prompt produces a properly organized result. Nothing about the model changed between the two runs. The organization did, and the organization was never inside the model to begin with. It was a file that either got loaded or didn't.
That same project, briefed the long way in the previous lesson's five-part style, compresses down to something much smaller once the procedure becomes a real skill: typing /reconcile 2026-06 triggers a command, which injects a prompt template, which the model recognizes as matching the reconciliation skill, which loads the full procedure, plans, and asks for approval before executing. Seven keystrokes now do what used to require typing out a full paragraph by hand, every time. That's not a shortcut in the trivial sense. It's practice converted into a durable asset: the exact wording that used to live in someone's head, or get retyped imperfectly each time, now lives in a file that produces the identical, correct brief every single time it's invoked.
And once a report exists, the question isn't whether to trust it. It's whether it can be verified. Asking a verifier subagent to check a completed reconciliation report is not a fancier version of "are you sure." It's structurally different, for the reason established earlier in this lesson: the verifier spins up with its own fresh context, recomputes from the raw source data independently, and returns a verdict without ever having seen the reasoning that produced the report in the first place. Sometimes it confirms the report is correct. Sometimes it catches something the original run missed, a discrepancy in a specific row, a control total that doesn't quite close. Either outcome is the isolation doing real epistemic work, not theater: a checker that shares no history with the doer can't be talked into agreeing with a mistake it never participated in making.
What goes where: the design table
Pull the whole lesson together into one table, because this is the actual discipline worth carrying forward, more than any individual role's definition.
| Knowledge | Home | Why there |
|---|---|---|
| Always-true rules, project map | CLAUDE.md | Paid in every session, so it stays constitution-grade only |
| Procedure for a recurring task | Skill | Loaded only on a match, so detail sits nearly free until used |
| Human-triggered entry point with arguments | Command | A button, pairs naturally with a skill it invokes |
| A role needing isolation, a checker or a researcher | Subagent | Its own window, its own tools, no contamination in either direction |
| Something that must always happen | Hook | Deterministic; never entrust a guarantee to a probability |
| What the agent may touch at all | .claude/settings.json | Allow and deny rules per tool and pattern, the permission perimeter from the previous lesson |
The bottom two rows differ from the top four in kind, not just degree. Everything above them is advice offered to a stochastic model, useful but not absolute. Hooks and permission settings are guarantees enforced by a deterministic harness, which is why they're worth treating as a truly separate category rather than just two more entries on the same list. One more note for where this goes later in the course: MCP connectors, plugging in a database, an email system, or an external API, extend the tools term of this same equation. They're a real topic in their own right and get proper treatment in a later week, not rushed into this lesson alongside everything else.
Where this leaves you
You now have the actual architecture this course keeps calling "the organization": a handbook that's always loaded and stays deliberately small, procedures that load only when they match, buttons a human presses on purpose, staff that check work in complete isolation from whoever produced it, and reflexes that guarantee certain things happen no matter what the model decides. None of it lives in a conversation, which means none of it evaporates when a conversation ends.
The next and final lesson in this class turns from architecture to habit: the five working practices that separate someone who occasionally uses these tools well from someone who compounds real advantage from them week over week, plus a look at where the rest of the semester takes this organization next.
Reply here and it goes straight to Rod. Same as replying to one of his emails.
