mirror of
https://github.com/bahdotsh/wrkflw.git
synced 2026-05-18 05:05:35 +02:00
05ed4d12b4
Add CLAUDE.md, AGENTS.md, and INDEX.md — all generated by the indxr MCP tooling to give AI coding assistants a structured way to explore the codebase without dumping entire files into context. CLAUDE.md is the detailed version with token cost estimates and a full tool reference. AGENTS.md is the condensed version. INDEX.md is an auto-generated codebase index with file summaries and symbol maps. While at it, add .indxr-cache/ to .gitignore because nobody needs that in the repo.
67 lines
4.4 KiB
Markdown
67 lines
4.4 KiB
Markdown
# wrkflw
|
|
|
|
## Codebase Navigation — MUST USE indxr MCP tools
|
|
|
|
An MCP server called `indxr` is available. **Always use indxr tools before the Read tool.** Do NOT read full source files as a first step — use the MCP tools to explore, then read only what you need.
|
|
|
|
### Token savings reference
|
|
|
|
| Action | Approx tokens | When to use |
|
|
|--------|--------------|-------------|
|
|
| `get_tree` | ~200-400 | First: understand directory layout |
|
|
| `get_file_summary` | ~200-400 | Understand a file without reading it |
|
|
| `batch_file_summaries` | ~400-1200 | Summarize multiple files in one call |
|
|
| `get_file_context` | ~400-600 | Understand dependencies and reverse deps |
|
|
| `lookup_symbol` | ~100-200 | Find a specific function/type across codebase |
|
|
| `search_signatures` | ~100-300 | Find functions by signature pattern |
|
|
| `search_relevant` | ~200-400 | Find files/symbols by concept or partial name (supports `kind` filter) |
|
|
| `explain_symbol` | ~100-300 | Everything to USE a symbol without reading its body |
|
|
| `get_public_api` | ~200-500 | Public API surface of a file or module |
|
|
| `get_callers` | ~100-300 | Who references this symbol (imports + signatures) |
|
|
| `get_related_tests` | ~100-200 | Find tests for a symbol by naming convention |
|
|
| `get_diff_summary` | ~200-500 | Structural changes since a git ref (vs reading raw diffs) |
|
|
| `get_hotspots` | ~200-500 | Most complex functions ranked by composite score |
|
|
| `get_health` | ~200-400 | Codebase health summary with aggregate complexity metrics |
|
|
| `get_type_flow` | ~200-500 | Track which functions produce/consume a type across the codebase |
|
|
| `read_source` (symbol) | ~50-300 | Read one function/struct. Supports `symbols` array and `collapse`. |
|
|
| `get_token_estimate` | ~100 | Check cost before reading. Supports `directory`/`glob`. |
|
|
| `Read` (full file) | **500-10000+** | ONLY when editing or need exact formatting |
|
|
|
|
### Exploration workflow (follow this order)
|
|
|
|
1. `search_relevant` — find files/symbols related to your task by concept, partial name, or type pattern. **Start here when you know what you're looking for but not where it is.**
|
|
2. `get_tree` — see directory/file layout. Use `path` param to scope to a subtree.
|
|
3. `get_file_summary` — get a complete overview of any file without reading it. Use `batch_file_summaries` for multiple files.
|
|
4. `get_file_context` — understand a file's reverse dependencies and related files.
|
|
5. `lookup_symbol` — find declarations by name across all indexed files.
|
|
6. `explain_symbol` — get full interface details for a symbol without reading its body.
|
|
7. `search_signatures` — find functions/methods by signature substring.
|
|
8. `get_callers` — find who references a symbol.
|
|
9. `get_token_estimate` — before deciding to `Read` a file, check how many tokens it costs.
|
|
10. `read_source` — read source code by symbol name or line range. Use `symbols` array to read multiple in one call.
|
|
11. `get_public_api` — get only public declarations with signatures for a file or directory.
|
|
12. `get_related_tests` — find test functions for a symbol.
|
|
13. `list_declarations` — list all declarations in a file.
|
|
14. `get_imports` — get import statements for a file.
|
|
15. `get_stats` — codebase stats: file count, line count, language breakdown.
|
|
16. `get_diff_summary` — get structural changes since a git ref.
|
|
17. `get_hotspots` — get the most complex functions ranked by composite score.
|
|
18. `get_health` — get codebase health summary: aggregate complexity, documentation coverage, test ratio.
|
|
19. `get_type_flow` — track where a type flows across function boundaries. Shows producers and consumers.
|
|
20. `regenerate_index` — re-index after code changes.
|
|
|
|
### When to use the Read tool instead
|
|
- You need to **edit** a file (Read is required before Edit)
|
|
- You need exact formatting/whitespace that `read_source` doesn't preserve
|
|
- The file is not a source file (e.g., config files, documentation)
|
|
|
|
### DO NOT
|
|
- Read full source files just to understand what's in them — use `get_file_summary`
|
|
- Read full source files to review code — use `get_file_summary` to triage, then `read_source` on specific symbols
|
|
- Dump all files into context — use MCP tools to be surgical
|
|
- Read a file without first checking `get_token_estimate` if you're unsure about its size
|
|
- Use `git diff` to understand changes — use `get_diff_summary` instead
|
|
|
|
### After making code changes
|
|
Run `regenerate_index` to keep INDEX.md current.
|