Where Does a Team Convention Live? Project CLAUDE.md Explained

July 24, 2026 · Claude Certified Architect (CCA) Prep (part 24)

▶ Watch on YouTube & subscribe to The Stack Underflow

Your team just agreed, out loud, in a standup: all new API endpoints get a Zod schema before the handler is written. Two days later, half the pull requests still skip it. The rule lived in someone’s memory, in a Slack thread that scrolled away, in a comment on one PR — everywhere except somewhere Claude Code actually reads before it starts writing code for the next person on the team. This is a memory-hierarchy problem, and it is one of the most practically useful things Domain 3 of the Claude Certified Architect exam tests.

The one-sentence version: A convention that must reach the whole team lives in the project’s CLAUDE.md, committed to the repo — because project memory is shared with everyone who clones it, while user memory is scoped to you alone.

The question

A coding convention must apply to your whole team on one repo. Where do you put it?

• A) Your user memory ~/.claude/CLAUDE.md
• B) The project CLAUDE.md committed to the repo
• C) A one-off chat message
• D) A comment in the code

Pause here and pick an answer before you keep scrolling.

The answer

The answer is B — the project CLAUDE.md, committed to the repo.

The mechanism is the Claude Code memory hierarchy. Claude Code doesn’t have one place it “remembers” things — it has several, distinguished by scope: who gets to see this, and where does it travel. The two scopes that matter for this question sit at opposite ends of that scope axis:

MEMORY HIERARCHY (scope = who inherits it)

  ENTERPRISE / MANAGED POLICY
  (org-wide, IT-deployed — out of scope for this question)
        │
        ▼
  PROJECT  ./CLAUDE.md                  ← shared, committed to the repo
  "Read this file before doing anything      Every teammate who clones the
   in this codebase."                        repo loads the same rules.
        │
        ▼
  USER  ~/.claude/CLAUDE.md             ← personal, lives on your machine
  "Read this no matter which                 Never seen by teammates.
   project I'm working in."                  Doesn't ship with any repo.

CLAUDE.md is context that Claude Code loads automatically at the start of a session — it’s not a prompt you type, it’s a file the harness reads for you, every time, before you say a word. The file’s location is what decides its audience:

A team convention — “all new endpoints get a Zod schema” — needs to reach every teammate the moment they open the repo, regardless of whose laptop they’re on. Only the project-scoped file, committed alongside the code it governs, does that. Put it in ./CLAUDE.md, commit it, and the rule ships with the codebase the same way a .eslintrc or a package.json does — as a durable artifact of the repo, not a fact that lives in someone’s head or a chat log.

Why the other options fail

• A) User memory ~/.claude/CLAUDE.md is the trap that looks almost right. It genuinely is “memory that Claude Code reads automatically” — but it is scoped to you, on your machine, across every project you touch. It never gets committed, never ships with the repo, and a teammate cloning the project will never see a single line of it. This is the correct answer to a different question — “a rule that should follow you personally across projects” — which is exactly what Q2 in this same practice set asks about.
• C) A one-off chat message has zero persistence. It applies to the current conversation and evaporates the moment the session ends or context gets compacted. It reaches nobody who wasn’t in that exact chat, including future-you next week.
• D) A comment in the code is scoped to a single file, not the whole team’s practice. It also isn’t read as instructions — Claude Code doesn’t scan every code comment in a repo as governing context the way it loads CLAUDE.md at session start. A comment might explain what one function does; it can’t establish “always do X for new endpoints” as a repo-wide norm Claude reliably picks up before writing new code.

The concept behind it

Zoom out past this one question and the pattern generalizes: every configuration surface in Claude Code — memory, settings, permissions — has a scope, and scope is the variable that answers “who does this apply to” and “who wins when two files disagree.” The exam tests this same shape of question repeatedly across Domain 3, just with different nouns:

