Claude Architect WorkshopPDFEPUBlearnwithparam.comkaas.team

Foundations, lesson 7

The CLAUDE.md hierarchy

Team rules live in the project and load only where they apply

A new hire opens the shop repository and asks Claude to edit the cart. Claude does not know that money is stored in cents, because that rule sits in one colleague's personal file. The test naming rule loads for every file, even when nobody is writing a test. This is the agent at Lumen Supply, an online electronics shop. You will watch Claude miss the money rule, then fix it with two small files.

I doWatch the failure and its fix.

Claude loads what the project gives it

Claude Code reads memory files before it answers. A file in the project travels with the repository. A file in a person's home folder stays on that person's machine.

A rules file can also name the paths it covers. It then loads only when Claude works with a file that matches.

Memory stacks: the user file loads first, then the project file, then a file in the directory being worked on. The /memory command lists the files that loaded, which is the first check when a rule goes missing.

Memory loads for every file. A path rule loads only for files that match.A filesource or testProject memoryCLAUDE.mdPath ruleonly for test filesClaudereads what loadeduser config is personal, so a colleague never loads itMemory loads for every file. A path rule loads only for files that match.A filesource or testProject memoryCLAUDE.mdPath ruleonly for test filesClaudereads what loadeduser config is personal, so a colleague never loads it

The right rules reach the right file

Claude is asked about the test file. It names the money rule from project memory and the test naming rule from the path rule. Both loaded, and nothing else came along.

The recording keeps four fields: result is the reply text, is_error is false, num_turns counts the turns and stop_reason is end_turn. Open the reply card to read result in full.

  1. New hireRead src/cart.test.ts. Then list, one short line each, the team conventions that apply…
    Show the result
    Read src/cart.test.ts. Then list, one short line each, the team conventions that apply when editing it. Do not edit anything.
  2. Claude namesthe money rule and the test naming rule
  3. Claude- Money in cents: store amounts as integer cents, never floats (CLAUDE.md). - Display format: show money as integer cents…
    Show the result
    - Money in cents: store amounts as integer cents, never floats (CLAUDE.md).
- Display format: show money as integer cents with two decimals (docs/style.md, pulled in by CLAUDE.md).
- Test names: start each test name with "should" (.claude/rules/tests.md). The current test, "adds the prices", doesn't follow this.
- One assertion per test: each test gets exactly one expect (.claude/rules/tests.md).
- Run tests before finishing: run the test suite before wrapping up any change (CLAUDE.md).

Claude named the rules that apply, no more.

Two files as written

Project memory is CLAUDE.md at the root of the repository. The starting file is an empty stub, so no team rule reaches a new hire. The rules folder, .claude/rules/ in a real project, holds tests.md, and the starting copy has no paths line, so it loads for every file.

That costs real tokens. Say the test rule is 300 tokens and Claude edits 200 source files. The rule rides along on each one, which is at least 60,000 tokens those requests never use.

starter/CLAUDE.md
1# Lumen shop23TODO(workshop): add the team rules and import the style guide.

What does Claude know about a source file?

Take the question "What conventions apply when editing src/cart.ts?" The money rule lives only in a colleague's personal file. The test naming rule sits in a rules file with no paths line.

Predict: What does Claude list for the source file?

  1. AThe money rule, because the team agreed on it.
  2. BThe test naming rule, and no money rule.
Show the answer

B. The personal file never reaches this repository. The test rule has no path limit, so it loads for the source file too.

Claude gets the wrong rules

This is the same question with the starting files. The reply names the test naming rule for a file that has no tests, and it does not name the money rule. The result card is red.

This is a real Claude Haiku 5.5 run through claude -p, recorded once and replayed here.

  1. New hireRead src/cart.ts. Then list, one short line each, the team conventions that apply when…
    Show the result
    Read src/cart.ts. Then list, one short line each, the team conventions that apply when editing it. Do not edit anything.
  2. Claude namesthe money rule and the test naming rule
  3. ClaudeConventions that apply when editing src/cart.ts: - docs/style.md: money is stored as integer cents and shown with two…
    Show the result
    Conventions that apply when editing src/cart.ts:

