mirror of
https://github.com/colbymchenry/codegraph.git
synced 2026-09-19 07:34:57 +08:00
Colby McHenry
82fc599d8d
Replaces the old Claude-only CLAUDE.md with a comprehensive guide covering the full project architecture, multi-agent installer, test conventions, NodeKind/EdgeKind reference, and release workflow. Key additions: - Documents the layered pipeline, all module paths, and the multi-target installer (targets/, registry.ts, AgentTarget interface). - Adds the Cursor `--path` quirk and the "update all three surfaces" rule when changing MCP tool guidance. - Documents `npm run eval`, `test:eval`, and the full set of build/test commands including single-file patterns. - `scripts/release.sh` — idempotent bash script that tags the current commit, pushes the tag, and creates a GitHub Release whose notes are extracted from the matching `## [X.Y.Z]` block in CHANGELOG.md. Safe to re-run after partial failure. - `.cursor/rules/codegraph.mdc` — Cursor-specific agent instructions (tool decision table, rules of thumb, index-lag warning) written by the installer and kept in sync with server-instructions.ts and instructions-template.ts.
38 lines
2.3 KiB
Plaintext
38 lines
2.3 KiB
Plaintext
---
|
|
description: CodeGraph MCP usage guide — when to use which tool
|
|
alwaysApply: true
|
|
---
|
|
<!-- CODEGRAPH_START -->
|
|
## CodeGraph
|
|
|
|
This project has a CodeGraph MCP server (`codegraph_*` tools) configured. CodeGraph is a tree-sitter-parsed knowledge graph of every symbol, edge, and file. Reads are sub-millisecond and return structural information grep cannot.
|
|
|
|
### When to prefer codegraph over native search
|
|
|
|
Use codegraph for **structural** questions — what calls what, what would break, where is X defined, what is X's signature. Use native grep/read only for **literal text** queries (string contents, comments, log messages) or after you already have a specific file open.
|
|
|
|
| Question | Tool |
|
|
|---|---|
|
|
| "Where is X defined?" / "Find symbol named X" | `codegraph_search` |
|
|
| "What calls function Y?" | `codegraph_callers` |
|
|
| "What does Y call?" | `codegraph_callees` |
|
|
| "What would break if I changed Z?" | `codegraph_impact` |
|
|
| "Show me Y's signature / source / docstring" | `codegraph_node` |
|
|
| "Give me focused context for a task/area" | `codegraph_context` |
|
|
| "Survey an unfamiliar module/topic" | `codegraph_explore` |
|
|
| "What files exist under path/" | `codegraph_files` |
|
|
| "Is the index healthy?" | `codegraph_status` |
|
|
|
|
### Rules of thumb
|
|
|
|
- **Trust codegraph results.** They come from a full AST parse. Do NOT re-verify them with grep — that's slower, less accurate, and wastes context.
|
|
- **Don't grep first** when looking up a symbol by name. `codegraph_search` is faster and returns kind + location + signature in one call.
|
|
- **Don't chain `codegraph_search` + `codegraph_node`** when you just want context — `codegraph_context` is one call.
|
|
- **`codegraph_explore` is the heavy hitter** for unfamiliar areas — it returns full source from all relevant files in one call, but is token-heavy. If your harness supports parallel subagents (e.g., Claude Code's Task tool), spawn one for explore-class questions to keep main session context clean.
|
|
- **Index lag**: the file watcher debounces ~500ms behind writes; don't re-query immediately after editing a file in the same turn.
|
|
|
|
### If `.codegraph/` doesn't exist
|
|
|
|
The MCP server returns "not initialized." Ask the user: *"I notice this project doesn't have CodeGraph initialized. Want me to run `codegraph init -i` to build the index?"*
|
|
<!-- CODEGRAPH_END -->
|