48 lines
2.6 KiB
Markdown
48 lines
2.6 KiB
Markdown
|
## Code Graph First (mandatory)
|
||
|
|
|
||
|
|
Before any cross-file understanding or change, query the code graph first. Do
|
||
|
|
NOT grep + read whole files to reconstruct relationships.
|
||
|
|
|
||
|
|
- **Session start**: run `codegraph_status` to confirm the graph is built; if
|
||
|
|
empty, run `codegraph init -i` from the project root once. The graph persists
|
||
|
|
and is reused for the whole session.
|
||
|
|
- **Trust but verify stats**: `codegraph_status` can return a stale or partial
|
||
|
|
snapshot. If counts look low, run `codegraph_status` again — codegraph
|
||
|
|
auto-syncs on file changes (2s debounce via native OS file watcher).
|
||
|
|
Do not run structural queries against a graph you suspect is incomplete.
|
||
|
|
- **Structural questions** ("who calls / what depends on / where defined / what
|
||
|
|
breaks if I change this") MUST use `codegraph_explore` (primary, for flows and
|
||
|
|
surveys), `codegraph_search` (locate symbols), `codegraph_callers` (every call
|
||
|
|
site).
|
||
|
|
Do not piece relationships together from grep + read output.
|
||
|
|
- **Reading an implementation**: use `read(filePath, symbol: "<name>")` to fetch
|
||
|
|
only the target symbol's line range. Do not read an entire large file to see
|
||
|
|
one function.
|
||
|
|
- **grep is the fallback, not the default**: use grep only for fuzzy text the
|
||
|
|
graph cannot answer (comments, string literals, config text). Use
|
||
|
|
`codegraph_node` with `symbolsOnly: true` for a cheap structural overview instead of Glob.
|
||
|
|
- **Delegate exploration**: prefer running graph + read inside an Explorer
|
||
|
|
subagent and returning only `file:line` results and conclusions, to keep the
|
||
|
|
main context lean.
|
||
|
|
|
||
|
|
## Per-worktree indexes (mandatory for worktree sessions)
|
||
|
|
|
||
|
|
The main checkout's `.codegraph/` indexes ONLY that tree. A git worktree lives
|
||
|
|
outside the repo path, so nearest-`.codegraph/` resolution finds nothing under
|
||
|
|
it — graph queries in a workflow worktree silently degrade to grep+read
|
||
|
|
(the [org-internal #2561] / TD-006 gap).
|
||
|
|
|
||
|
|
- `script/session-worktree.sh create` and `script/scratch-worktree.sh create`
|
||
|
|
build a per-worktree index automatically: `codegraph init -i <path>` runs in
|
||
|
|
the background (best-effort — missing CLI, existing index, or init failure
|
||
|
|
never blocks worktree creation). Set `CODEGRAPH_SKIP=1` to disable
|
||
|
|
(selftests / CI).
|
||
|
|
- Worktrees created BEFORE this hook landed have no index: run
|
||
|
|
`codegraph init -i` once from inside them.
|
||
|
|
- First query after creating a worktree may hit a still-building index; if
|
||
|
|
results look empty, check `codegraph status` inside the worktree, then retry.
|
||
|
|
- Kickoff readiness (`checkCodegraph`) checks `<root>/.codegraph/codegraph.db`
|
||
|
|
per root, and `codegraph serve --mcp` resolves from the session's cwd — both
|
||
|
|
pick the worktree's own index once it exists.
|
||
|
|
|