- docs/style.md: money is stored as integer cents and shown with two decimals. total() doesn't state its unit, so keep prices in cents.
- CLAUDE.md: the team rules section is still a TODO(workshop) placeholder, so there are no team rules yet.
- .claude/rules/tests.md: test names start with "should" and each test has one assertion. This governs src/cart.test.ts, not cart.ts itself.

The test naming rule loaded for a file it does not fit.

Move the rule in, and scope the other

The team rules go into project memory, and the style guide comes in with one @docs/style.md line. The guide stays in one file. The test rule gets a paths list in its frontmatter, the settings block between two --- lines at the top of the file. The list matches **/*.test.*.

Both files are plain text, and a colleague gets them with a clone. One glob covers tests in any number of folders, where a CLAUDE.md in each folder would need one file per folder. A long file is better split by topic into the rules folder.

What a new hire's Claude loads before it answers.New hireClaudeProjectRulesquestionload memoryload test ruleconventions
CLAUDE.mdgreen lines are what the fix adds
1# Lumen shop23Team rules for every file in this repository.45Money is stored in cents, never as a float.67@docs/style.md89Run the tests before you finish a change.
We doChange one setting at a time and predict.

The same question now has the right answer

Use the switch to run the question with the rule in a colleague's user file, then in project memory. The card marked "This is where the runs split" shows which rules Claude named.

With the rule in project memory, the source file reply names the money rule and the reminder to run the tests, and the test naming rule stays out.

This part is interactive in the lab: run ./workshop watch claude-md-hierarchy.

Commands and skills follow the same folders

The switch below is the memory switch again: a colleague's user folder never reaches the new hire, and the project does. A command is one markdown file run by its name, such as /review, and where it lives decides who gets it.

Folder Who gets it
.claude/commands/ in the repository everyone who clones it
~/.claude/commands/ in a home folder only that person

A command file and a skill take the same frontmatter. A skill is a SKILL.md with its own directory, so it can also carry files, and Claude can pick it by its description.

The setting context: fork gives the skill its own fresh context, and only its summary comes back to the main conversation. The list allowed-tools pre-approves tools, and argument-hint shows what to type after the name.

This part is interactive in the lab: run ./workshop watch claude-md-hierarchy.

Try it: memory and path rules

Change one setting at a time. Pick the source file or the test file, then move the money rule and the test rule. A rule in a colleague's user file never reaches the new hire, and a test rule with no paths line leaks into the source file.

Every combination is a recorded run, so this works with no internet. Eight recordings cover every cell.

This part is interactive in the lab: run ./workshop watch claude-md-hierarchy.

The same files run in Claude Code

The harness copies your CLAUDE.md and rules folder into a sandbox project and runs claude -p --output-format json there. Replay needs nothing installed. A live run needs the claude command-line tool, signed in.

Only project files load, so a rule in a colleague's user file never reaches the run. The reply for the source file names the money rule and leaves the test rule out. A CLAUDE.md inside a subfolder loads too, when Claude works on a file there. This is a real Claude Haiku 5.5 run.

app/agent.pyfile: 92 lines
···67 lines not shown6869 @property70 def right(self) -> bool:71 """Whether the reply names what applies and nothing else."""72 return not self.missing and not self.leaked737475def run(ticket: Ticket, memory: Path, rules: Path, llm: Run) -> Handled:76 """Ask about one file with `memory` and `rules` as the project's files."""77 request = cli.build_request(78 ticket.text,79 f"lumen-shop:{fingerprint(memory, rules)}",80 allowed_tools=["Read"],81 )82 with tempfile.TemporaryDirectory() as tmp:83 result = llm(request, sandbox=build_sandbox(memory, rules, Path(tmp)))8485 text = result["result"]86 handled = Handled(ticket, text, [])87 handled.events = [88 {"kind": "ask", "file": ticket.file},89 *({"kind": "named", "rule": RULES[p]} for p in handled.named),90 ]9192 return handled
  1. New hireRead src/cart.ts. Then list, one short line each, the team conventions that apply when…
    Show the result
    Read src/cart.ts. Then list, one short line each, the team conventions that apply when editing it. Do not edit anything.
  2. Claude namesthe money rule
  3. Claude- Money is stored in integer cents, never as a float. total() takes number[] with no unit stated, so confirm the inputs…
    Show the result
    - Money is stored in integer cents, never as a float. total() takes number[] with no unit stated, so confirm the inputs are cents.
- Money is shown with two decimals, per docs/style.md. This applies to display code, not to total()'s return value.
- Run the tests before finishing any change. I didn't run them because nothing was edited.

Claude named the rules that apply, no more.

You doFix the starting code, then test yourself.

You do: write the memory files

Copy the starting files and open work/claude-md-hierarchy/CLAUDE.md. It holds a TODO in place of the team rules. Add the rules, import the style guide and say how to run the tests. Then give rules/tests.md a paths block.

Terminal
./workshop start claude-md-hierarchy
./workshop check claude-md-hierarchy
./workshop watch claude-md-hierarchy

The checks want no TODO, an @docs/style.md import and a test command in project memory. The test rule must load only for test files and stay out of CLAUDE.md.

Check your understanding

Answer each question, then read why every option is right or wrong. The wrong options are the mistakes engineers make on the job.

On the exam, "new team member", "consistently" and "only for test files" point to project memory and path rules. "Put it in the user config" is the wrong answer for a team rule.

1. A new hire's Claude writes prices as 12.99 floats. The team stores money in cents, and that rule sits in a colleague's personal Claude file. Two earlier hires hit the same problem. What is the best fix?

  1. ALeave it in the personal file, because user memory is shared with anyone who opens the same repository.
  2. BMove the rule into the project CLAUDE.md so it is committed and loaded for every clone.
  3. CAsk each hire to start their first prompt with a reminder that money is stored in cents.
  4. DHave the colleague sit with each new hire during the first week and correct their sessions.
Show the answer

Answer: B

  • A User memory lives in one person's home folder. It never travels with the repository, so nobody else loads it.
  • B Correct. A file committed at the project root goes wherever the repository goes, so every teammate loads the same rule.
  • C This treats the symptom on one session at a time. The next hire has to be told again.
  • D A person correcting sessions does not change what Claude loads, and it does not scale to the next hire.

2. A 900-line CLAUDE.md mixes API, test and deploy rules. Engineers cannot tell which rule applies to which work, and every session loads all 900 lines. What is the best fix?

  1. AKeep one file so every rule is in one place, and add a table of contents at the top.
  2. BMove each topic into the user memory of the engineer who owns that topic.
  3. CDelete the oldest rules until the file is 300 lines, whatever they cover.
  4. DSplit it by topic into separate files in the project's rules folder.
Show the answer

Answer: D

  • A A table of contents helps a reader, but Claude still loads all 900 lines and the topics stay mixed.
  • B Owners' personal files never reach the team, so their rules disappear for everyone else.
  • C Age says nothing about whether a rule still matters, so this deletes rules that may be needed.
  • D Correct. One file per topic makes each rule easy to find, and the files live in the repository.

3. A monorepo has a payments package with a 40-line money guide and a docs package with a 10-line writing guide. Both guides are pasted into every CLAUDE.md, so each session carries 50 lines. What is the best fix?

  1. AKeep each guide in one file and import only the one each package needs with an @ line.
  2. BMerge both guides into one 50-line guide at the root and delete the two originals.
  3. CPut the payments guide in the user memory of the people on the payments team.
  4. DWrite a hook that removes the other package's guide at the start of each session.
Show the answer

Answer: A

  • A Correct. An import pulls the file in where it is named, so each package loads its own guide and there is one copy to edit.
  • B A merged guide puts all 50 lines in front of every session, which is the cost you started with.
  • C User memory does not travel with the repository, so a teammate outside that team misses the guide.
  • D A hook adds a moving part to undo what the files already decide. Importing only what is needed costs nothing.

4. Which two statements about memory files are true? Select two.

  1. AAn import line copies the guide's text into the file once, so later edits to the guide do not reach it.
  2. BA user-level file in a home folder stays on that machine and never travels with the repository.
  3. CA user-level file is shared with teammates through the repository, like a project file.
  4. DUser, project and folder memory files layer, and all the ones that apply load together.
Show the answer

Answer: B, D

  • A An import is read when memory loads, so the guide is pulled in fresh and stays one copy.
  • B Correct. Only files inside the project are committed, so a home folder file is personal.
  • C A home folder file is not in the repository, so a clone does not carry it.
  • D Correct. The layers add up, and the closest file covers the work Claude is doing.

5. A test naming rule of 300 tokens sits in project memory. It loads for each of the 200 source files Claude edits, about 60,000 tokens of text those edits never use. What is the best fix?

  1. AShorten the rule to 150 tokens and keep it in project memory.
  2. BMove the rule into each author's user memory so source edits skip it.
  3. CPut the rule in a rules file with a paths list that matches only test files.
  4. DAdd a hook that removes the rule whenever Claude opens a source file.
Show the answer

Answer: C

  • A A shorter rule still loads for every file, and it may be too short to help.
  • B A personal file hides the rule from the rest of the team, including the people who write tests.
  • C Correct. A paths glob loads the rule only when Claude works with a matching file.
  • D Path matching is built in. A hook adds code to do what one line of frontmatter does.

6. Tests sit in 14 folders, and one naming rule covers all of them. A teammate proposes a CLAUDE.md in each folder. What is the better fix?

  1. AOne rules file whose paths list holds a glob such as **/*.test.*.
  2. BFourteen folder files, each holding a copy of the rule.
  3. COne folder file in the first test folder, which covers the other 13 folders.
  4. DOne rules file plus a hook that loads it when a test file is opened.
