The Recs Files

SCULLY: "Mulder, I’ve reviewed the latest commits. It’s chaotic. It introduced a second retry wrapper, bypassed the authentication middleware we wrote ten days ago, and renamed Account to Subscriber across four separate modules."

MULDER: "It’s agent drift, Scully. A classic case. The codebase isn't just failing to maintain state—it's actively fabricating a new reality."

SCULLY: "There’s a perfectly rational explanation, Mulder. LLMs are non-deterministic, probabilistic prediction engines. As codebases grow, asking an agent to maintain long-term architectural consistency is a fool's errand. Hallucination is baked into the math."

MULDER (staring at the terminal screen): "That’s where you’re wrong, Scully. You’re blaming the engine for failing to navigate chaos. We keep searching for the solution out there, hoping a bigger context window, a smarter model, or a bigger prompt dump will magically fix our engineering."

SCULLY: "And what's your alternative hypothesis?"

MULDER: "Stop treating context like an unstructured chat log and start treating it like an engineered runtime state. The Recs Files, Scully. The truth is in here."

If you’ve spent more than a few weeks building a system alongside AI coding agents, that conversation isn't science fiction. It’s your Tuesday afternoon.

When an agent operates over long-running projects without explicit structural boundaries, all the decisions you haven't made explicit were never made at all. Left unconstrained, the model default-fills architectural ambiguity with plausible, localized guesses. The codebase slowly degrades into a patchwork of competing idioms, duplicate abstractions, and shifted vocabulary.

Two diametrally opposed behaviors eventually trigger this drift:

1. Context Flooding ("The Truth is Out There"): Dumping raw pull requests, issue threads, chat histories, and full API docs into a massive context window. This creates prompt pollution, high token burn, and subtle reasoning errors.
2. Blind Discovery: Giving the agent a minimal prompt and letting it inspect files haphazardly to "figure it out." This leads to runtime discovery sprawl and unguided guesses.

Both approaches stem from the same flawed premise: treating agent context as an unstructured, growing chat log.

If we want to build complex systems alongside autonomous agents without watching our architecture disintegrate, we must treat context differently. Context is not a conversation history. It is an engineered runtime state. And if we want our software to remain congruent over time, we need a deterministic architecture that keeps humans in firm control of decisions, while directing the agent to execute bounded plans.

Welcome to… The Recs Files (tuuh daah duuh daah dee daah…).

To replace the growing chat log with an engineered runtime state, The Recs Files architecture separates history from active state. Borrowing from Event Sourcing¹ and CQRS², we split our context infrastructure into three distinct artifacts: a root unifying anchor, append-only decision records, and active state projections.

                         [ VISION.md ]
                     (Root Unifying Anchor)
                               │
                               ▼
                   [ APPEND-ONLY RECORDS ]
                 (The "Files" in Recs Files)
               (docs/adr/, docs/user-workflows/...)
                Log of immutable choices & changes
                               │
                               │ Trigger: Record added/superseded
                               ▼
                  [ ACTIVE STATE PROJECTIONS ]
                   (Read-Only Ground Truth)
            Single materialized file per record type

Even with clean projections, a mature repository can accumulate dozens of active state files across different domains. If we dump every projection file into every prompt, we fall right back into context window bloat and reasoning pollution—searching for truth out in the noise.

To keep token spend flat and focus agent reasoning, context assembly in The Recs Files follows a strict Order of Precedence anchored in user value.

                             [ VISION.md ]
                         (Root Unifying Anchor)
                                   │
                                   ▼
                       [ CURRENT_VOCABULARY.md ]
                         (Ubiquitous Language)
                                   │
                                   ▼
                      [ USER WORKFLOW RECORDS ]
                    (Primary Driver / User Value)
                                   │
                                   ▼
                      [ FEATURE DECISION RECORDS ]
                    (Implementation Specs & Details)
                                   │
               ┌───────────────────┴───────────────────┐
               ▼                                       ▼
 [ ERROR / PERFORMANCE RECORDS ]         [ ARCHITECTURAL DECISION RECORDS ]
 (Specialized Constraints)               (Dynamically Filtered Subset)

With our context routed and bounded, we can turn records into production code.

I built my workflow on an evolution of obra/superpowers, and the next article shows how it runs day to day. You can use whatever implementation workflow you want, as long as it respects three rules:

1. Records first. No code is generated or modified without first creating or updating the record that governs it. If a requirement changes, or a bug exposes a case nobody considered, you do not ask the agent to "fix the code". You update the record, the agent updates the projection, and only then does work on the code begin.
2. Records are read-only during execution. While planning, implementing or reviewing, the agent never modifies records or projections.
3. Contradictions halt the work. When the agent finds a conflict or an ambiguity between the task and a record, it stops, surfaces the conflict to the human, and may propose resolutions grounded in VISION.md. The human decides and updates the record, and work resumes.

The third rule is the circuit breaker: it keeps the agent from quietly inventing architectural workarounds under the hood.

Even with a clean plan, codebases evolve over months of active development. If code becomes detached from its governing records, future agent passes will struggle to understand why specific abstractions exist, leading right back to accidental duplication and architectural drift.

To tie source code to its records permanently, we enforce one last invariant: code comments are citations, and nothing else.

1
2
3
4
5
6
7

# UW-014-user-initiates-passwordless-login
# FR-008-stripe-webhook-idempotency-handling
# ADR-012-use-redis-for-session-caching
# knowledge-base/webhook-retries.org §Lock ordering
def process_payment(account, payload)
  # ... implementation
end

When an agent (or human) inspects this code months later, there is no need to guess why the logic was structured this way. The anchors point directly to the original design intent and boundary conditions.

A comment that explains what the code does, or which business rule it obeys, is deleted, and the rule goes into the record where it belongs. A comment that explains technical mechanics (an algorithm choice, a concurrency control, a workaround for a third-party bug) moves into a knowledge base, and the code cites it there. The knowledge base is somewhere the explanation can be verified rather than merely asserted: an instruction manual, or an executable notebook (org-mode, Jupyter) that demonstrates the behavior.

Building software alongside AI coding agents does not require us to choose between two bad choices: flooding prompts with disorganized chat logs or surrendering our architectural authority to an LLM's localized guesses.

By treating context as an engineered runtime state, The Recs Files establish an understandable and maintainable pipeline for software development:

1. VISION.md sets the immutable North Star.
2. Append-Only Records (e.g. ADR-, UW-, FR-) log every choice explicitly.
3. Active Projections provide compact, unpolluted ground truth.
4. Targeted Context Routing keeps token spend bounded and focused on user value.
5. Three Rules of Execution keep humans in control: records first, records read-only while work runs, and every contradiction halted and handed back.
6. Traceability Anchors keep source code permanently connected to design intent.

When we build with this architecture, rapid iteration stops being a descent into chaos. Agents execute bounded plans at high speed, while human developers remain in firm, unambiguous control of system design.

The truth about your architecture isn't scattered out in a 200,000-token prompt log or buried in ephemeral chat histories.

The Recs Files. The truth is in here.