How to Cache Your Codebase for AI Agents
How to Cache Your Codebase for AI Agents
CLAUDE.md works great for small projects. You describe your project structure, key conventions, and common patterns. The AI reads it and has enough context to be useful. But once your codebase hits 50-60 files, CLAUDE.md stops scaling.
Why CLAUDE.md Breaks Down
A CLAUDE.md file for a large codebase faces a dilemma:
- Too brief and the AI does not know where to find things
- Too detailed and it consumes too much of the context window before any actual work begins
- Stale quickly - the codebase changes but the documentation does not keep up
At 50-60 files, you can still list every file with a one-line description. At 500 files, this approach is unworkable.
The Semantic Map Approach
Instead of describing your entire codebase upfront, build a semantic map - a searchable index that the AI agent can query on demand:
- Extract signatures - function names, class definitions, type exports for every file
- Generate summaries - one-sentence description of what each module does
- Map dependencies - which files import from which other files
- Tag by domain - group files by feature area (auth, payments, UI, etc.)
Store this as a structured file (JSON or YAML) that the agent can search rather than read sequentially.
How to Build It
# Generate a codebase map
find src -name "*.ts" | while read f; do
echo "File: $f"
head -5 "$f" # First 5 lines usually have imports and description
echo "---"
done > .codebase-map.txt
Better tools exist - tree-sitter can extract AST-level information, and embeddings can make the map semantically searchable. But even a simple grep-able file of function signatures is dramatically better than no map.
The Agent Workflow
With a semantic map, the agent's workflow becomes:
- Read the task description
- Search the semantic map for relevant files
- Load only those files into context
- Do the work
- Update the semantic map if files changed
This keeps the context window focused on what matters and scales to codebases of any size.
Fazm is an open source macOS AI agent. Open source on GitHub.