AOL 3 - /docs / RAG | Resource Hub | Agent Builder Academy

The short version

At AOL 3, you give the agent deep context. It now knows not just what the project is, but how it is supposed to be built. This is where output quality makes a real jump. The agent has enough context to act with real intent - it stops guessing at your standards and starts following them.

Why it is called the Blueprint

A map tells you where things are. A blueprint tells you how they are supposed to look and work. Your /docs folder is the blueprint of your project. The agent reads these documents when it needs to make a decision - and makes the right one instead of a generic one.

What /docs gives the agent

Design standards

Colors, spacing, typography, component patterns. The agent follows your system instead of inventing its own.

Architecture decisions

Why the project is structured the way it is. The agent understands the reasoning, not just the result.

Anti-patterns

What not to do. The agent avoids your known bad paths instead of rediscovering them.

Business logic

Rules that are specific to your domain. The agent knows the "why" behind the constraints.

How to write docs the agent can use

Agents read differently from humans. They perform best with clear, direct requirements - not explanations and background.

Avoid

"We generally prefer blue for our primary buttons because it aligns with our brand values and feels trustworthy to users."

Prefer

"Primary button: background #00D9FF. Never use inline styles. Always use design tokens."

Keep each document focused on one topic. A 200-line focused document is more useful than a 2000-line general one. The agent pulls in only what it needs - small, precise documents make that pull more accurate.

Rule of thumb: if you explain it twice, document it once. DRY applies to context too.

How the agent reads /docs

There are four ways an agent accesses your docs, ranging from fully manual to fully autonomous. Most teams start at the top and move down as the project matures.

Manual

@docs/design.md

You reference the file directly in the prompt. Precise, but repetitive. Does not scale across sessions.

CLAUDE.md anchor

Automatic at session start

CLAUDE.md points to the relevant docs by intent. The agent reads them when it needs to make a decision. This is the AOL 3 baseline.

Built-in file search

Agent searches the project

Claude uses grep, glob, and file reads to find relevant content on its own. Full-text search, not vector search. Works well when files are focused and well-named.

RAG / vector search

Semantic retrieval on top of /docs

Your /docs files get chunked and embedded into a vector database. RAG does not replace them - it indexes them. The agent retrieves the most relevant chunks by meaning, not by filename. Additive, not a replacement. Right when the volume justifies the infrastructure.

MCP servers

Autonomous cross-system queries

Power-user mode. Agents query docs across multiple systems autonomously. Often combined with RAG. AOL 5 territory.

RAG adds to /docs - it does not replace it

RAG does not remove your /docs files. It reads them. Your markdown files stay exactly as they are. RAG adds a layer on top: it breaks each document into small pieces, turns them into numbers (embeddings), and stores them in a database. When the agent needs something, it searches by meaning - not by filename. Good docs make RAG work better, not useless.

For most projects, /docs with CLAUDE.md pointers is enough - and will stay enough. Adding RAG early means adding real infrastructure: a vector database, an embedding pipeline, re-indexing every time a doc changes, and ongoing tuning. Add it when you feel the friction. Not before.

Add RAG when you see these signs

More than 50 docs and the agent keeps reading the wrong ones
Documents are long and the agent misses the important parts
Your knowledge is spread across multiple systems or repositories
You tell the agent which file to read at the start of every session

No friction yet? Your /docs is working. Keep it clean.

What AOL 3 gives you

Output consistency improves significantly. The agent has the context to act with clear intent - it is no longer inventing standards, it is enforcing yours. Code reviews become faster because the agent already knows what you will reject. The human in the loop spends less time correcting style and more time reviewing logic.

MEMORY.md - the project diary

Your /docs folder holds the standards you define. A MEMORY.md file holds what the agent has learned. Where /docs is prescriptive - how things should be done - MEMORY.md is operational: what decisions were made, what patterns emerged, what was tried and rejected.

The agent writes and updates MEMORY.md itself. It reads it at the start of each session alongside CLAUDE.md. Together, they give the agent two layers of context: your intent as the builder, and the accumulated history of the project. This is what makes AOL 3 the layer where institutional knowledge starts to live in the project rather than in your head.

/docs

Standards and patterns you define. Prescriptive. The blueprint.

MEMORY.md

Decisions and learnings the agent accumulates. Operational. The project diary.

What AOL 3 does not give you

The agent still needs to be told to use the docs. It reads them when relevant, but it does not actively apply them on its own initiative. That comes at AOL 4 with Skills.

There is also a risk in the other direction: if your docs are messy, outdated, or unclear, the agent will confidently follow bad instructions. A wrong blueprint is worse than no blueprint. AOL 3 forces you to keep your documentation honest.

Chat is for exploration. Docs are for systems.

Starter files

/docs Folder - Simple The five files that matter most, with template content and the CLAUDE.md snippet to connect them.

/docs Folder - Advanced Full structure with nested CLAUDE.md files, ADR format, and hierarchical orchestration.

MEMORY.md Starter The agent-maintained project diary - template, setup instructions, and the CLAUDE.md block to activate it.

Next step: AOL 4 - Capable

Give the agent custom tools for repeatable tasks. It picks up the right skill for each job and executes it with precision.

See AOL 4