Agent Lore

The cold-start problem

Jumping into an unfamiliar codebase wastes time if you (or your AI agent) don't know where to look. Here's a systematic approach.

Step 1: Read the entry points

1. README.md -- what the project does
2. CLAUDE.md / .cursorrules -- AI-specific context
3. package.json / Makefile / Cargo.toml -- commands and deps
4. Directory listing (top-level only)

Step 2: Use explore agents

In Cursor, launch an explore agent:

"Explore the codebase and explain the architecture. Focus on data flow and key entry points."

In Claude Code, use the Task tool with subagent_type="explore":

"Explore the src/ directory. Map the module structure and identify the main entry point, routing, and data layer."

Step 3: Build a mental model

Ask targeted questions:

• "Where does authentication happen?"
• "How does data flow from the API to the UI?"
• "What are the key abstractions?"

Step 4: Write what you learned

Create or update CLAUDE.md with what you discovered. Future sessions (yours or someone else's) will start faster.

Anti-patterns

• Reading every file top-to-bottom (too slow)
• Skipping README and guessing (too error-prone)
• Asking vague questions like "explain everything" (too broad)