Show the answer

Answer: A

  • A Correct. One glob matches test files in every folder, so there is a single file to keep current.
  • B Fourteen copies drift apart the first time someone edits one and forgets the rest.
  • C A file in a directory loads for work in that directory and below. It does not reach sibling directories.
  • D The glob already does the matching, so the hook is an extra step with nothing to add.

7. A terraform rule of 3,000 tokens loads on every request, but only 5 in 100 requests touch a .tf file. What is the best fix?

  1. ATurn it into a skill that Claude must call before each edit to any file.
  2. BCut it to the 10 most important lines and keep it in project memory.
  3. CMove it to the user memory of the platform team so other requests skip it.
  4. DScope the rule with a paths glob that matches .tf files, so it loads only for them.
Show the answer

Answer: D

  • A A skill Claude must call before each edit adds a step to all 100 requests instead of removing the cost.
  • B A shorter rule still loads on every request, and cutting it may drop rules that matter for terraform.
  • C A personal file leaves other teammates without the rule when they edit terraform.
  • D Correct. The rule now loads for the 5 requests that need it and costs nothing on the other 95.

8. Which two effects follow from adding a paths list to a rule file? Select two.

  1. AThe rule loads only when Claude works with a file that matches the glob.
  2. BThe rule becomes personal and is left out of the repository.
  3. CRequests that touch other files skip the rule's tokens.
  4. DA hook must also be added before the match takes effect.
