context-architecture

name	context-architecture
description	Audit a codebase and bind every claim it makes about itself to a mechanism that fails when the claim stops being true, so it is legible to people and AI agents. Applies Context Architecture's nine principles: make structure say what the system does, place AGENTS.md at boundaries, codify conventions, and bind every claim the repo makes about itself to a mechanism (compiler, linter, automated tests, review) that fails when the claim stops being true. Works greenfield (a repo born legible) and brownfield (a repo restructured in steps). Use when an agent reimplements code that already exists, invents structure, follows stale or deleted docs, propagates a deprecated pattern, or resolves ambiguity at random, or when asked to make a repository "agent-ready", "AI-legible", or to add or fix AGENTS.md / CLAUDE.md files.
license	CC BY 4.0
metadata	{"source":"https://context-architecture.dev","author":"Sergio Azócar","term-introduced":"2025-10"}

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.

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. 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. The rule lives inside that flow, not off to the side:

1. Write the claim. A change introduces or modifies something the repository holds about itself: a new source of truth, an invariant, a convention.
2. Verify it. Bind that claim to a mechanism that fails when it stops being true, in the same change. A change that touches existing code also meets the mechanisms already there: if it violates a claim, something goes red before it reaches production.
3. Repeat on every change. This is not a setup you do once. It is a property maintained change by change, which is why the repository's context grows with the system instead of falling behind.

When a change adds a new claim and leaves it loose, review (by a person or an agent) catches it and requires it to be 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:

Level	Who reviews	What breaks without repository discipline
Inline	a person approves each edit	the agent reimplements things that already exist; the person burns time on what the tools could have caught
Async	a person reviews the change before integrating it	review does not scale; the integration gate exists but enforces nothing, one click lets a change through
Autonomous	a person sets the rules, does not look at each change	if the mechanisms are missing, "done" is empty: the agent calls a change finished when it passes but is wrong
Orchestrated	nobody in the middle	the error multiplies at machine speed; the only arbiters are the repository's mechanisms

When there is a person, the mechanisms absorb the routine checks, so the person spends attention on what needs judgment. When there is no person, the mechanisms 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.

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.

The procedure

Run four phases in order. Phases 1 and 2 are read-only; do not edit until you have the audit and a prioritized plan. The work in phase 3 is incremental: one bounded change at a time, each landing with the mechanism that keeps it true.

Phase 1: Audit (read-only)

Walk the repository and judge it against the nine principles. Read the top-level tree first, then the boundaries, then a sample of leaf files. For each principle, record a verdict (holds / partial / violated), the evidence (paths), and the mechanism that is (or should be) bound to it.

Use the five failure modes as diagnostic signals: each is what a cold reader does when a claim is not bound, and each points back at the principle that is loose. A better model lowers their frequency, it does not remove them, because the missing mechanism is in the repository, not the reader. When you see one of these in the repo's history (or imagine a cold agent producing it), name the unbound claim behind it:

• Reimplementation. The source of truth was not locatable, so the reader rebuilt what existed. (Points at 01, 03, 05.)
• Invented structure. None was imposed, so the reader imposed its own. (Points at 01, 03.)
• Obedience to false documentation. Cites deleted files or contradicts the current code. (Points at 02, 06.)
• Deprecated-pattern propagation. Copies the most visible pattern even when it is obsolete. (Points at 04, 07.)
• Random ambiguity resolution. Two conventions coexist; it uses whichever it read first. (Points at 07.)

Phase 2: Prioritize (incremental, by leverage)

Never propose a big-bang restructuring. Order the work by leverage and reversibility:

