نمط التحقيق التدريجي

When Claude Code lands in an unfamiliar codebase, dumping every file into context is wasteful and unreliable. Large blobs trigger lost-in-the-middle: the model attends to the start and end of context far more than the middle, so facts buried in a giant paste get missed.

The Incremental Investigation Pattern solves this. Instead of loading everything, Claude follows a deliberate chain that widens understanding one verified step at a time, pulling only the files that matter.

The canonical loop for built-in tools is:

• Grep entry points — search file contents to locate where a feature begins.
• Read files — load the matched files to understand the definition.
• Grep usages — search for everywhere that symbol is referenced.
• Read consumers — open the call sites to see how it is actually used.

Each step narrows the search space using evidence from the previous step. You never guess which files matter — the codebase tells you.

This pattern leans on Claude Code's built-in tools. Know exactly what each does:

• Glob — find files by name pattern, e.g. **/*.test.tsx.
• Grep — search inside file contents.
• Read — load a single file into context.
• Edit — make a precise, unique-match change.
• Bash — run shell commands.

Incremental investigation is built almost entirely from Grep and Read — search to discover, read to confirm.

Start by searching for the symbol or string that anchors the feature. You are looking for the definition, not every mention yet. A focused query keeps the result set small and relevant.

Searching contents (Grep) beats opening directories blindly: the match points you straight at the file that defines the behavior you care about.

Open only the file (or files) the Grep surfaced. Now you read the actual implementation: its inputs, return values, and the other symbols it depends on. Those dependencies become the seeds for your next search.

This is the discipline of the pattern — you Read after you Grep, so every file you load is one the evidence already justified.

Now flip direction. You understand the definition; next find who calls it. Grep for the symbol name across the codebase to enumerate every consumer.

This answers the questions that matter for a safe change: How many call sites exist? Do they pass the arguments correctly? Will an edit here ripple outward?

Open the call sites the usage-Grep returned. Reading consumers reveals real-world behavior the definition alone can't show: edge cases, error handling, and assumptions each caller makes.

With definition and consumers understood, you now have a complete, evidence-backed picture — without ever loading the whole repository.

Grep and Read can return verbose output. Don't let it pile up — trim verbose tool output to the relevant fields before it crowds your context window.

Keeping context lean directly fights lost-in-the-middle: a smaller, sharper context means the facts you gathered stay near the model's attention rather than buried in noise. Each step should add signal, not bulk.

Two discovery tools, two jobs:

• Glob when you know the file shape — "all test files", "every migration" — e.g. **/*.test.tsx.
• Grep when you know a symbol or string inside the code and need to find where it lives or who uses it.

Incremental investigation usually opens with Grep (you're chasing a symbol), and reaches for Glob when you want to scope by file type.

Use a fixed pipeline / prompt chain when the steps are known and sequential. But investigation is open-ended, so this pattern is best run with adaptive decomposition — the model chooses the next Grep or Read based on what the last step revealed.

Drive it through the agentic loop: each tool result returns stop_reason: "tool_use", you append the result to history, and the model decides the next move. Terminate on end_turn — never by scanning text for words like "done".

If you delegate investigation to a subagent, give it a tightly scoped toolset. 4-5 tools per agent is optimal; 18+ degrades selection reliability. An investigator needs little more than Glob, Grep, and Read.

Apply least privilege: a read-only explorer should NOT hold Edit, Write, or Bash. And remember subagents do not inherit the coordinator's history — pass the target symbol, the goal, and any prior findings explicitly in the prompt.

Key takeaways:

• Grep entry points → Read files → Grep usages → Read consumers. Evidence guides every step.
• Avoid loading whole repos — large context causes lost-in-the-middle; trim tool output to relevant fields.
• Grep finds symbols in content; Glob finds files by pattern.
• Run it as adaptive investigation through the agentic loop; terminate on end_turn, never on text like "done" or a hard iteration cap.
• A delegated explorer stays read-only (Glob, Grep, Read), keeps to 4-5 tools, and gets all context passed explicitly.

Investigate like an architect: search to discover, read to confirm, edit with confidence.