From 57ba3762fc7c1b0d9e5ae5d29777a39f98b94a60 Mon Sep 17 00:00:00 2001 From: Kevin Old Date: Thu, 15 Jan 2026 13:06:49 -0600 Subject: [PATCH 1/2] docs: Add LSP prioritization guidance for project CLAUDE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add "Customizing Agent Behavior" section to README with example CLAUDE.md snippets that projects can use to prioritize LSP tools over grep for code understanding. Includes both minimal (one-line) and detailed versions, plus guidance on when LSP vs grep is appropriate. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- plugins/compound-engineering/README.md | 54 ++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/plugins/compound-engineering/README.md b/plugins/compound-engineering/README.md index 13285453..25bdce81 100644 --- a/plugins/compound-engineering/README.md +++ b/plugins/compound-engineering/README.md @@ -183,6 +183,60 @@ MCP servers start automatically when the plugin is enabled. claude /plugin install compound-engineering ``` +## Customizing Agent Behavior + +Plugin agents read your project's `CLAUDE.md` before executing. You can add instructions to customize their behavior without modifying the plugin. + +### Example: LSP Prioritization + +To make agents prioritize LSP tools over grep for code understanding, add this to your project's `CLAUDE.md`: + +**Minimal version:** + +```markdown +## Code Search + +Prefer LSP operations for semantic code understanding; use grep for text patterns and config files. +``` + +**Detailed version:** + +```markdown +## Code Search Strategy + +When searching or analyzing code, prioritize LSP tools over grep/search: + +1. **LSP First** - Use LSP operations for semantic code understanding: + - `findReferences` - Find all usages of a symbol + - `goToDefinition` - Navigate to where a symbol is defined + - `documentSymbol` - List all symbols in a file + - `hover` - Get type info and documentation + - `incomingCalls` - Find callers of a function + - `outgoingCalls` - Find functions called by a function + +2. **Grep Second** - Fall back to grep/rg for: + - String literals and comments + - Config files (YAML, JSON, ENV) + - TODO/FIXME markers + - Files without LSP support (Markdown, templates) + +LSP provides compiler-accurate results; grep finds text patterns. +``` + +This influences agents like `repo-research-analyst`, `pattern-recognition-specialist`, and `security-sentinel` to use LSP operations before falling back to grep. + +**When to use LSP prioritization:** +- TypeScript/JavaScript projects (excellent LSP via tsserver) +- Python projects (good LSP via Pyright/Pylsp) +- Ruby projects (good LSP via ruby-lsp/Solargraph) +- Go projects (excellent LSP via gopls) + +**When grep is still appropriate:** +- Searching for hardcoded secrets (`password`, `API_KEY`, etc.) +- Finding TODO/FIXME comments +- Searching config files and environment variables +- Pattern matching across non-code files + ## Known Issues ### MCP Servers Not Auto-Loading From 9a31ba8375b04adf6b2477504d78aac9a9595d35 Mon Sep 17 00:00:00 2001 From: Kevin Old Date: Thu, 15 Jan 2026 14:08:05 -0600 Subject: [PATCH 2/2] docs: Align LSP prioritization with user CLAUDE.md conventions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Move documentSymbol to first position with "(ALWAYS START HERE)" - Add Agent Delegation section with sub-agent instruction - Add "(MANDATORY)" emphasis to header - Include Rust in supported languages - Add sub-agent awareness in introduction 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- plugins/compound-engineering/README.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/plugins/compound-engineering/README.md b/plugins/compound-engineering/README.md index 25bdce81..848e6df0 100644 --- a/plugins/compound-engineering/README.md +++ b/plugins/compound-engineering/README.md @@ -202,25 +202,33 @@ Prefer LSP operations for semantic code understanding; use grep for text pattern **Detailed version:** ```markdown -## Code Search Strategy +## Code Search Strategy (MANDATORY) -When searching or analyzing code, prioritize LSP tools over grep/search: +**This applies to ALL code search operations, including work delegated to sub-agents.** + +When searching or analyzing code - whether directly or via Task tool agents - prioritize LSP tools over rg: 1. **LSP First** - Use LSP operations for semantic code understanding: + - `documentSymbol` - List all symbols in a file (ALWAYS START HERE) - `findReferences` - Find all usages of a symbol - `goToDefinition` - Navigate to where a symbol is defined - - `documentSymbol` - List all symbols in a file - `hover` - Get type info and documentation - `incomingCalls` - Find callers of a function - `outgoingCalls` - Find functions called by a function -2. **Grep Second** - Fall back to grep/rg for: +2. **rg/Grep Second** - Fall back to text search ONLY for: - String literals and comments - Config files (YAML, JSON, ENV) - TODO/FIXME markers - Files without LSP support (Markdown, templates) -LSP provides compiler-accurate results; grep finds text patterns. +LSP provides compiler-accurate results; rg finds text patterns. + +### Agent Delegation + +When using the Task tool to spawn agents for code exploration, you MUST include this instruction in the prompt: + +> "Use LSP tools (documentSymbol, findReferences, goToDefinition, hover) before falling back to Grep/Glob for code search." ``` This influences agents like `repo-research-analyst`, `pattern-recognition-specialist`, and `security-sentinel` to use LSP operations before falling back to grep. @@ -228,6 +236,7 @@ This influences agents like `repo-research-analyst`, `pattern-recognition-specia **When to use LSP prioritization:** - TypeScript/JavaScript projects (excellent LSP via tsserver) - Python projects (good LSP via Pyright/Pylsp) +- Rust projects (excellent LSP via rust-analyzer) - Ruby projects (good LSP via ruby-lsp/Solargraph) - Go projects (excellent LSP via gopls)