Where the project brief is read

A project brief is context, not configuration. Claude Code's documentation states that brief files load at the start of every conversation and are treated as context rather than enforced configuration, delivered as a user message after the system prompt, with no guarantee of strict compliance¹. Where an instruction has to hold regardless of what the model decides, the same documentation sends you to a PreToolUse hook instead¹.

That makes load order the part worth remembering. Four scopes are documented, from broadest to most specific: managed policy, user instructions, project instructions, and local instructions¹. They are concatenated into context rather than overriding one another, and across a directory tree the content is ordered from the filesystem root down to the working directory, so the file nearest the launch directory is read last¹. Within a single directory the local file is appended after the project file¹.

The timeline shows why load order matters: briefs become context after the system prompt, while their placement relative to your prompt is undocumented.

<svg viewBox="0 0 700 210" xmlns="http://www.w3.org/2000/svg">
  <title>Where in one session the project brief becomes context</title>
  <g fill="currentColor" font-family="system-ui, sans-serif" font-size="16">
    <text x="8" y="22">One session, not fully ordered</text>
  </g>
  <line x1="20" y1="96" x2="680" y2="96" stroke="currentColor" stroke-width="1.5" opacity="0.5" />
  <g stroke="currentColor" stroke-width="1.5">
    <circle cx="90" cy="96" r="6" fill="none" />
    <circle cx="350" cy="96" r="9" fill="currentColor" />
    <circle cx="610" cy="96" r="6" fill="none" />
  </g>
  <g fill="currentColor" font-family="system-ui, sans-serif" font-size="15" text-anchor="middle">
    <text x="90" y="74">session start</text>
    <text x="350" y="74">brief becomes context</text>
    <text x="610" y="74">subdirectory brief</text>
  </g>
  <g fill="currentColor" font-family="system-ui, sans-serif" font-size="14" text-anchor="middle">
    <text x="90" y="124">system prompt first</text>
    <text x="350" y="124">a user message,</text>
    <text x="350" y="142">vs. your prompt: not documented</text>
    <text x="610" y="124">only when a file</text>
    <text x="610" y="142">there is read</text>
  </g>
  <g fill="currentColor" font-family="system-ui, sans-serif" font-size="14">
    <text x="20" y="186">Not read at session start: files below cwd, and rules scoped to a path glob.</text>
  </g>
</svg>

Figure: The system prompt comes first, prompt-relative placement is undocumented, and subdirectory briefs wait until a file there is read. In practice you check rather than assume. Claude Code's /context lists which memory files actually loaded in the current session¹. Other tools document their own equivalents without a shared placement claim: Cursor describes project rules as "included at the start of the model context"²; GitHub documents that when a path-specific and a repository-wide instruction file both match, the instructions from both are used, without stating where either lands in the request³; and the AGENTS.md format says agents read the nearest file in the directory tree, again without a placement claim⁴.

This holds for what loads at session start, and that is its boundary. Files in subdirectories below the working directory are not loaded at launch; they come in only when the agent reads a file there, and rules scoped to a path glob behave the same way¹. CLAUDE.md files from directories supplied with --add-dir are not loaded by default either¹. A rule you wrote for one subtree can therefore be absent from the request that needed it. For the exact file names, keys and flags, check the current documentation directly.