pablodiazjorge Codebase Exploration Playbook
Golden Rules
- First: check for errors —
get_errors()before anything else. Fixing compile errors is priority zero. - NEVER read files one by one —
grep_searchwith regex alternation first semantic_searchfor concepts,grep_searchfor exact symbolsfile_searchfor globs to discover structure instantly- Read 100+ lines at a time — fewer reads = fewer tokens
- Parallel reads — read 2-3 key files in one turn
- Avoid the "grep tax" — use familiar formats (Markdown/YAML), not obscure ones
Progressive Disclosure (Skill Pattern)
Top coding agents (Codex, Claude Code) use this — do the same:
- Metadata (~100 tokens): name + description loaded for ALL files
- Instructions (< 500 lines): body loaded when triggered
- Resources (on-demand): only files referenced via Markdown links
Strategy by Goal
| Goal | Approach |
|---|---|
| "Where is X?" | grep_search → vscode_listCodeUsages → read defining file |
| "How does this work?" | file_search("**/*.{ts,js}") → semantic_search("architecture") → read ONE key file deeply |
| "Find tests for Y" | file_search("**/Y*.spec.ts") — glob is instant |
| "What deps?" | read_file("package.json", 1, 100) — one read |
| "Are there errors?" | get_errors() FIRST — then grep for error symbols |
| "Find all imports of X" | grep_search("import.*X", isRegexp=true) across **/*.ts |
Tool Quick Reference
| Tool | Best for |
|---|---|
get_errors(filePaths) |
Always first — compile/lint errors |
grep_search(query, isRegexp, includePattern) |
Text/regex: `function |
semantic_search(query) |
Natural language: "how does auth work" |
file_search(query) |
Glob: **/*.spec.ts, **/*.component.ts |
read_file(path, start, end) |
Read 100+ line chunks (parallel when possible) |
vscode_listCodeUsages(symbol, lineContent) |
All references of a symbol |
list_dir(path) |
Directory listing |
Anti-Patterns
| Don't | Do |
|---|---|
| Read 15 files sequentially | Search first, read 2-3 key files in parallel |
| Read 20-line chunks | 100-200 lines at a time |
| Single-keyword searches | Regex alternation |
| Guess file locations | file_search with globs |
| Use obscure formats for context | Markdown/YAML — models know them best |
| Skip error checking | get_errors() as step 1 |
Token Economics
| Approach | Tokens |
|---|---|
| Sequential 15 files × 500 tokens | ~7,500 |
| With this playbook | ~700 |
| Savings | ~91% |