Context engineering: brains, pointers and drift checks

Working with AI coding tools every day taught me that the scarce resource is not model capability; it is accurate context. A model that reads a stale README will confidently do the wrong thing. So I treat the filesystem as the canonical memory of the project and design the documents in it for two readers at once: a person picking the work up after a break, and a model starting a fresh session with no history.

Three brains, one rule

The work lives in three documentation repositories, each with a job. A career brain holds identity, verified evidence and a do-not-claim file that overrides everything else. A company brain holds business posture and the dated snapshot of the active arc. A platform brain holds the decision log, the stack overview, the chronology, open questions and working principles learned from mistakes. The one rule across all three: every claim carries evidence, and evidence has three states, verified, stated but not verified, and weakness. Only verified is allowed into public material.

Durable orientation versus dated snapshots

The mistake I made early was baking current state into README files. Six weeks later they read like a snapshot of a project that no longer existed. Now the README and the agent-harness file answer only the question that does not change: what is this repository and where do I look? Everything arc-to-arc lives behind pointers: which vendor is primary, what is deployed, where the business is headed. The current-state document is explicitly replaceable; prior versions live in git history and the durable logs. If a fact in an orientation file reads like a dated snapshot, the rule is to trust the pointer over the file.

Agent contracts

The platform’s agent file is read first by any model touching the repository. It lists hard constraints that were each learned by breaking something: the exact service name, the two-stage status vocabulary whose imperative/past-tense mismatch once caused silent failures, the deploy flags that must never be shortened, the package path that must never be renamed, the customer-facing language rules. It points at the build doctrine before any arc is selected. A model that reads it cannot plausibly make the old mistakes, and a person can audit exactly what the model was told.

Checks that surface drift

1. The status page regenerates from ticket frontmatter; a check mode fails on drift.
2. Backend fixtures and their console mirror are held byte-identical by a lockstep test.
3. The verification gate runs offline with sockets fenced, so a test cannot quietly depend on a live service, and it refuses a dirty working tree.
4. Orientation checklists name the exact files to read, in order, and say when the generated status may lag the tickets and which one wins.

Why this is the job

Applied AI work is mostly deciding what a model is allowed to know and do, and proving afterwards that it stayed inside that. The same discipline that keeps a coding agent from renaming a package keeps an extraction model from writing a name into an address field: a closed contract, a stated boundary and a check that runs. I would rather be measured on that than on how fast I can type.

Related: Tickets as contracts and Why human review sits before the write.