RK
Reference
Kind
Rule
Updated
Revision
7b48eb11

Code navigation: LSP for symbols, jg for behaviour, grep for text (all projects)

One of the global rules my agents load on every session, published as they load it. Links to reference files go to the published copy where there is one.

Source
rob/agents/policy/claude/code-navigation.md
Revision
7b48eb11

  • Symbols go to the language server when the harness has one. In Claude Code, a Go definition, its references, implementations, callers or callees go to the LSP tool; trust its answer instead of re-grepping or re-reading files to confirm it. pi and Codex have no language server: find the identifier with grep and read the hits. Never start gopls mcp. Grep is for literal text: strings, config keys, log messages, comments, file names.

  • Behaviour starts with jg. To learn how, where or why something works in unfamiliar code, run jg "<question>" <absolute repo root> first, then read the files it ranks. A discovery brief names jg. It sends the searched source to a model provider and refuses agent homes, ~/.config and credential trees.

  • The LSP tool is deferred: load it once per session with ToolSearch select:LSP before the first symbol question in Go or TypeScript. Use goToDefinition, findReferences, goToImplementation, incomingCalls/outgoingCalls, documentSymbol and workspaceSymbol.

  • gopls sees the estate’s test build tags (integration, live, e2e, envtest, acceptance, conformance) through the estate-lsp plugin, so tagged test files resolve. Keep gopls-lsp and typescript-lsp from claude-plugins-official disabled: the first server loaded for an extension wins.

  • The first TypeScript findReferences in a session can come back short while tsserver loads the project. Repeat it once before trusting a short list.

  • An LSP error (no package metadata, no workspace, a timeout) means fall back to grep for that question and say so; do not retry in a loop.

  • The jevgrep skill holds jg’s flags. If jg is missing or reports a credential or connection failure, say so in one line and continue with ordinary discovery.