SCOPE AXIS (narrow → wide, top overrides bottom in a conflict)

  ENTERPRISE / MANAGED POLICY   (org-wide, IT-controlled)
  COMMAND-LINE FLAGS            (this invocation only)
  LOCAL PROJECT                 (.claude/settings.local.json — you, this repo, gitignored)
  SHARED PROJECT                (.claude/settings.json or CLAUDE.md — the team, this repo)
  USER                          (~/.claude/CLAUDE.md — you, every repo)

Three practical habits fall out of understanding scope rather than memorizing file names:

1. Ask “who needs this?” before “where do I put this?” If the answer is “everyone who works on this repo,” it belongs in something committed at the project level. If the answer is “just me, everywhere,” it belongs in your user-level config. If the answer is “just me, on this one repo, and I don’t want it in git” — that’s a third scope, settings.local.json, covered by its own question in this series.
2. CLAUDE.md is remembered context, not enforced behavior. Even a project-level CLAUDE.md is advisory — it’s a strong instruction the model reads and generally follows, but nothing stops a large or noisy context window from causing it to drift. If a rule must run deterministically every single time regardless of what the model “decides,” that’s a job for a hook, not a memory file — a distinction worth its own careful read.
3. Files that ship with the repo are load-bearing infrastructure. Treat a project CLAUDE.md the way you’d treat a linter config: version it, review changes to it in PRs, and keep it current as the codebase’s conventions evolve. A stale CLAUDE.md that contradicts the actual codebase is worse than no CLAUDE.md at all, because it actively misleads every session that reads it.

This is also the exam’s broader Domain 3 theme: nearly every “where does X live” question is really a scope question wearing a different hat, whether X is a memory file, a settings key, a slash command, or a permission rule.

FAQ

Can a repo have more than one CLAUDE.md? Yes — Claude Code supports nested CLAUDE.md files in subdirectories, which layer on top of the root file for context specific to that part of the codebase (a frontend/CLAUDE.md alongside a root CLAUDE.md, for example). The scope principle still holds: whatever you commit, everyone who touches that directory inherits.

What happens if the project CLAUDE.md and my user CLAUDE.md say different things? Both get loaded as context — they aren’t mutually exclusive the way a permission conflict is. In practice you write your user-level file to cover personal habits that don’t contradict team conventions (verify the exact merge behavior in the current docs, since this is exactly the kind of detail Domain 3 flags as fast-moving).

Is CLAUDE.md the same thing as a system prompt? Functionally similar in effect — both are context the model sees before responding — but CLAUDE.md is a file you and your team maintain and version like any other repo artifact, loaded automatically by the harness, rather than something set once in an API call.

Should every rule go in CLAUDE.md, or are some things better as hooks? If it’s guidance the model should understand and reason about (“we prefer composition over inheritance here”), CLAUDE.md is right. If it’s an action that must happen every time, no exceptions (“run the linter after every edit”), that’s a hook’s job — memory is advisory, hooks are enforcement.

Where this fits in the CCA series

This is Q1 of the Domain 3 practice set — Claude Code Configuration & Workflows, roughly 20% of the exam as of mid-2026 (verify current weighting on Anthropic’s official pages). If memory hierarchy clicked here, the natural next stop is the companion question on the other end of the scope axis: A Rule for You, Not Your Team: Local vs Shared Claude Code Settings. From there, Instructions or a Hook — Which Runs Every Time? CLAUDE.md vs Hooks covers the advisory-vs-enforced distinction raised above in more depth, and Enterprise Denies, You Allow — Who Wins? Claude Code Permission Precedence extends the same scope-axis diagram to permissions, where the stakes of getting precedence wrong are higher.

For the full five-domain map before diving into more D3 questions, start with Claude Certified Architect (CCA) Exam Guide: All Five Domains on One Diagram. Browse all tutorials for the rest of the series.

Not affiliated with, authorized, or endorsed by Anthropic. “Claude” and “Claude Certified Architect” are trademarks of Anthropic. These are original practice questions for study, not real exam content — verify current exam details on Anthropic’s official pages.