Searching Sourcegraph

Search before you build. Existing patterns reduce tokens, ensure consistency, and surface tested solutions.

Tool Selection Logic

Start here:

• Know the exact symbol or pattern? → sg_keyword_search

• Know the concept, not the code? → sg_nls_search

• Need to understand how/why? → sg_deepsearch_read

• Tracing a symbol's usage? → sg_find_references

• Need full implementation? → sg_go_to_definition → sg_read_file

Goal Tool

Concepts/semantic search sg_nls_search

Exact code patterns sg_keyword_search

Trace usage sg_find_references

See implementation sg_go_to_definition

Understand systems sg_deepsearch_read

Read files sg_read_file

Browse structure sg_list_files

Find repos sg_list_repos

Search commits sg_commit_search

Track changes sg_diff_search

Compare versions sg_compare_revisions

Scoping (Always Do This)

repo:^github.com/ORG/REPO$ # Exact repo (preferred) repo:github.com/ORG/ # All repos in org file:..ts$ # TypeScript only file:src/api/ # Specific directory file:..test.ts$ -file:mocks # Tests, exclude mocks

Start narrow. Expand only if results are empty.

Combine filters: repo:^github.com/myorg/backend$ file:src/handlers lang:typescript

Context-Aware Behaviour

When the user provides a file path or error message:

• Extract symbols, function names, or error codes

• Search for those exact terms first

• Trace references if the error involves a known symbol

When the user asks "how does X work":

• Prefer sg_deepsearch_read for architectural understanding

• Follow up with sg_read_file on key files mentioned in the response

When the user is implementing a new feature:

• Search for similar existing implementations first

• Read tests for usage examples

• Check for shared utilities before creating new ones

When fixing a bug:

• Extract exact symbols from the error message or stack trace

• Search for the error site, then trace the full call chain with sg_find_references

• Check recent changes with sg_diff_search and sg_commit_search early — regressions are common

• Find all affected code paths before writing the fix

• Read existing tests to understand intended behaviour

Workflows

For detailed step-by-step workflows, see:

• workflows/implementing-feature.md — when building new features

• workflows/understanding-code.md — when exploring unfamiliar systems

• workflows/debugging-issue.md — when tracking down bugs

• workflows/fixing-bug.md — when fixing bugs with extensive Sourcegraph search

• workflows/code-review.md — when reviewing a pull request or changeset

Efficiency Rules

Minimise tool calls:

• Chain searches logically: search → read → references → definition

• Don't re-search for the same pattern; use results from prior calls

• Prefer sg_keyword_search over sg_nls_search when you have exact terms (faster, more precise)

Batch your understanding:

• Read 2-3 related files before synthesising, rather than reading one and asking questions

• Use sg_deepsearch_read for "how does X work" instead of multiple keyword searches

Avoid common token waste:

• Don't search all repos when you know the target repo

• Don't use sg_deepsearch_read for simple "find all" queries

• Don't re-read files you've already seen in this conversation

Query Patterns

Intent Query

React hooks file:..tsx$ use[A-Z].= (

API routes file:src/api app.(get|post|put|delete)

Error handling catch.*Error|.catch(

Type definitions file:types/ export (interface|type)

Test setup file:.*.test. beforeEach|beforeAll

Config files file:(webpack|vite|rollup).config

CI/CD file:.github/workflows deploy

For more patterns, see query-patterns.md .

Output Formatting

Search results:

• Present as a brief summary, not raw tool output

• Highlight the most relevant file and line

• Include a code snippet only if it directly answers the question

Code explanations:

• Start with a one-sentence summary

• Use the codebase's own terminology

• Reference specific files and functions

Recommendations:

• Present as numbered steps if actionable

• Link to specific patterns found in the codebase

• Note any existing utilities that should be reused

Common Mistakes

Mistake Fix

Searching all repos Add repo:^github.com/org/repo$

Too many results Add file: pattern or keywords

Missing relevant code Try sg_nls_search for semantic matching

Not understanding context Use sg_deepsearch_read

Guessing patterns Read implementations with sg_read_file

Principles

• Start narrow, expand if needed

• Chain tools: search → read → find references → definition

• Check tests for usage examples

• Read before generating