Claude Architect · Lesson

Incremental Investigation Pattern

Grep entry points, Read files, Grep usages, Read consumers.

Incremental Investigation Pattern is a free Claude Architect lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Claude Architect learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Why Investigate Incrementally

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 Four-Step Chain

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.

# Conceptual flow with Claude Code built-in tools
# 1) Grep -> find entry points
# 2) Read  -> the matched definition files
# 3) Grep -> usages of the symbol
# 4) Read  -> the consumer / call-site files

The Built-in Tools You'll Use

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.

Step 1 — Grep the Entry Point

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.

# Find where the checkout handler is defined
# Grep tool query:
#   pattern: "def process_checkout"
#   glob:    "**/*.py"
# -> returns: billing/checkout.py:42

Step 2 — Read the Definition

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.

# Read tool:
#   file_path: billing/checkout.py
#
# You learn: process_checkout() calls
#   - validate_cart()
#   - charge_card()
# These become your next Grep targets.

Step 3 — Grep the Usages

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?

# Grep tool query:
#   pattern: "process_checkout\("
#   glob:    "**/*.py"
# -> api/routes.py:88
# -> tasks/retry_jobs.py:19
# -> tests/test_checkout.py:55

Step 4 — Read the Consumers

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.

# Read tool on each consumer:
#   api/routes.py        -> HTTP entry, validates auth first
#   tasks/retry_jobs.py  -> retries failed charges
#   tests/test_checkout  -> documents expected contract
# Now an Edit is safe and well-scoped.

Trim Tool Output as You Go

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.

Glob vs Grep — Pick the Right Door

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.

# Glob: enumerate by pattern
#   pattern: "src/**/*.controller.ts"
# Grep: enumerate by content
#   pattern: "checkout", glob: "src/**/*.ts"

Adaptive, Not a Fixed Pipeline

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".

while True:
    resp = client.messages.create(
        model="claude-opus-4-1",
        max_tokens=2048,
        messages=history,
        tools=[grep_tool, read_tool, glob_tool],
    )
    if resp.stop_reason == "end_turn":
        break  # model decided investigation is complete
    # stop_reason == "tool_use": run tool, append result, loop
    history.append(run_tools(resp))

Scope the Investigation Agent

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.

explorer = AgentDefinition(
    name="code-explorer",
    description="Read-only incremental investigation of a symbol",
    system_prompt="Grep entry points -> Read -> Grep usages -> Read consumers. Report findings only.",
    allowed_tools=["Glob", "Grep", "Read"],  # least privilege, no Edit/Write
)

Quick Check

Test your grasp of the pattern's core decision.

Recap — The Investigation Discipline

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.

Frequently asked questions

Is the “Incremental Investigation Pattern” lesson free?

Yes — the full text of “Incremental Investigation Pattern” is free to read here on the web, and the Claude Architect course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Claude Architect course, upgrade to CoddyKit PRO.

What will I learn in “Incremental Investigation Pattern”?

Grep entry points, Read files, Grep usages, Read consumers. You practise Claude Architect with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Claude Architect?

No prior experience is required. Claude Architect on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Incremental Investigation Pattern” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Claude Architect lesson?

Yes. Every Claude Architect lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Claude Architect