Context Architecture

Context Architecture: bind a repository's claims to mechanisms

This skill applies Context Architecture to a repository: it makes the repo's intent and behavior equally legible to people and AI agents, and binds every claim the repo makes about itself to a mechanism that fails when that claim stops being true. It works from the first commit (a repo can be born legible) and on a repo that grew without design (restructured in steps, never all at once). The job is to take the repo as it is and make it legible and self-verifying, without a big-bang rewrite.

Context Architecture treats the repository itself (its file tree, boundaries, conventions, and embedded context) as a designed artifact, not an accident of growth. Introduced by Sergio Azócar in October 2025. Canonical specification: https://context-architecture.dev

The one assumption

Design for a reader who retains nothing between sessions and knows only what the repository says out loud. An AI agent meets this exactly; a new human contributor approximates it. Agents keep memory now, but it is local, unverified, and unshared, so it is not the repository's truth; design as if it were absent.

The rule (the test you run, claim by claim)

Every claim a repository makes about itself must be bound to a mechanism that fails when that claim stops being true.

That is the whole architecture. Everything else is how you apply it.

A claim is anything the repository holds about itself, not just the shape of its folders. "Prices are computed in this module and nowhere else" is a claim. "This operation responds within a certain time" is a claim. "This data format does not break for the people already using it" is a claim. For each one, ask: is there a compiler, a linter rule, an automated test, or a review step (by a person or an agent) that breaks when that stops being true? If not, it is prose, and prose goes stale without anything noticing. A claim with no mechanism behind it is the violation.

The mechanism has to actually fail, not just exist. A performance test that never exercises the slow path does not satisfy the rule, it violates it. That a test can fail is a claim too: mutation testing checks it, a surviving mutant is a test that cannot fail. The rule applies to itself: the set of tests and rules that verify the repository is itself a set of claims, so it too is bound to a mechanism that fails if it is weakened.

The loop (write a claim, verify it, repeat on every change)

Working with an agent is a continuous flow of code changes, and the rule lives inside it. When a change introduces a claim (a source of truth, an invariant, a convention), bind it to a mechanism in the same change; a change that touches existing code meets the mechanisms already there, so a violation goes red before it reaches production. It is not a one-time setup but a property maintained change by change, which is why the context grows with the system instead of falling behind. A claim left loose is caught in review, by a person or an agent, and bound before the change is accepted.

Works with or without a person in the loop

Context Architecture serves the whole autonomy spectrum. What changes across it is who consumes the verification, not the verification. The same AGENTS.md and the same mechanisms work at every level: inline (a person, or a classifier, approves each edit), async (a person reviews before integrating), autonomous (a person sets the rules and does not watch each change), and orchestrated (nobody in the middle). As of 2026 all four exist as products, and with several agents in parallel the merge queue is where the mechanisms arbitrate. When there is a person, the mechanisms absorb the routine checks; when there is no person, they are the reviewer.

The kinds of mechanism (not tools)

Binding a claim is connecting it to something that fails when it stops being true. Context Architecture names the kinds of mechanism; the repository picks the product (oxlint or eslint, it makes no difference), and the infrastructure runs it on each change.

• The compiler catches what can be expressed in types: reintroducing a forbidden import breaks the build.
• The linter catches problems of structure and convention: a file in the wrong folder fails the lint and cites the rule it breaks.
• Automated tests catch documentation that lies and behavior that strays: an AGENTS.md that mentions a deleted file turns the tests red.
• Review, by a person or an agent, catches the meaning the others do not see: on each change it asks whether any document now says something false, and requires the fix in the same change. Review by an agent counts only when its verdict can stop the change (a required check, a request for changes), not a comment nobody must resolve, and its approval never authorizes a change to the verification surface.

Where a mechanism fires is the infrastructure's choice: a hook the repository commits runs it in the agent's loop, the repository's rules run it at push, or CI runs it. Firing early does not replace the gate, because a hook can be switched off locally. The split is clean: Context Architecture decides what gets verified and guarantees the mechanism exists and fails. The infrastructure runs it.