1. Context-rot first (cheap, high trust). Find and fix docs that lie; they actively mislead the reader. See phase 3.
2. Embedded context at the top boundaries (AGENTS.md at the root and the few highest-traffic directories). Highest legibility gain per edit.
3. Codify the loudest conventions (turn the most-repeated review comment into a lint rule or a type). This is what makes every other claim hold.
4. Name the worst junk drawers (split or rename utils//common/ only where it buys clarity; keep a genuinely generic shared/ small).
5. Domain-first top level last, and only if the gain justifies the churn. It is the most expensive and most likely to break imports. Often a partial move plus a clear AGENTS.md beats a full reshuffle.

Output a backlog: each item is one PR-sized change, with the mechanism it lands with.

Phase 3: The moves (the concrete edits)

Each move pairs a claim with the mechanism that fails when the claim stops being true. A move without its mechanism is just documentation; do not land it that way.

Place an AGENTS.md at each meaningful boundary. Keep it short and specific to its scope. Put in it only what cannot be learned by reading the code:

# AGENTS.md (<boundary name>)

<One line: what this boundary owns.>

## Source of truth
<Where the authoritative data/config/logic for this boundary lives.>

## Invariants
<Rules that must hold. Each should be bound to a mechanism; note which.>

## Gotchas / accepted tech debt
<What looks wrong but is intentional, and why.>

## The why a spec left behind
<Rationale the code cannot hold, moved here from a   ( )>

Bind each invariant to a mechanism, and add the mechanism in the same change, or the AGENTS.md is a new claim that can go stale.

Bind claims to mechanisms. The four kinds, each catching a kind of drift:

• Compiler. A forbidden import alias breaks the typecheck (a banned path mapping, a nominal type).
• Linter. A file in the wrong folder is an immediate error citing the rule (custom lint rule / import-boundary rule). Reach for the linter to enforce structure and conventions.
• Tests. A doc that cites a deleted file turns the suite red (a test that asserts every path referenced in AGENTS.md/README still exists); a generated capability index that drops a real capability turns it red.
• Review (person or agent). Guards semantic truth: on every change, ask whether it leaves any doc lying, and require fixing it in the same change.

Detect and fix context-rot. Find documentation that lies:

• Extract every file path, command, symbol, and URL referenced in README, AGENTS.md/CLAUDE.md, and design docs; verify each still exists / still runs. Dead references are the highest-priority fix.
• Diff each AGENTS.md against the code it sits beside: does it describe modules, exports, or flows that no longer match? Correct the doc, then add the test that would have caught it.
• Land a doc-reference test so this class of rot cannot return.

Name boundaries. Rename or split utils//common//core/ only where a precise name exists (pricing-engine, auth-session, event-ingestion). If you cannot name a boundary precisely, that is a signal the boundary is wrong, not an excuse to call it shared. Keep a genuinely generic shared/ small and dependency-free.

Make capabilities discoverable. Move scripts/generators/commands to conventional, named locations (package.json scripts, a scripts/ or skills/ directory). Where possible, generate the capability index from the conventional paths rather than hand-keeping it, and test that the index is complete. A hand-kept list is itself a claim that goes stale.

Phase 4: Keep the loop running

Context grows with the system only if write-and-verify runs on every change. Install the review-loop instruction: when a change introduces a source of truth or an invariant, the loop asks to document it right there, in the same change, bound to a mechanism. Add this instruction to the root AGENTS.md and to the review checklist, so a new claim cannot land loose. Bind the verification surface itself (principle 09) so the mechanisms cannot be weakened to get a change through.

Output: the audit report

Produce this before any edit:

# Context Architecture audit (<repo>)

## Summary
<2-3 sentences: where would a cold reader (a person or an agent) guess, and why.>

## Per-principle verdict
| # | Principle | Verdict | Evidence (paths) | Mechanism (bound / missing) |
|---|-----------|---------|------------------|------------------------------|
| 1 | Structure Screams Intent | holds / partial / violated | ... | ... |
| ... | | | | |

## Failure-mode signals
<For each signal observed: the failure mode, the unbound claim behind it, the principle it points at.>

## Context-rot found
<Dead references in docs: file, the false claim, the correct state.>

## Prioritized backlog
1. <PR-sized change>, lands with <mechanism>. Leverage: <why first>.
2. ...

Guardrails

• Work incrementally. One bounded, reversible change at a time, each with its mechanism. Never a big-bang restructuring.
• A claim without a mechanism is the violation. Do not add an AGENTS.md invariant, a README promise, or a convention doc without the check that fails when it stops being true.
• The mechanism must actually fail. A test that never exercises the path it guards violates the rule, it does not satisfy it.
• Do not invent or alter the methodology. The nine principles above are the author's methodology; apply them as written. Do not add principles of your own.
• Stay qualitative about results. Do not attribute performance numbers to Context Architecture; speed gains belong to the specific tooling, not the discipline.
• Respect the limits. If the repo is a throwaway or the problem is ill-defined, say the cost beats the return rather than applying the discipline anyway.
• It does not make the agent smarter. It makes the truth of the repository checkable automatically, so an error fails at once and where it happened, instead of integrating without anything noticing.

---

Canonical specification, the nine principles in full, and the comparison with context engineering and harness engineering: https://context-architecture.dev. Raw, agent-readable: https://context-architecture.dev/llms.txt