AOL 2 - CLAUDE.md / AGENT.md | Resource Hub

The short version

CLAUDE.md is a file you place at the root of your project. It gives the agent its first real context - what the project is, how to build and test it, and what the main rules are. The agent reads it at the start of every session. This alone removes a significant amount of friction.

Requires APL 2 or APL 3 + AAL 3 An AI tool that reads your project files. Not a browser chat tab.

Why it is called the Map

Without a map, the agent has no context and no intent - it uses general training data to guess what your project might need. With a map, it has both. It stops guessing at the basics and can focus on the actual task.

This layer is built around CLAUDE.md - the project configuration file in Claude Code. Other AI coding tools use the same concept under different names. The principle is identical: one file that gives the agent a stable starting point for every session.

Without CLAUDE.md Agent starts every session lost. Uses general assumptions. You re-explain the project every time.

With CLAUDE.md Agent knows the project from the first message. Consistent starting point every session.

What belongs in CLAUDE.md

Must have

What the project is and what it does
How to run, build, and test the project
The main technologies and frameworks used
Rules the agent must follow (e.g. never use px, always use design tokens)

Good to have

Project folder structure explained
What the agent should never touch
Links to key files the agent should read first
Naming conventions

Avoid

Everything at once - keep it focused
Outdated information - a wrong map is worse than no map
Links to external URLs (agents cannot follow them reliably)

The three-layer strategy

One CLAUDE.md is a start. Three layers is structured intelligence. Each layer loads only where it is needed - global rules do not bleed into folder-specific context, and personal preferences never pollute team standards.

Root - /CLAUDE.md

Global rules: tech stack, build commands, architecture constraints, and a map pointing to your /docs files. Every session starts here.

Sub-folder - /src/api/CLAUDE.md

Folder-specific rules that only apply inside that folder. Loaded on demand, not globally. Less noise. More precision.

Local - CLAUDE.local.md

Your personal preferences. Add it to .gitignore. It does not affect the team's standards and does not get committed.

Keep it lean

Auto-generated CLAUDE.md files usually repeat what the agent can already see in your code. TypeScript is visible in package.json. Tailwind is visible in the config. Writing it again wastes tokens and creates drift when things move.

Traffic Controller pattern

Use CLAUDE.md as a pointer, not a library. Instead of writing all the API rules inline, write: "For API rules, read @docs/api.md. For UI rules, read @docs/style-guide.md. Do not guess - read the doc." The agent fetches only what it needs, when it needs it.

Rule of thumb: if the agent can find it by scanning the project (ls or grep), remove it from CLAUDE.md.

What AOL 2 gives you

You move out of the deepest part of the Friction Zone. The agent is no longer working blind. Output becomes more consistent because the agent has a stable reference point. Sessions get shorter because you no longer repeat basic context.

AOL 2 is the minimum viable setup for any ongoing project. If you are using Claude Code, Cursor, or any other agent tool on a real project without a map file, start here first.

What AOL 2 does not give you

CLAUDE.md is orientation, not expertise. The agent knows where it is, but it does not know your patterns, your design decisions, or the standards you have established. That is what AOL 3 adds.

The same principle in other tools

This guide uses Claude Code as the reference implementation. Every major AI coding tool has an equivalent file. The concept is identical - one file that gives the agent a stable starting point. The name and location differ.

Claude Code

CLAUDE.md

Placed at project root. Read automatically at session start.

Cursor

.cursor/rules/

Directory of .mdc rule files. Older versions used .cursorrules at the root.

Windsurf

.windsurfrules

Root-level file. Same pattern as CLAUDE.md - global rules for every session.

GitHub Copilot

.github/copilot-instructions.md

Stored in the .github folder. Applies to the whole repository.

Gemini CLI

GEMINI.md

Google's CLI agent reads this from the project root.

OpenAI Codex

AGENTS.md

Tool-agnostic name. Works as a cross-tool canonical file when you use multiple agents.

Pro tip - symlink for multi-agent setups

If you use more than one agent tool on the same project, you do not want to maintain separate copies of the same rules. Create one canonical file - CLAUDE.md or AGENTS.md - and symlink the others to it.

ln -s CLAUDE.md AGENTS.md
ln -s CLAUDE.md GEMINI.md

One source of truth. Every agent reads the same rules. No drift between tool configs.

Starter file

CLAUDE.md Starter A clean template with the structure that matters. Delete what does not apply, keep what does.

Next step: AOL 3 - Informed

Move from orientation to expertise. Give the agent the blueprint of how your project is supposed to work.

See AOL 3