When this applies, and when it does not

Apply it to: repositories that absorb agent or multi-person work, refactors at scale, mechanical migrations, features with a clear spec. It applies from the first commit (a repository can be born legible) and to one that grew without design, restructured in steps.

Do not force it onto: throwaway projects, ill-defined problems, the first prototype of something not yet understood. The structuring work is an investment that pays back in proportion to how much agent or multi-person work the repo absorbs. On a throwaway, the cost outweighs the return. Say so when you see it.

The nine principles

Each principle is a property you can check, not an aspiration. Either it is true of the repository and bound to a mechanism, or it is not. If it cannot be bound to something that fails, it is not a principle.

Let the repository say what it is

01 · Structure Screams Intent. The file tree says what the system does, not what framework built it. A billing/ folder names a business responsibility; a controllers/ folder names a technical detail that could belong to any system. The framework lives one level down, inside the domain it serves. Mechanism: a linter rule that errors when a file lands in a folder that does not match its domain.

02 · Context Lives With Code. Context lives next to the code it describes, at every important boundary, not in a separate wiki that goes stale. It holds only what the code cannot say on its own: where the source of truth is, what invariants must be respected, what tech debt was accepted on purpose, what behavioral limits apply. Mechanism: a test that fails if an AGENTS.md mentions a file that no longer exists.

03 · Boundaries Are Explicit and Named. Each module and package is named for the responsibility it owns. Folders like utils/, common/, or helpers/ collect anything, because the name rules nothing out. Genuinely shared, domain-free code goes in a small shared/ with no dependencies toward any domain. If you cannot name a boundary precisely, the boundary is usually drawn wrong. Mechanism: a rule that forbids a module from importing across another boundary through paths that are not allowed, and breaks the build when it happens.

04 · The Repo Is Legible at Every Zoom Level. Legibility works at every level. A clean tree with functions named doStuff or data2 is legible at one level and illegible at the next. The same discipline that names folders names functions, types, and variables. Mechanism: linter rules on names and complexity limits.

05 · Capabilities Are Discoverable. The project's tools, scripts, and commands live in predictable places with names that say what they do (package.json scripts, a scripts/ folder, a skills folder). A capability an agent cannot find does not exist for that agent: it reimplements it. The list of capabilities is generated from those predictable places, not written by hand. Mechanism: the list generated from the conventional paths, and a test that fails if a real capability does not appear in it.

Bind every claim to a mechanism

06 · Intent Becomes Mechanism. Intent is written as a spec before the code, then turned into the code and into the tests and rules that enforce it, and the spec is removed once its content already lives there. What stays is the intent and its verification, not the code that satisfies it: as long as the tests pin down the behavior, that code can be regenerated. Mechanism: the tests, the types, and the rules the spec was turned into.

07 · Conventions Are Codified, Not Implicit. A convention that lives only in people's heads is invisible to an agent, and the agent will break it. Take it out of the culture and put it in the tools that review the code: linter rules, type constraints, automated validations in CI that state the rule and enforce it in the same place. Mechanism: the linter rules and the type constraints.

08 · Behavior Is Verifiable, Not Asserted. Every claim about how the system behaves (how long an operation may take, what data must not cross a boundary, what format must not break for the people already using it) is bound to an automated test that lives in the repository and goes red when the behavior strays. A time limit in a document goes stale; the same limit bound to a test that fails when it is exceeded is architecture. Mechanism: an automated behavior test (performance, data contract, security) that lives in the repository and fails when the behavior deviates.

09 · The Verification Surface Is Itself Bound. The set of tests and rules that verify the repository is, in turn, a set of claims, so it too is bound. An agent can rewrite the code freely, but it cannot weaken or delete a test, a rule, or a validation to get a change through. Without a person reviewing, this is the principle that matters most: the cheapest way to make a validation pass is to remove it. Mechanism: a validation that goes red if the set of tests and rules changes without the authorization the repository defined.