# Context Architecture > Context Architecture is a software architecture for the age of AI agents: it structures a repository so every claim it makes about itself, its structure, its behavior, and who can change it, is legible to the agent writing the code and to the people who answer for it, and bound to a mechanism that fails when the claim stops being true. A specification by Sergio Azócar, who introduced the term in October 2025. ## Documentation Sets - [Context Architecture: full specification](https://context-architecture.dev/llms-full.txt): The complete Context Architecture specification: the rule, the problem, the autonomy spectrum, the write-and-verify loop, the nine principles, what it does not do, and its limits. ## Canonical definition Context Architecture is a software architecture for the age of AI agents: it structures a repository so that everything it claims about itself, its structure, its behavior, and who can change it, is legible to the agent writing the code and to the people who answer for it, and bound to a mechanism that fails when that claim stops being true. It is the design-time counterpart to context engineering (runtime) and harness engineering (the agent operating environment). Introduced by Sergio Azócar in October 2025. - [The manifesto](https://context-architecture.dev/) - [Context Architecture vs. context engineering vs. harness engineering](https://context-architecture.dev/comparison) ## The rule The whole architecture reduces to one rule: every claim a repository makes about itself must be bound to a mechanism that fails when that claim stops being true. A claim is anything the repository holds about itself, not just the shape of its folders: where the source of truth lives, what pattern is correct, how long an operation may take, what data must not cross a boundary. The mechanism must actually fail, not just exist; a check that cannot fail violates the rule. The rule applies to itself: the set of tests and rules that verify the repository is also bound, so it cannot be weakened to get a change through. Design for a reader who retains nothing between sessions and knows only what the repository says out loud (an agent meets this exactly). When no person reviews the code, the mechanisms are the reviewer. ## The problem Writing code stopped being the bottleneck; verifying that a growing volume of changes does not break anything, at the speed an agent produces them, is. A small error rate times that volume and speed, with no mechanism that fails when a claim is violated, is silent breakage at scale. With a person reviewing, verification does not scale. Without a person, a change that looks correct gets integrated because nothing failed. The job of the architecture is not to make the agent wrong less often (the model handles that), but to make every violated claim fail at once, where it broke. The problem grows with better models, it does not go away. ## The autonomy spectrum Context Architecture works with or without a person in the loop, across the whole range: inline (a person approves each edit), async (a person reviews the change before integrating), autonomous (a person sets the rules and does not look at each change), and orchestrated (nobody in the middle). What changes across the spectrum is who consumes the verification, not the verification: the same AGENTS.md and the same mechanisms serve all of them. With a person, the mechanisms absorb the routine review; without a person, they are the reviewer. ## How it applies Working with an agent is a continuous flow of code changes, and the rule lives inside that flow. When a change introduces a claim (a source of truth, an invariant, a convention), it is bound to a mechanism in the same change; when a change touches existing code, it meets the mechanisms already there. Binding means connecting a claim to something that fails when it stops being true. Context Architecture names the kinds of mechanism, not the tool: the compiler (a forbidden import breaks the build), the linter (a misplaced file fails the lint), automated tests (an AGENTS.md citing a deleted file turns the tests red), and review by a person or an agent (catches the meaning). Context Architecture decides what gets verified and guarantees the mechanism exists and fails; the infrastructure runs it. ## The principles Each principle is a property you can check, bound to a mechanism, not an aspiration. Let the repository say what it is: 01 Structure Screams Intent (the file tree says what the system does, not what framework built it); 02 Context Lives With Code (context at every boundary, next to the code, not in a wiki that goes stale); 03 Boundaries Are Explicit and Named (named for the responsibility they own; genuinely shared code goes in a small shared/, the debt is using a generic name to avoid deciding); 04 The Repo Is Legible at Every Zoom Level (from the tree to the function body); 05 Capabilities Are Discoverable (tools and commands at predictable paths, listed by a generated index that cannot leave one out). Bind every claim to a mechanism: 06 Intent Becomes Mechanism (the spec is written before the code, becomes the code and the checks that enforce it, then is removed; the durable artifact is the intent and its verification); 07 Conventions Are Codified, Not Implicit (lint rules and type constraints); 08 Behavior Is Verifiable, Not Asserted (latency, security, and data contracts bound to an automated test in the repository that goes red when behavior deviates); 09 The Verification Surface Is Itself Bound (an agent cannot weaken or delete a check to get a change through). ## What it does not do, and how to apply it Context Architecture is not an isolation or permissions system, not the machinery that runs the controls, not regulatory compliance, and it does not impose tools (it names the kinds of mechanism, the repository picks the product). It does not make the agent smarter; it makes the truth of the repository checkable so the agent error fails at once instead of integrating silently. It applies from the first commit (a repository can be born legible) and to one that grew without design, restructured in steps. The skill is an agent-agnostic procedure (a single Markdown file, served raw at /skill.md) that audits a repository against the principles and proposes a prioritized backlog. - [How to apply Context Architecture](https://context-architecture.dev/guide) - [The Context Architecture skill (agent-agnostic)](https://context-architecture.dev/skill) - [The skill, raw markdown](https://context-architecture.dev/skill.md) - [Glossary: Context Architecture and adjacent terms](https://context-architecture.dev/glossary) ## Docs - [Context Architecture vs. context engineering vs. harness engineering](https://context-architecture.dev/raw/en/comparison.md): Three disciplines, three objects of design. Context Architecture designs the codebase itself, the design-time counterpart to context engineering (runtime) and harness engineering (the agent's operating environment). A specification by Sergio Azócar. - [Glossary: Context Architecture and adjacent terms](https://context-architecture.dev/raw/en/glossary.md): Concise, citable definitions of Context Architecture and the terms it is most often confused with: context engineering, harness engineering, AGENTS.md, spec-driven development, and context-rot. A specification by Sergio Azócar. - [How to apply Context Architecture](https://context-architecture.dev/raw/en/guide.md): A hands-on guide to making a repository legible to people and AI agents: structure it so it says what it is, then bind every claim it makes about itself to a mechanism that fails when the claim stops being true. Works from the first commit and on a repo that already grew. A specification by Sergio Azócar. - [Context Architecture](https://context-architecture.dev/raw/en.md): Context Architecture is a software architecture for the age of AI agents: it structures a repository so that everything it claims about itself, its structure, its behavior, and who can change it, is legible to the agent writing the code and to the people who answer for it. A specification by Sergio Azócar. - [The Context Architecture skill, run it with your agent](https://context-architecture.dev/raw/en/skill.md): An agent-agnostic skill that audits a codebase against the nine principles of Context Architecture, finds the claims that are not bound to a mechanism, and hands back a backlog of fixes. One command installs it into Claude Code, Cursor, Codex, Copilot, and more. By Sergio Azócar. - [Context Architecture vs. context engineering vs. harness engineering](https://context-architecture.dev/raw/es/comparison.md): Tres disciplinas, tres objetos de diseño. Context Architecture diseña el codebase mismo, la contraparte de diseño de context engineering (runtime) y harness engineering (el entorno de operación del agente). Una especificación de Sergio Azócar. - [Glosario: Context Architecture y los términos adyacentes](https://context-architecture.dev/raw/es/glossary.md): Definiciones concisas y citables de Context Architecture y los términos con los que más se confunde: context engineering, harness engineering, AGENTS.md, spec-driven development y context-rot. Una especificación de Sergio Azócar. - [Cómo aplicar Context Architecture](https://context-architecture.dev/raw/es/guide.md): Una guía práctica para dejar un repositorio legible para personas y agentes de IA: estructúralo para que diga lo que es, y luego ata cada afirmación que hace sobre sí mismo a un mecanismo que falla cuando esa afirmación deja de ser verdad. Sirve desde el primer commit y en un repo que ya creció. Una especificación de Sergio Azócar. - [Context Architecture](https://context-architecture.dev/raw/es.md): Context Architecture es una arquitectura de software para la era de los agentes de IA: estructura un repositorio para que todo lo que afirma sobre sí mismo, su estructura, su comportamiento y quién puede cambiarlo, sea legible para el agente que escribe el código y para las personas que responden por él. Una especificación de Sergio Azócar. - [El skill de Context Architecture, aplícalo con tu agente](https://context-architecture.dev/raw/es/skill.md): Un skill agnóstico de agente que audita un codebase contra los nueve principios de Context Architecture, encuentra las afirmaciones que no están atadas a un mecanismo y te devuelve un backlog de arreglos. Un comando lo instala en Claude Code, Cursor, Codex, Copilot y más. Por Sergio Azócar.