Context Architecture Beats Documentation Dumps

The Problem

AI coding agents with unbounded context degrade in predictable ways. Load the full documentation corpus for a multi-service platform and the model interpolates across unrelated domains, output goes generic because the signal-to-noise ratio drops, and correction cycles multiply. The failure never looks like a refusal; it looks like competent work that is plausibly wrong in a way that is expensive to catch.

The standard response, add more documentation, makes each of these worse. The context window is finite and it is the scarce resource every other concern competes for; every token spent on context the task does not need is a token not spent on the code it does.

The moment that made this obvious was a retry. Two dispatches of a coding agent were handed one brief spanning more than four new files. Each was killed at the roughly fifteen-minute stall signal having produced 68 thousand and 99 thousand characters of planning and no files. Two things changed for the next run: the brief was cut in half, and the prompt named the first file to create. It created that file immediately and finished. Nothing about the model changed; the scope of what it had to hold did.

The Approach

The method has two halves. Partition the corpus so a slice is a coherent, loadable unit (by service, feature domain, or architecture layer). Then route: a router file at the root of each repository, forty to fifty lines rather than four hundred, maps task types to the workspace and the context it loads. Planning context never contaminates implementation context, and a fresh session reaches full speed on one read instead of reconstructing the world from whatever file it happened to open first.

Enterprise scale: built a specification-as-code system as the single source of truth for a multi-service orchestration platform, powering specialist AI coding agents through a hub-and-spoke context architecture. Specs are partitioned by service, feature domain, and architecture layer so each specialist loads the slice its layer needs; a central hub holds the shared skills every specialist inherits; cascade rules keep dependent artifacts in the same change as the spec that moved them.

Data layer: the marathon coach receives a deliberately narrow slice, the recovery signals that gate a hard session (resting heart rate, heart-rate variability, last night's sleep, training readiness) read against acute-to-chronic workload. A rules engine over that slice emits a typed call (PROCEED, REDUCE_INTENSITY, REDUCE_VOLUME, CROSS_TRAIN_OR_REST, FULL_REST, RECOVERY_RUN, NEEDS_MORE_DATA) and the language model narrates it, never decides it. A wellness metric that fails to load stays empty rather than becoming a fake zero.

Interface constraint: the investment committee began as five personas each computing a weighted score from the whole financial picture, and they diverged. ADR-011 mapped every persona to exactly one factor to narrate, never recompute. The lever was the scope of each persona's responsibility; the model did not change.

Partition by layer, not by feature, because features span layers and would force one task across three abstraction levels; a folder earns its place the day two kinds of intent compete for one home. Markdown, not schemas, because humans review it without tooling, language models read prose better than rigid structure, and a spec is the recovery point after a context reset, so it has to read cold.

The Impact

• Scoped context turned two stalled dispatches into a passing one with no change to the model: no files across two full-brief runs, a one-shot pass after the brief was split and the first file named. Two variables moved, so it is the clearest demonstration on record, not a controlled experiment
• The leak surface is measurable in tokens: an evaluation grader already isolated from fleet memory still spent 61,279 tokens, 21 percent of its wave, consulting a second model through a channel nobody had closed; closing it took an explicit environment gate and tool denials, not a prompt, and isolation from the corpus is still not isolation from every channel
• The committee went from two contradictory scores per question to one number per factor with narration that cites it (ADR-011)
• A template plan prescribes the tempo day on the calendar; the grounded coach sees two poor nights of sleep and an elevated resting heart rate and returns REDUCE_INTENSITY, citing both
• What is lost, stated plainly: slices that stop knowing about each other are a filing cabinet, not architecture, so linking matters as much as partitioning; cross-cutting concerns load two slices; spec rot against a stateless reader is the single biggest risk; and curation is a standing cost, because a bounded slice nothing routes to is an orphan