# Context Architecture > Context Architecture is a software architecture for the age of AI agents: the practice of structuring a codebase so that its intent and behavior are equally legible to people and AI agents. 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: canonical definition, the eight principles, the practices, the case studies, and the comparison with adjacent disciplines. ## Canonical definition Context Architecture is a software architecture for the age of AI agents: the practice of structuring a codebase so that its intent and behavior are equally legible to people and AI agents. It treats the repository itself (its file tree, boundaries, conventions, and embedded context) as a designed artifact, not an accident of growth. It is the structural, design-time counterpart to context engineering (runtime) and harness engineering (the agent operating environment), and the heir to Screaming Architecture. 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 invariant: every claim a repository makes about itself must be bound to a mechanism that fails when that claim stops being true. The slogan: if a piece of context can rot silently, it is not architecture, it is documentation. The rule assumes a reader who retains nothing between sessions and knows only what the repository makes explicit (AI agents satisfy this exactly), and it exists to remove five failure modes: reimplementation, invented structure, obedience to false documentation, deprecated-pattern propagation, and random ambiguity resolution. ## How it works Context is written (the four pillars), verified (the mechanism), and, in its mature form, fed (the metabolism). The four pillars: 1 Structure Screams Intent, 2 Embedded Context at every boundary, 3 Intent Becomes Mechanism (a spec written before code, then turned into tests, types, and lint, and removed), 4 Capabilities Are Discoverable (at predictable paths, bound to a generated, drift-checked index). Context lives with the code (where it is written) and conventions are codified (the mechanism's first instance) run across all four. The mechanism is four layers that make a claim fail when it stops being true: the compiler, the linter, the tests, and review (human or AI); together they leave the five failure modes nowhere to happen. The metabolism: when a PR introduces a source of truth, the review loop asks to document it in the same PR, so context grows with the system. It all serves one quality attribute: the time to the first correct change by a reader with no prior context. ## The principles The methodology is eight principles. 01 Structure Screams Intent: a reader, person or agent, must infer what the system does from the file tree alone, never from the framework it happens to use. 02 Context Lives With Code: embedded context belongs at every meaningful boundary, colocated with what it describes, not exiled to a wiki that drifts. 03 Intent Becomes Mechanism: intent is written as a spec before code exists, then becomes the code and the checks that enforce it (acceptance criteria become tests, contracts become types, conventions become lint); the spec is scaffolding, removed once that is done, kept only when it is generative. 04 Boundaries Are Explicit and Named: every module, package, and ownership line is named so its responsibility is inferable; ambiguous names are architectural debt. 05 Conventions Are Codified, Not Implicit: encode conventions in linting and types so the toolchain can check them. 06 Capabilities Are Discoverable: tools, skills, and commands live at predictable paths, bound to a generated, drift-checked index, so an agent finds them instead of re-implementing them; choosing which to load at runtime is context engineering's job. 07 The Repo Is Legible at Every Zoom Level: from the file tree to the function body, each level of zoom communicates purpose; legibility is fractal. 08 Optimize for the Newcomer, and the Newcomer Is Now an Agent: the clearest test of architecture is how fast a stranger becomes productive, and that stranger is increasingly a machine. ## Applying it Context Architecture is a retrofit discipline for codebases that already exist, not a scaffold for new projects. The guide walks the incremental retrofit step by step. The skill is an agent-agnostic procedure (a single Markdown file, no server) that audits a repository against the eight principles, finds context-rot, and proposes a prioritized backlog; it is served raw at /skill.md so an agent can fetch it in one request. The glossary defines the term alongside context engineering, harness engineering, AGENTS.md, spec-driven development, and Screaming Architecture. - [How to apply Context Architecture to an existing codebase](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 Screaming Architecture. A specification by Sergio Azócar. - [How to apply Context Architecture to an existing codebase](https://context-architecture.dev/raw/en/guide.md): A hands-on guide to reworking a repository so it is legible to people and AI agents: audit it as a cold reader, fix the docs that lie, put AGENTS.md at the boundaries, and back every claim with a check. 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: the practice of structuring a codebase so that its intent and behavior are equally legible to people and AI agents. 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 an existing codebase against the eight principles of Context Architecture, finds the docs that lie, 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 Screaming Architecture. Una especificación de Sergio Azócar. - [Cómo aplicar Context Architecture a un codebase existente](https://context-architecture.dev/raw/es/guide.md): Una guía práctica para reordenar un repositorio y dejarlo legible para personas y agentes de IA: léelo como alguien sin contexto, arregla los docs que mienten, pon AGENTS.md en las fronteras y respalda cada afirmación con un check. 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: la práctica de estructurar un codebase para que su intención y comportamiento sean igual de legibles para personas y agentes de IA. 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 existente contra los ocho principios de Context Architecture, encuentra los docs que mienten y te devuelve un backlog de arreglos. Un comando lo instala en Claude Code, Cursor, Codex, Copilot y más. Por Sergio Azócar.