tools-code-search

Code search and targeted reading

Local search is the first evidence pass. It discovers where the architecture is implemented before heavier tools spend time proving graph or semantic facts.

Evidence dimensions: discovery and lightweight structural context.

When to use

Use during the system-map step and whenever a finding needs scoped file:line support before graph, AST, LSP, or language-tool confirmation. Good questions:

• Where are the entrypoints, deploy units, public interfaces, and package roots?
• Which files mention a domain concept, config key, route, queue, or dependency?
• Which modules import a boundary package or framework type?
• What docs, ADRs, manifests, or ownership files describe intended structure?
• Which exact files should the review read next?

This skill supports architecture-review; it does not assign architecture scores or make findings by itself.

Commands

Run from the repo root. Prefer fd for paths and rg for text. Use the runtime's file-read tool for targeted reads after search narrows the scope.

# High-signal structure and intent files
fd -H '(^README|CONTEXT|ARCHITECTURE|adr|decisions|ownership|CODEOWNERS|package.json|pyproject.toml|go.mod|Chart.yaml|kustomization.yaml|Dockerfile|\.github)' .

# Files by language / package marker
fd 'package.json|tsconfig.json|pyproject.toml|requirements.txt|go.mod|main.tf|Chart.yaml|kustomization.yaml'

# Exact concepts, routes, config keys, or dependency names
rg -n --hidden --glob '!{.git,node_modules,dist,build,vendor}/**' 'Order|Payment|Auth|Session|Repository|Controller|Handler|typeorm|sqlalchemy|kafka|redis'

# Import/dependency hints before AST or graph tools
rg -n --glob '!{.git,node_modules,dist,build,vendor}/**' "from ['\"]|import |require\(|package "

# Git-tracked scope, useful for generated/vendor exclusion
git ls-files

# Change hints when GitNexus is missing or stale
git log --name-only --pretty=format: -- <path> | sort | uniq -c | sort -nr | head

Prefer git grep -n <pattern> when the review should ignore untracked/generated files and only search the versioned source. If the target is not a git repo, record that limit and use scoped fd / rg instead.