用 Sourcegraph MCP…

当需要通过 Sourcegraph MCP 工具搜索或导航代码时，按工具选择逻辑、作用域限定和高效查询模式来定位实现、理解系统、调试问题、修复 bug 或审查代码。

适用场景

解决思路

1. 先搜索再动手构建：复用已有模式可减少 token、保证一致性并发现经过测试的方案。
2. 按工具选择逻辑起步：知道确切符号或模式用 keyword_search；知道概念但不知道代码用 nls_search；需要理解 how/why 用 deepsearch 再 deepsearch_read；追踪符号用法用 find_references；需要完整实现用 go_to_definition 再 read_file；需要知道用户参与过哪些仓库用 get_contributor_repos。
3. 按目标选工具：概念/语义搜索用 nls_search；精确代码模式用 keyword_search；追踪用法用 find_references；查看实现用 go_to_definition；发起深度搜索用 deepsearch；读取深度搜索结果用 deepsearch_read；读文件用 read_file；浏览结构用 list_files；查找仓库用 list_repos；搜索提交用 commit_search；跟踪变更用 diff_search；比较版本用 compare_revisions；查找某用户参与过的仓库用 get_contributor_repos。
4. 始终做作用域限定：用 repo:^github.com/ORG/REPO$ 精确到仓库（首选）、repo:github.com/ORG/ 限定组织下所有仓库、file:.*\.ts$ 限定 TypeScript、file:src/api/ 限定目录、file:.*\.test\.ts$ -file:__mocks__ 限定测试并排除 mocks。
5. 从窄范围开始，只有在结果为空时才扩大范围。
6. 组合过滤器，例如 repo:^github.com/myorg/backend$ file:src/handlers lang:typescript。
7. 当用户提供文件路径或错误信息时：提取符号、函数名或错误码，先搜索这些确切词，若错误涉及已知符号则追踪引用。
8. 当用户问“X 如何工作”时：用 deepsearch 发起搜索，再用 deepsearch_read 获取结果，随后对响应中提到的关键文件用 read_file 跟进。
9. 当用户问谁做过某事或某贡献者碰过哪些仓库时：用 get_contributor_repos 传入一个或多个用户名发现其活跃仓库，再把后续搜索限定到这些仓库。
10. 当用户实现新功能时：先搜索类似的已有实现，阅读测试获取用法示例，在创建新工具前检查是否有共享工具可复用。
11. 当排查错误、构建失败或运行时异常时：从堆栈跟踪或构建输出中提取确切符号、错误码或日志行，搜索错误发生点，再用 find_references 追踪完整调用链，尽早用 diff_search 和 commit_search 检查近期变更（回归很常见），在提出修复前识别所有受影响的代码路径和服务。
12. 当修复 bug 时：从错误信息或堆栈跟踪中提取确切符号，搜索错误发生点，再用 find_references 追踪完整调用链，尽早用 diff_search 和 commit_search 检查近期变更（回归很常见），在写修复前找出所有受影响的代码路径，阅读已有测试以理解预期行为。
13. 需要详细分步工作流时参考：实现新功能看 workflows/implementing-feature.md；探索不熟悉系统看 workflows/understanding-code.md；排查错误、构建失败、堆栈跟踪、支持问题或运行时异常看 workflows/debugging-issue.md；用大量 Sourcegraph 搜索修 bug 看 workflows/fixing-bug.md；审查 PR 或变更集看 workflows/code-review.md。
14. 减少工具调用：按 search → read → references → definition 逻辑串联搜索；不要对同一模式重复搜索，复用之前调用的结果；有确切词时优先用 keyword_search 而非 nls_search（更快更精确）。
15. 批量理解：在综合前先读 2-3 个相关文件，而不是读一个就问问题；用 deepsearch + deepsearch_read 回答“X 如何工作”，而不是多次 keyword_search。
16. 避免常见 token 浪费：已知目标仓库时不要搜索所有仓库；简单“找出全部”查询不要用 deepsearch，keyword_search 更快；不要重复阅读本次对话中已看过的文件。
17. 使用查询模式：React hooks 用 file:.*\.tsx$ use[A-Z].*= \(；API 路由用 file:src/api app\.(get|post|put|delete)；错误处理用 catch.*Error|\.catch\(；类型定义用 file:types/ export (interface|type)；测试设置用 file:.*\.test\. beforeEach|beforeAll；配置文件用 file:(webpack|vite|rollup)\.config；CI/CD 用 file:\.github/workflows deploy。更多模式见 query-patterns.md。
18. 输出格式化——搜索结果：以简要摘要呈现而非原始工具输出，突出最相关的文件和行，仅当代码片段直接回答问题时才包含它。
19. 输出格式化——代码解释：以一句话总结开头，使用代码库自身的术语，引用具体文件和函数。
20. 输出格式化——建议：可操作时以编号步骤呈现，链接到代码库中找到的具体模式，注明应复用的已有工具。
21. 避免常见错误：搜索所有仓库→加上 repo:^github.com/org/repo$；结果太多→加 file: 模式或关键词；遗漏相关代码→尝试 nls_search 做语义匹配；不理解上下文→用 deepsearch_read；猜测模式→用 read_file 阅读实现。
22. 遵循原则：从窄范围开始，必要时扩大；串联工具 search → read → find references → definition；检查测试获取用法示例；先阅读再生成。