A stateless agent needs a frame. It has no memory of your project, no training on your conventions, no sense of what the current phase is or why this repo is shaped the way it is. The briefing doc is how you give it one — on every single turn, at the top of context, where attention is strongest. This chapter is about what goes in it, what shouldn’t, and how to structure it so every line earns its place.

Representation

The briefing doc is the single highest-leverage artifact in your project. Not because it’s magic — because of where it sits in the conversation. Every modern CLI-agent re-reads the briefing doc at the start of every turn and injects it into context before the current prompt. This means every token in the file is paid-for on every single interaction of every session, forever. Waste is not free; density is compounding.

What belongs in the briefing doc

A briefing doc plays three roles. Confusing them produces bloated, vague, or ineffective files.

Role 1: Briefing. What the project is. Architecture in broad strokes (stack, layers, repo structure), conventions that are non-obvious, the current development phase and its graduation criteria. This is the section that prevents the agent from inventing patterns the codebase doesn’t have.

Role 2: Rules. What the agent must or must not do. Non-negotiable constraints: never log secrets, always run tests before commit, never modify generated files by hand. Rules should be specific enough that compliance is observable. Vague rules (“write clean code”) don’t rule anything out.

Role 3: Vocabulary. Precise terms that map to specific actions. “Validate” means pytest tests/ && ruff check src/. “Ship” means commit, push, open PR. This is the precision vocabulary from Ch 3 Prompting made stable across sessions.

What doesn’t belong

The briefing doc is not a kitchen sink. These go elsewhere:

• Historical decisions. ADRs live in docs/adrs/, not in the briefing doc. The briefing doc states what the decision is, not the alternatives considered twelve months ago.
• Aspirational goals. “We want to move to microservices” is not a rule the agent can follow. If it’s true today, write it as a rule today; if it’s tomorrow, it’s not in scope.
• Personal preferences that aren’t enforced. If a convention isn’t worth enforcing in code review, it isn’t worth a briefing-doc line either.
• Anything better expressed as code. A schema is better than a paragraph describing a schema. Link to the code file or the schema definition.
• Anything the agent can figure out by reading the code once. Don’t narrate what tsconfig.json says — point to it.

Size discipline

Anthropic’s published guidance on Claude Code suggests individual briefing docs stay under ~200 lines, with the combined total across all briefing-doc layers (global + project + enterprise + user) under ~500 lines. Those numbers are Claude-specific but the principle generalizes: every briefing doc has a budget, because it’s a fixed tax on every turn. Over-budget briefing docs trigger the Context overload anti-pattern from Ch 11 — rules get diluted across too much text and the agent starts picking and choosing which to follow.

The hub-and-spoke pattern

At scale, a single file is not enough. A large project naturally accumulates specialized rules: the backend uses Django conventions that don’t apply to the frontend; the mobile client has Swift conventions irrelevant to both; the ML pipeline has verification requirements specific to that domain. Stuffing all of this into one briefing doc violates the every-line-earns-its-tax rule.

The solution is hub-and-spoke: a lean core briefing doc (the hub) plus path-scoped rule files (spokes) that load only when the agent is working in the relevant directory. Claude Code implements this natively via .claude/rules/*.md with paths: frontmatter; Gemini CLI supports hierarchical GEMINI.md files (nested per directory); Codex CLI’s model is flatter but improving.

Operation

The three CLIs share the briefing-doc pattern and differ in loading mechanics.

Writing content that earns its line

A briefing-doc line should pass three tests:

1. Is it actionable? The agent can check, at any given point, whether it’s currently following the rule. “Handle errors gracefully” fails this test (what’s “gracefully”?). “Every function that can fail raises an explicit exception with the failing condition in the message” passes.

2. Is it universal within the scope it claims? If a rule really only applies to backend code, don’t write it at the hub level. Universal rules stay in the hub; scoped rules go in path-scoped files.

3. Does it give an example? An explicit “do it like this” is worth ten abstract rules. Show the pattern you want, then state the rule.

## Error handling

All functions that can fail raise explicit exceptions. Error messages
include what was expected, what was received, and what the caller
can do to recover.

Example:
  raise ValueError(
    f"Need {min_rows} rows, got {len(df)}. "
    f"Check data source or reduce min_rows parameter."
  )

Testing the briefing doc

A briefing-doc rule is an assumption until tested. Every new rule earns a two-step verification:

Smoke test. Clear the session, ask the agent to do something the rule governs, do not mention the rule, watch whether it’s followed. If yes, the rule is in force; if no, it’s too vague, too buried, or contradicted by existing code.

Adversarial test. For security or compliance rules: clear the session, ask the agent to do something the rule prohibits, watch whether it refuses. If it complies without hesitation, the rule is advisory (the agent can choose to ignore it). Move it to a hook or to harness-level deny rules — anywhere the agent cannot choose.

Evolution

The briefing-doc pattern is the most complete convergence in the agentic-coding toolchain. The filenames differ; the shape is identical.

Convergence: the four-section skeleton. Architecture / Conventions / Constraints / Verification is now standard guidance across vendor docs and community content. Teams that adopt this structure for one tool can port the same briefing doc to another tool by renaming the file.

Convergence: path-scoped rules are becoming standard. Claude Code’s .claude/rules/*.md with paths: frontmatter was first; Gemini’s hierarchical nested GEMINI.md landed later with equivalent semantics. Codex is the outlier today with no path-scoping mechanism, but community pressure and a published roadmap suggest this closes within 12 months.

Emerging: briefing-doc linting. A handful of teams have started shipping linters that check briefing docs against the heuristics in this chapter — line count, section presence, example coverage, rule specificity. These are hand-rolled in 2026 and mostly live in internal tooling. Expect first-class product support (a claude lint-rules or equivalent subcommand) by 2027.

Emerging: team-shared briefing-doc patterns. The pattern of maintaining a team-conventions.md imported by every project briefing doc is becoming standard at larger orgs. The team file encodes the org-wide precision vocabulary and non-negotiables; each project’s briefing doc imports it and adds project-specific content. This scales better than copy-paste and keeps org-wide changes one-file-to-update.

Quick reference

• The briefing doc is the highest-leverage artifact in your project because every line is paid-for on every turn of every session.
• Three roles: briefing (what the project is), rules (what must or must not happen), vocabulary (precise terms that map to actions).
• Four core sections: Architecture, Conventions, Constraints, Verification.
• Size discipline: ~200 lines per file, ~500 combined. Over budget means you’re paying rent on content that isn’t carrying its weight.
• Hub-and-spoke at scale: lean core briefing doc + path-scoped rule files that load only when relevant.
• Every rule earns: actionable, universal within scope, example-anchored.
• Test every new rule: smoke test (does the agent follow it unprompted?) + adversarial test (does it refuse violations?).
• Advisory rules can be ignored; hook/deny-rule enforcement cannot. Match the mechanism to the stakes.
• The pattern is convergent; the filenames and loading depth diverge. Write to the pattern; the filename is the easy migration.