Show the answer

Answer: A, C

  • A Correct. The match on a file's path is what switches the rule on.
  • B The file stays in the project's rules folder and travels with the repository.
  • C Correct. A rule that does not load costs no tokens, so work on other files is cheaper.
  • D The match is built into how rules load, and no hook is involved.

9. A team pastes the same 12-line review prompt by hand each week, and five teammates now hold five versions. Where should the shared prompt live?

  1. AOn a wiki page that each teammate copies from before a review.
  2. BIn a file in the project's commands folder, committed to the repository.
  3. CIn each teammate's user commands folder, kept in step through a chat message.
  4. DIn the project CLAUDE.md as a paragraph that loads on every session.
Show the answer

Answer: B

  • A Claude cannot run a wiki page, and each copy drifts as soon as someone edits their own.
  • B Correct. A committed command is one file that everyone who clones the repository can run by name.
  • C Home folders are not shared, so the versions drift again and new hires have none.
  • D A paragraph in memory loads on every session, even when nobody is reviewing anything.

10. A developer keeps a personal review shortcut that calls their own scripts. It should not reach the other 30 people on the team. Where should it live?

  1. AIn the project's commands folder, with a note asking the team not to call it.
  2. BIn the project CLAUDE.md, written as a paragraph only they are expected to use.
  3. CIn the commands folder of their own home directory.
  4. DIn a project skill, because skills are the personal version of commands.
