Context Modeling

LLM onboarding has two artifacts. The rules file tells the model how to behave - we published ours in A Working AGENTS.md, Annotated. This piece is about the other one: documents that tell the model where to look. We call the practice context modeling, and on large legacy codebases it is the difference between a model that navigates and a model that wanders.

A context model is a document written for an LLM, not for a human. Its entire job is to make the model confident enough to load the right code into its window. Nothing more.

The problem it solves

Point a model at a mature codebase and ask a question that spans two large classes - the kind with fifteen-hundred-line methods that grew over a decade. The model starts reading sequentially, because that is all it can do with no map. Three files in, most of the context window is gone, the relevant method was never reached, and the answer that comes back is confident and wrong. The failure looks like model incompetence. It is actually missing navigation.

Human documentation does not fix this, because it is built for a different reader. Architecture overviews explain rationale and history - things a model does not need, since it reads the code itself. What the model needs is the thing human docs almost never contain: which methods matter, how the parallel pieces map to each other, and an explicit instruction about what NOT to read.

The form

One way to picture a context model: an AST of the codebase - the structural skeleton - with human hints layered on top that point at flow and narrative. The structure tells the model where things are; the hints tell it which paths matter, in what order, and which ones to leave alone.

A context model is small and rigid. The template we use carries these rules:

Hard rules:
- Cap the file at ~120 lines. Past 150, split by topic and link the
  splits from the repo's agent instructions file.
- 25% orientation, 75% code-reading guide. Do not invert the ratio.
- Tables for cross-references. No prose explaining methods one at a
  time - the model reads the code itself.
- Identifiers (class and method names), not line numbers. Names
  survive edits; line numbers do not.
- No code excerpts. No history. No rationale.
- Stamp the doc with the commit it was generated against.

What this is not:
- Not engineer onboarding. Not an architecture overview.
- Not an API reference. Not a changelog.

Every rule is a context-budget rule in disguise. The 120-line cap exists because the doc itself consumes window - a map that costs more than the territory is a bad map. The 25/75 ratio keeps the doc from drifting into an architecture essay. Identifiers instead of line numbers make the doc survive edits, so it stays true between regenerations. And the commit stamp tells the next session how stale the map might be.

A worked example

A fictional but representative case - the shape appears in almost every system past a certain age. A billing platform computes sales commissions in two places: a nightly BatchCommissionRun that produces the statements of record, and a QuoteCommissionService that recomputes live so a rep can preview a deal. Same business rule, implemented twice, fifteen years apart - and drifted, in ways nobody has fully written down.

Drift is exactly where an unguided model gets hurt: it finds one implementation, assumes parity, and answers questions about the other. The context model's job is to state the shared rule once and map each step to its method on both sides:

1. LOAD      - contract, rate tables, active overrides
2. QUALIFY   - which line items are commissionable?
3. APPLY     - tier schedules, splits, caps
4. ADJUST    - clawbacks, manual corrections
5. SETTLE    - batch: persist statements
               quote: return the preview

Then the heart of the doc, the cross-reference - including the part that took real verification to write, the side-only branches:

| Rule step        | BatchCommissionRun       | QuoteCommissionService |
|------------------|--------------------------|------------------------|
| Orchestrator     | runStatements(period)    | quote(request)         |
| Qualification    | qualifyLines(...)        | filterCommissionable(...) |
| Tier application | applyTierSchedule(...)   | applyTiers(...)        |
| Caps and splits  | enforceCaps(...)         | applyCapsAndSplits(...)|
| Settle           | persistStatements(...)   | buildPreview(...)      |

Side-only branches (verified, not assumed):
- batch-only: clawbacks, retroactive adjustments
- quote-only: what-if override inputs

Note: read ONLY the methods listed above. Do NOT read these files
sequentially - they are too large and you will burn the context window.

That closing note is the single highest-value line in the document. It converts the model's default behavior - read everything, in order - into targeted loading: jump to the named methods, skip the rest. One line of instruction protects the working band of the entire session (the capacity argument is in Make the Change Easy).

Docs you can test

Here is what separates context modeling from documentation in general: the doc has a measurable job, so you can measure it. The protocol we use:

• Pick a real task that touches the area. Run it through a fresh session twice: once with the doc loaded, once without. The gap between the two runs is what the doc bought you.
• Repeat with three or four different tasks. One trial is noise; repetition is signal.
• Where the model trips up is the edit list for the next revision.
• A reviewer approving the doc runs the same loop. The doc earns its place in the repo the way code does - by demonstrating behavior, not by looking right.

The same protocol produces the maintenance signal: if the doc keeps growing as you patch holes, it is telling you to split by topic. And the drafting is itself AI-augmented work - the model helps write the doc, but it will not truly understand the code on its own. The operator wrangles the knowledge out of it, iteratively, which is exactly the turn-based discipline from the Three Disciplines.

The onboarding pair

Rules file plus context models: the constitution and the map room. The rules file is global and behavioral; context models are local and navigational, one per hairy area of the codebase, each linked from the rules file so the model knows the maps exist. Teams ask where to start with LLM onboarding, and the answer is the same one this site keeps giving: start where the model gets lost, write the smallest document that fixes it, and test that it did.