The Codex is the single most important artifact in the system. It's a structured, versioned, living document of everything the agents know about your codebase, its architecture, its patterns, and the way your team works. If the Codex is accurate, the agents produce good work. If the Codex is wrong, they produce garbage — regardless of which model you pair them with.
System type, primary languages and frameworks, infrastructure, data stores, external integrations, deployment model. An auto-generated diagram refined during onboarding. This is the shape of your system as AE understands it.
For every module, package, or service: purpose, public interface, dependencies, dependents, internal patterns, owning team, risk level, and test coverage notes. This is what lets AE answer "what breaks if I change this?" with a real answer.
Named patterns used in your codebase. Each entry has a when-to-use, reference implementations (actual file paths), the rationale behind the choice, key rules, and common mistakes. Agents copy from the canonical examples — not from memory.
Things agents must not do — with historical context. "Direct DB calls in handlers caused a data leak in Feb 2024; we migrated to repositories." That's recorded and enforced.
How tests are structured, what gets mocked and what doesn't, test data management, coverage expectations, how to run the suite, CI pipeline description, known flaky tests.
Naming conventions for domain concepts, file organization, import order, comment philosophy, error message style, logging conventions, configuration approach. Everything the linter doesn't catch.
Branch naming, PR size expectations, commit format, Jira hierarchy and workflow, release process, incident response. How your team actually works, captured.
Business entities and relationships, rules enforced in code, compliance constraints, SLAs, data sensitivity. The business context engineering decisions depend on.
Each Codex version is sequential. Work items are tagged with the version they were planned against. When a new version is published, the system checks each in-flight item: sections that didn't change continue untouched; sections that did are flagged for re-evaluation by the planner.
That means you never have a work item quietly drift out of sync with reality. If the pattern it depended on has been deprecated, the planner knows — and either updates the tag or re-plans the work.
Stored in PostgreSQL for exact lookups and indexed in a vector store for semantic search. An agent retrieves exactly what its current task needs.
"What do I need to know about the billing module?" → catalog entry + relevant patterns + anti-patterns + domain knowledge.
"How should I implement data access in this project?" → relevant patterns with reference implementations.
"What would be affected if I change this interface?" → dependents from the module catalog, related patterns.
"Are there rules about error handling in API endpoints?" → patterns + anti-patterns + style rules that apply.
The Codex defines zones — areas of the codebase that can be independently managed. Each zone maps to one or more modules, has its own subset of patterns, and can be frozen or flagged independently of the others. Agents working in one zone don't worry about freezes in unrelated zones.
Zones typically align with team or domain boundaries. During onboarding they're proposed automatically and refined in conversation — not guessed at.
§ Afterword
Without the Codex, agents are clever autocomplete.
With it, they're colleagues who know your codebase as well as you do.
