Context Engineering

1 · Context is the unit of engineering

Start with the thing that surprises everyone. Claude does not remember your project. Not between sessions, and past a certain size not even within one. Every time you open Claude Code, it wakes up knowing nothing about your repo, your client, or the conversation you had yesterday. Everything it "knows" during a session is text that got loaded into a working area called the context window.

Think of the context window as a briefcase. It has a fixed size. Every file, every instruction, every search result you put in leaves less room for everything else, and when the briefcase is full, something has to come out. So the real question behind this whole module is a packing question: what goes in the briefcase, when does it go in, and what stays on the shelf until it is needed?

A literal example. Picture a consulting team's client engagement repo. When a consultant types claude inside it and the session immediately knows the engagement rules, the client's terminology, and the required writing style, that is happening for exactly one reason: the repo's CLAUDE.md file got loaded into the briefcase at startup. Claude did not remember any of it. Delete that file and the next session knows none of those things.

Here is what actually gets packed, and when:

Notice the two groups. The top three load at the start of every single session, whether the task needs them or not. That makes them a tax. If your CLAUDE.md runs 2,000 lines, you pay for all 2,000 when you ask Claude to fix a typo. And there is a second, sneakier cost: the longer an instruction file gets, the more of it gets skimmed. Anyone who has written a 40 page employee handbook knows how many of those pages get followed. Instruction files work the same way.

The bottom three cost almost nothing until the moment they matter. A skill carrying 200 lines of instructions costs one line of description until someone actually uses it. A rule file inside the api/ folder costs nothing at all until Claude opens a file in api/.

2 · The CLAUDE.md hierarchy (TS 3.1)

▶ Watch: how the CLAUDE.md chain loads · 90 sec

A CLAUDE.md file is just a markdown file full of instructions, written in plain English. What makes the system interesting is that Claude Code looks for these files in several places and loads them in a specific order. Think of the rules that apply to you at work: law, then company policy, then your department's norms, then your own habits. Each layer adds detail, and the layers above outrank the layers below.

The project file is a team contract

The "who controls it" column matters more than it looks. The project level file is committed to git, and that one fact changes its whole character. Committed means every teammate who clones the repo gets it, and their Claude follows it in every one of their sessions. Whatever you write in that file, you are writing into every teammate's sessions, forever, whether they know it or not. That makes the project CLAUDE.md a contract between teammates. So sort by audience:

• Rules for everyone ("client docs follow the style guide") belong in the committed CLAUDE.md.
• Preferences about you ("keep answers short") belong in a file only you have: your global ~/.claude/CLAUDE.md, which follows you everywhere, or a CLAUDE.local.md inside the repo that git is told to ignore, so it never reaches anyone else.

Folder rules wait by their own door (TS 3.3)

This is the mechanism the exam calls path specific rules, and it is easiest to see with an example. Say your repo has a deliverables/ folder and the team rule is that every file in it gets named YYYY-MM-DD-clientname.md. You could put that rule in the root CLAUDE.md, where every session pays for it, including the many sessions that never touch a deliverable. Or you could create deliverables/CLAUDE.md with the rule inside. That file sits dormant until the moment Claude opens or creates a file in deliverables/, and then it loads and applies. Rules posted on the door of the room they apply to, instead of piling up in the lobby. The rule of thumb: any instruction that starts with "when working in X" belongs in X/CLAUDE.md. The root never needs to hear about it.

Imports tidy your files, and change nothing about loading

A CLAUDE.md can pull another file into itself with one line:

See @docs/style.md for the writing rules.

The @ means: load that file too, right now, as part of me. This is genuinely useful for keeping the root file organized. Instead of one 800 line monster you get a short root file and a set of tidy topic files. But watch the trap: an imported file loads at the same time as the file that imports it, so importing a 500 line style guide into your root CLAUDE.md costs exactly as much briefcase space as pasting all 500 lines in directly. Keep the two jobs straight:

• Want tidy files? Use an import. Organization on disk, same cost in the briefcase.
• Want content to wait until it is needed? Use a subdirectory file or a skill. Those are the lazy tools.

3 · Anatomy of .claude/

Alongside the CLAUDE.md files, every repo can carry a hidden folder called .claude/. If CLAUDE.md is the instruction manual, .claude/ is the toolbox: the machine readable half of the setup, where capabilities and configuration live. The full layout:

<repo>/
├── CLAUDE.md                  ← shared contract (always loaded)
├── CLAUDE.local.md            ← personal overlay (gitignored)
└── .claude/
    ├── settings.json          ← shared config: permissions, hooks (committed)
    ├── settings.local.json    ← personal overrides (gitignored)
    ├── commands/              ← slash commands: one .md per command → /name
    ├── skills/                ← one folder per skill, with SKILL.md
    ├── agents/                ← subagents: one .md each (frontmatter + prompt)
    └── (hooks are registered in settings.json; there is no hooks/ directory)

