upstream-atomic-crm/.claude/rules/lsp-usage.md

LSP — use semantic code intelligence when possible

Applies to: developer, quality-reviewer, planner.

This repo has an LSP tool backed by a TypeScript language server (configured in .claude/settings.json, covering .ts, .tsx, .mjs, .js, and .jsx). Use it for any semantic question about TypeScript/JavaScript code. It resolves symbols through the type system, so it is exact where text search only guesses.

The reflex to break: grep/rg in Bash to find a symbol

In practice the Grep tool is rarely used — code search here happens through grep/rg inside Bash (grep -rn "DealStage" src/). That reflex is the thing to stop for symbol questions. grep matches strings: it can't tell a definition from a comment, a type from a same-named variable, or one handleSubmit from another, and it silently misses re-exports and aliased imports. The LSP tool resolves the actual symbol.

Hard rule: to find where a TypeScript identifier (a PascalCase type/component, a camelCase function/hook, an exported const) is defined or used in .ts/.tsx/.js/.jsx, call LSP — never grep -rn "<Symbol>" src/ in Bash and never the Grep tool. Reach for LSP first whenever the question is "where / what / who", not "which files contain this string".

Instead of this bash-grep…	…use this LSP call
grep -rn "DealStage" src/ (every use of a type)	findReferences (impact/blast radius)
grep -rn "mergeContacts" src/ (where defined)	goToDefinition
grep -rn "LatestNotes|useContactImport" src/ (locate a symbol)	workspaceSymbol
grep -n "export" file.tsx (what a file exports)	documentSymbol
grep -rn "buildActivityLog" src/ (who calls it)	incomingCalls

Operation	Use it to
goToDefinition	jump to where a symbol is declared (type, function, component, prop)
findReferences	find every real use of a symbol before changing or renaming it — impact analysis
hover	get a symbol's resolved type / signature / JSDoc without opening its file
documentSymbol	outline a file's exports/functions/components before reading it whole
workspaceSymbol	locate a symbol by name across the repo (query required) — faster than grepping for a file path
goToImplementation	find concrete implementations of an interface or abstract member
prepareCallHierarchy	get the call-hierarchy anchor at a position (precedes incoming/outgoing calls)
incomingCalls / outgoingCalls	trace the call graph into / out of a function

Positions are 1-based (line, character), exactly as shown in Read output and editors.

Per-agent fit

• developer — before editing a symbol's signature, findReferences to size the blast radius; hover to confirm a type; goToDefinition to reach the source. Do not grep -rn "<Symbol>" src/ in Bash to answer these — that is the exact reflex this rule replaces.
• quality-reviewer — findReferences / incomingCalls to check that every call site of a changed function is handled; goToDefinition to confirm a type is what the diff assumes; findReferences / workspaceSymbol to confirm a new component or resource is actually wired into the app (imported, registered), not merely created.
• planner — workspaceSymbol to locate probable files_to_modify faster than grep. Still light discovery — no deep reading.

When grep/rg IS the right tool

LSP is for TS/JS symbols. Keep using grep/rg (in Bash) — and do not try LSP — for:

• Non-TS/JS files: .sql, .md, .json, .css — no server covers them.
• Text / domain-word sweeps that deliberately include strings, comments, and non-code: e.g. deleting a resource with grep -rniE "\bdeals?\b|deal_notes?", which must catch SQL, fixtures, and labels — not just the TS symbol.
• Database identifiers (column / view names like company_id, contacts_summary) that live in SQL and string literals, not as TS symbols.
• Plain "which files mention 'boulangerie'" lookups.

LSP is read-only code intelligence, not a validation command — it does not run tsc, so it is exempt from validation-commands.md and you may use it freely. It does not replace the hook-run typecheck.

Worktree note

Pass absolute paths inside your own worktree (<WORKTREE_PATH>/src/...), per worktree-scope.md — never the base-branch checkout under $CLAUDE_PROJECT_DIR. Fall back to grep / Read only when LSP returns an actual error or empty result for a worktree file — not as the default. Do not block on it.