Every team using AI coding tools eventually hits the same wall: the model writes syntactically correct code that violates your architecture. It creates a service that should be a selector. It puts business logic in a view. It uses synchronous patterns where you've standardized on async.
The fix isn't better prompting. The fix is building a documentation layer that gives AI agents persistent context about your codebase. At Horizon, we use three layers: AGENTS.md for app-level architecture rules, CLAUDE.md for behavioral instructions, and Skills for reusable workflows.
AGENTS.md: Architecture Rules Per App
Every app in our Django monorepo has an AGENTS.md file at its root. This file describes the app's purpose, its scope, its invariants, the patterns it follows, what it should never do, and pointers to key files.
Here's what a real AGENTS.md looks like for our Company App:
Company App
WHY (Purpose) Provide foundational company and employee models used across the product.
WHAT (Scope & Invariants)
- •Soft deletes: Employee deleted_date / deleted_by and User is_active=False
- •Email is globally unique across companies (via User OneToOneField)
- •balance_uid defaults to uuid if empty during creation
- •Company creation auto-creates permission groups via signal
- •Admin/Company creation triggers multiple signals (including external API calls)
HOW (Focal Points)
- •Use services for writes and bulk imports
- •Use selectors for read-heavy access
- •Keep signals lightweight; heavy work goes to tasks/services
Anti-Patterns (Never Do)
- •Query employees without filtering soft-deleted rows
- •Bulk-create employees without create_employees_hierarchically()
- •Call get_company_copilot_model() in loops
- •Import conversation_app models at module level
Code Pointers (How)
- •Import flow: company_app/services.py
- •Permissions: company_app/models.py
- •Signals: company_app/signals.py
This file is read by AI agents before they write any code in that app. It's not documentation for humans (though humans benefit from it too). It's the instruction set that prevents an AI from making architectural mistakes.
The key sections: WHY tells the model what this app is for, so it doesn't put unrelated logic here. WHAT tells it the invariants it must respect. HOW tells it the patterns to follow. Anti-Patterns tells it specifically what to avoid. Code Pointers tells it where to find things.
The agent_docs Directory: Deep Technical Context
Beyond AGENTS.md, each app can have an agent_docs folder containing detailed documentation files. These are the deep dives that give AI agents expert-level understanding of specific technical areas.
In our codebase, the agent_docs directory includes files covering async patterns, Django templates, error handling, external integrations, services and selectors, architecture patterns, BPMN layout engine, product context, rule evolution logs, and testing patterns.
Each file covers a specific technical domain in enough detail that an AI agent can work within it correctly. The async_patterns.md file, for example, specifies when to use async views (SSE streaming endpoints, high-concurrency API endpoints, endpoints that call multiple external services in parallel) and the exact pattern for wrapping Django ORM operations in async views using sync_to_async.
CLAUDE.md: Behavioral Instructions
While AGENTS.md defines what and how, CLAUDE.md defines the behavioral rules for the AI agent itself. This file lives at the project root and at the app level, and it tells the model how to behave when working on this codebase.
CLAUDE.md includes things like: what command to run for tests, how to format commit messages, what linting rules to follow, and cross-cutting concerns that span multiple apps.
The distinction matters. AGENTS.md is about the code's architecture. CLAUDE.md is about the agent's behavior. Together, they give an AI tool both the technical context and the operational instructions it needs.
Skills: Reusable Workflows
The third layer is Skills. These are packaged workflows that automate multi-step processes.
For example, we have a translation skill that handles Django .po file translations. We also have an agent-docs-updater skill that automatically updates AGENTS.md files when code patterns evolve, a create-markdown-file skill, and a spec-clarification-questions skill.
Each skill has a SKILL.md file that defines the workflow step by step. The agent-docs-updater skill automatically updates AGENTS.md files when code patterns evolve. This keeps the documentation layer in sync with the actual code.
How We Keep Documentation Updated
Documentation that drifts from reality is worse than no documentation. It actively misleads AI agents.
Our approach: we document using AI, then review and correct. When a new pattern emerges or an existing one changes, we use AI to draft the updated documentation based on the current code, then a human reviews and approves it.
We also track a rule-evolution-log.md that records when and why rules changed. This gives both humans and AI agents a history of architectural decisions.
The improvement cycle is continuous. We write docs with AI, review them, use them to generate features, observe where the AI goes wrong, and update the docs accordingly. Every mistake is a documentation gap that gets filled.
What This Costs and What It Saves
Writing and maintaining this documentation layer takes real effort. Initial setup for a new app is a few hours. Ongoing maintenance is part of every feature's lifecycle.
But the return is massive. When an AI agent has the right AGENTS.md and agent_docs, it produces code that follows your patterns on the first try. No back-and-forth. No "actually, we don't do it that way here." The code reviews become about logic and edge cases, not about architectural corrections.
For teams that want to start: pick your most actively developed app. Write its AGENTS.md. Focus on the Anti-Patterns section first, because that's where AI makes the most costly mistakes. Then expand to agent_docs as you identify repeated context that the model needs.