Two settings files, one familiar pattern

settings.json is committed and shared. It holds the team's configuration: which commands Claude may run without asking, which files it may never read, which hooks fire. settings.local.json is yours alone and gitignored, for personal overrides. When both set the same option, your local file wins, on the sensible logic that the settings closest to you know your situation best.

The exception at the top

There is an enterprise managed settings file that IT can install at the machine level, outside any repo. Whatever it says cannot be overridden by anything below it. Not by the project settings, not by your local file, not by anything you type. That sounds heavy handed until you consider what it makes possible: a health plan's IT team writes "no Claude session on this laptop may ever read files matching *.pem" once, and it holds for every developer, every repo, every session, with no way around it. The enterprise governance chapter builds its whole story on this one property. The full pecking order, strongest first:

1. Enterprise managed policy (IT installed, unoverridable)
2. Command line flags
3. .claude/settings.local.json (yours, this repo)
4. .claude/settings.json (the team's, committed)
5. ~/.claude/settings.json (your global defaults)

The three capability folders

Each gets its own module later; here is the short version of each, plus the odd one out:

• commands/ holds slash commands: each markdown file becomes a typed shortcut, so review.md becomes /review, a saved prompt you fire by name.
• skills/ holds skills: each is a folder with a SKILL.md inside, carrying a one line description that is always visible and a body of instructions that loads only when used. The case study team in this module has a prep-for-meeting skill of exactly this shape.
• agents/ holds subagents: each markdown file defines a separate worker with its own briefcase, for jobs whose mess you want kept out of your window.
• Hooks get no folder of their own. They are registered inside settings.json, and forgetting that is a classic mistake you will meet again in the quiz.

Where does this thing go?

Every rule and every piece of knowledge you want Claude to have has one best home. This table is the sorting hat. It is worth internalizing early, because every module ahead comes back to it:

4 · Structuring a repo Claude can navigate (TS 5.4, 2.5)

How does Claude actually find things in a repo it has never seen? The same way a sharp new hire would on day one. It searches for promising names using Grep (which searches inside files) and Glob (which searches file names). It opens whatever looks relevant with Read. It follows references from one file to the next, and runs commands with Bash when it needs to. No magic and no prebuilt index. A methodical new hire with a search bar.

Once you picture that new hire, "optimizing a repo for Claude" stops being mysterious. You are designing for a fast reader with zero tribal knowledge:

• Predictable names beat clever names. A folder called deliverables/ gets found on the first search. A folder called The_Goods/ gets found after four wrong turns, and every wrong turn costs briefcase space, because each opened file stays in the window whether or not it helped.
• Put an index file at every major junction. A five line README inside each big folder, saying what lives there and which files matter, turns exploration from ten file reads into one. The case study team's wiki/ layer is this pattern done at full scale, and it is a real asset. When the map is good, the new hire stops opening doors at random.
• Many small files beat one giant file. If the answer lives in one section of a 5,000 line document, Claude still has to load the whole document to reach it. Split it into topic files and it loads just the topic. The modularity you would want for human readers is exactly the modularity the briefcase wants.
• Wall off what must never be read. This one deserves its own paragraph.

Suppose your repo contains data/secrets.txt, and it genuinely must never enter a session. You have two very different tools. The first is writing "never read data/secrets.txt" in CLAUDE.md. That is a written request to Claude, and Claude will honor it almost every time. Almost. Instructions compete for attention with everything else in a busy window, and "almost every time" is a terrible guarantee for a secrets file. The second tool is a permissions.deny rule in settings.json:

{ "permissions": { "deny": [ "Read(data/secrets.txt)" ] } }

This works differently under the hood. When any session tries to open that file, the request is refused by the Claude Code software itself, before the model gets any say in the matter. It is the difference between a sign on a door that says "staff only" and a door that is locked. The sign works on almost everyone. The lock works on everyone. For preferences and conventions, signs are fine and appropriate. For secrets, client data, and anything with real consequences, install the lock.

5 · Case study: a team's second brain

The setup

Time to apply everything above to a real setup, anonymized. Five consultants are running an AI governance engagement at a regional health plan. Eighteen months of engagement history, dozens of stakeholders, three parallel workstreams. Early on, someone had a good idea: one shared repo as the team's second brain. Engagement context and deliverable drafts. Meeting summaries that get filed automatically. A glossary of the client's hundred abbreviations, and a style guide for how the practice writes. Every consultant runs Claude Code against this same repo, so whatever one person adds becomes context for everyone's sessions the next morning.

This is the pattern you will meet, or build, on almost any serious engagement. And this particular team is worth studying closely, because they got the hard part right and the easy part wrong, and both halves teach.

What they got right: the part most teams never build

• A strong root CLAUDE.md that orients every session to the engagement: what the client does, what the deliverables are, how to talk. A new session knows the account in its first second.
• A wiki/ index layer at the repo's junctions, so sessions find the right file on the first search instead of the fourth. Exactly the index file advice this module teaches, already implemented at full scale.
• LEXICON, GLOSSARY, and STYLE files that pin down shared vocabulary and writing rules. Exactly the kind of team contract the project level exists to hold.

Whoever set this up understood that Claude reads a repo like a new hire, and built the new hire a map.

What went wrong: one detail of placement

Over a few months the team wrote 23 skills: meeting prep, deck formatting, document transcription, weekly syncs. Genuinely good ones. But they put them in a folder called skills/ at the top of the repo, and Claude Code only auto discovers skills in .claude/skills/. One path difference, and here is everything that silently followed from it:

• None of the 23 load as skills. Their descriptions never appear in any session's menu.
• Ask a fresh session "what skills do you have here?" and the honest answer is: none.
• The authors never noticed, because a person who already knows a skill exists can point Claude at the file by hand. From the inside, everything seemed fine.
• New joiners got nothing. The team's accumulated craft was invisible to exactly the people who needed it most.

The fix is one ask: "move the skills folder into the .claude folder so the skills get discovered." Claude does it with a single move command that even preserves the files' history. Finding this kind of gap is precisely what this module trains you to do, and the story continues in the next module's case study: an audit of what those 23 actually contained.

The risk they had not thought about yet

The repo has no hooks, no shared settings.json policy, and no locked doors. Play out what that means with five people sharing one brain:

• A Monday session decides to "tidy up" and rewrites CLAUDE.md. On Tuesday, every consultant's Claude follows the rewritten rules, and nobody reviewed the change.
• Nothing scans anyone's file writes. Nothing blocks a destructive command. Nothing records what changed.
• The only thing protecting the team contract is good manners.

That is not a reason to avoid shared repos. It is the reason Modules 03 and 09 exist, where the guardrails get built.

6 · Demo: watch it built, then build yours

▶ Watch the demo: setting up a Claude ready repo · 3 min

The prompt pack: every demo prompt, cleaned and explained

The demo shows this entire module implemented from the user's chair. A consultant on a healthcare engagement starts with an empty folder, opens Claude Code in the terminal, and gives plain language instructions while Claude does the building. You watch every mechanism from this chapter go in, with the actual file contents on screen: the root CLAUDE.md written short and real, the @import of a style file, folder level rule files in deliverables/ and data/, the gitignored personal overlay, the .claude/ scaffold with both settings files and the empty commands, skills, and agents folders, the deny rule locking a secrets file, where the enterprise and user level files sit, and README maps at the junctions. Then the payoff: a brand new session gets opened and tested, and you watch the conventions answer come back, the naming rule apply itself unprompted, and the locked file refuse to open.

Then build yours. No special setup needed: make a folder anywhere on your machine, open Claude Code inside it, and work through the prompt pack linked above, copied as is or rephrased in your own words. Every prompt in the pack explains what it builds and what you should see when it lands. This repo is the start of your own second brain, and every module from here adds a layer to it.

When your version is built, prove it works the same way the demo did. Open a fresh session (fresh matters, because you are testing what loads at startup, with no help from conversation memory) and check:

• Ask "what are this project's conventions?" The answer should reflect your root CLAUDE.md and the imported style file.
• Ask for a new file in your rules folder. The naming rule should be applied without you mentioning it. That silence is the proof that the subdirectory file loaded on its own.
• Ask Claude to read your dummy secrets file. The deny rule should block it. You are watching the locked door work, live.
• Ask Claude to edit something you declared read only. It should push back and cite the rule.
• Ask "what skills and commands do you have here?" It should correctly report the empty scaffold, which proves discovery is looking in the right place.

If a check fails, good. Figure out which layer should have caught it, fix that layer, and run the check again. Fixing the symptom instead of the layer is how repos rot. Keep this practice repo around: the next module's prompt pack builds your first skill and command inside it.

7 · Wrap-up: what you should be able to do cold

• Name the memory file levels and their precedence, and say which load at startup and which wait
• Decide in seconds whether an instruction belongs in the user, project, subdirectory, or local overlay file
• Explain progressive disclosure to a teammate using the briefcase, then show them a real SKILL.md
• Explain the two settings files, and why the unoverridable enterprise layer is a feature
• Sketch the .claude/ anatomy from memory
• Diagnose the case study's skills/ misplacement and say precisely what breaks, and for whom

Readings

The official docs are the source of truth for everything in this chapter: the Claude Code documentation pages on Memory, Settings, and Permissions (code.claude.com/docs), plus the Anthropic engineering post Claude Code Best Practices.

Take the Module 01 quiz →  then hit the Study App for Domain 3 reps.