What the Intent Layer Is
The Intent Layer is a structured context system that lives inside your repository. It's a network of small, opinionated files — called Intent Nodes — that together form a navigable map of your codebase.
Think of it as GPS for AI agents. Without it, an agent working on your codebase is dropped into a foreign city with no map, no street signs, and no sense of which neighborhood it's in. The Intent Layer gives it orientation, direction, and local knowledge.
How It's Structured
The Intent Layer follows your codebase's own directory structure. At each meaningful level — the repo root, major modules, key subsystems — an Intent Node declares:
- What this area is for (its purpose and responsibilities)
- What patterns to follow (coding conventions, architectural rules)
- What boundaries exist (what this module owns and what it doesn't)
- Where to go deeper (downlinks to child nodes covering subsystems)
This creates a hierarchy that agents can traverse top-down: start with the broad picture at the root, then drill into relevant subsystems as the task demands.
Why It Works
The Intent Layer works because it aligns with how effective human engineers navigate codebases. A senior engineer doesn't read every file before making a change — they start with a mental model of the system, identify the relevant areas, and zoom in. The Intent Layer gives AI agents the same capability.
Key results from real deployments:
- 37% token reduction — Agents load only the context they need, not everything
- 52% less clock time — Less wandering, faster task completion
- 31% more task success — Agents make fewer mistakes when they understand the system
Intent Layer vs. RAG
Retrieval-Augmented Generation (RAG) retrieves context at query time by searching embeddings. The Intent Layer takes the opposite approach: context is structured upfront, organized hierarchically, and loaded progressively.
RAG is great for general knowledge retrieval. But for codebases — where relationships, boundaries, and architectural intent matter — the Intent Layer's structured approach produces significantly better results. See our full comparison.
Getting Started
Start by placing a root AGENTS.md at the top of your repository declaring the system's purpose, major modules, and key patterns. Then add nodes at the next level down — one per major subsystem. Most teams see measurable improvement with just 5-10 well-placed Intent Nodes.
For a complete implementation guide, read The Intent Layer.