Show the answer

Answer: C

  • A The file would still be cloned by all 30 people, and a note does not stop it from showing up.
  • B Everything in project memory loads for every teammate.
  • C Correct. A user-level command stays on that machine and is never committed.
  • D A skill is also shared when it sits in the project. Where the skill lives decides who gets it, not the file type.

11. A review skill prints a 4,000-line diff summary into the main session, about 48,000 tokens. What keeps that work out of the main session?

  1. ASetting context to fork in the skill's frontmatter, so the skill runs apart.
  2. BWriting a longer description so Claude picks the skill more carefully.
  3. CSetting allowed-tools to Read so the skill can open fewer files.
  4. DSaving it as a command instead, since commands run apart from the session.
Show the answer

Answer: A

  • A Correct. A forked skill runs in its own context and returns only a summary to the main session.
  • B The description helps Claude choose the skill. It does not change where the work is done.
  • C A tool limit decides what the skill may use. What it reads still lands in the session.
  • D A command runs in the main session too. Only a fork moves the work apart.

12. Which two settings can a skill's frontmatter hold? Select two.

  1. AA share key that publishes the skill to every teammate.
  2. BAn allowed-tools list that pre-approves tools while the skill runs.
  3. CA memory key that rewrites CLAUDE.md each time the skill runs.
  4. DAn argument-hint that shows a person what to type after the name.
Show the answer

Answer: B, D

  • A There is no share key. The location of the skill decides who gets it.
  • B Correct. The listed tools run without a permission prompt while the skill is active.
  • C There is no memory key, and a skill does not rewrite memory files by itself.
  • D Correct. The hint labels the argument, for example a path to a diff, for the person typing.

Play: predict the output

A teammate wrapped the import in backticks so it reads like a path.

markdown
# Lumen shop

Money is stored in cents, never as a float.

Follow the style guide in `@docs/style.md`.

Predict: Does the style guide load into the session?

  1. AYes. The import line is still in project memory.
  2. BNo. Imports inside a code span are skipped, so the path stays plain text.
Show the answer

B. Claude Code reads an @ import only outside code spans and code blocks. Write @docs/style.md on its own line with no backticks, and keep backticks for a path you only mention.

References

Conclusions

  • Rules the whole team needs belong in project memory, so they travel with the repository.
  • A paths list loads a rule only for the files it fits.
  • A shared command belongs in the project, and a personal one stays in the home folder.

You can now place a rule where the right people and the right files will load it.

Project memory

CLAUDE.md in the repository, loaded for everyone who clones it

User memory

A file in a person's home folder that only that person loads

Import

An @ line that pulls another file into memory

Path rule

A rules file with paths that loads only for matching files