Agent Lore

The problem with monolithic docs

A 2000-line CLAUDE.md wastes tokens. Agents read the whole file on every message, even when they only need one section.

Progressive disclosure pattern

Layer your documentation:

CLAUDE.md              # 100-200 lines: overview, commands, key conventions
docs/
  architecture.md      # Deep dive: data flow, module responsibilities
  api.md               # Endpoint reference
  deployment.md        # Deploy steps and environment setup
  conventions.md       # Detailed coding standards

CLAUDE.md as an index

## Architecture
ES module app with state management. See `docs/architecture.md` for details.

## API
REST endpoints at /api/v1/. See `docs/api.md` for the full reference.

The agent reads only CLAUDE.md initially. It follows links to deeper docs only when the task requires them.

Benefits

• Lower token cost (smaller initial context)
• Faster agent orientation
• Easier maintenance (update one section without touching others)
• Works with both Claude and Cursor

Rule of thumb

If a section in CLAUDE.md exceeds 50 lines, extract it to its own file and leave a one-line reference.