Fast Context Understanding

Watch a fresh agent on a real task and you'll see it do the same thing every time. Read package.json. Read tsconfig.json. Read the entry point. Read every file in src/. Twenty steps later, it's just starting to think about the actual work.

This is the "read everything, then act" strategy. It feels thorough. It pollutes context, burns budget, and runs out of attention before the agent's done anything useful.

The fix is small: search first, read second, act third. The whole change lives in the system prompt and a habit the agent picks up from it.

Outcome

The system prompt's Agency section steers the agent toward grep before read whenever the relevant files aren't already named. Multi-file tasks resolve in a few steps instead of a few dozen.

Fast Track

1. Add two lines to the Agency section: search before reading, don't read files "just in case"
2. Verify with a real task: the agent should grep for the pattern, then read only the matches
3. Confirm direct file questions still go straight to read

Hands-on Exercise 9.2

Steer the agent toward grep-first exploration through the prompt.

Requirements:

1. Update the # Agency section in buildSystemPrompt with two new bullets:
   • Search before reading. Use grep first, then read only what you'll change
   • Don't read files "just in case." Read what you need when you need it
2. Run a task where the relevant files aren't named in the prompt. Confirm the agent uses grep first
3. Run a task that names a specific file. Confirm the agent goes straight to read

Implementation hints:

• The change is in src/system.ts, not in any tool. The tools haven't changed
• The Agency section is where action policy lives. This is action policy
• Don't add this to the tool description on grep. It belongs at the agent's policy level, not the tool's

The prompt addition

sections.push(`
# Agency
- USE your tools. Read files, search code, run commands, then answer.
- Do NOT explain what you WOULD do. Actually do it.
- Available tools: ${ctx.toolNames.join(", ")}
- Search before reading. Use grep first, then read only what you'll change.
- Don't read files "just in case." Read what you need when you need it.`);

Two bullets. That's the whole policy change.

The pattern in practice

The naive (slow) flow on "Add rate limiting to the auth routes":

read package.json
read tsconfig.json
read src/index.ts
read src/routes/index.ts
read src/routes/auth.ts
read src/routes/users.ts
read src/middleware/index.ts
... 20 more files
start implementing

The grep-first (fast) flow on the same prompt:

grep pattern: "router\.post.*auth|router\.get.*auth"
  -> matches src/routes/auth.ts
read src/routes/auth.ts
grep pattern: "rateLimit|rate-limit|middleware"
  -> matches src/middleware/rate-limit.ts
read src/middleware/rate-limit.ts
start implementing

Five steps instead of thirty. The agent now has exactly the context it needs to act and almost nothing else.

Parallel reads, when they apply

Once grep has narrowed the file list, the reads can fan out. The AI SDK runs tool calls in parallel when they don't depend on each other:

Step 1: grep for the pattern (1 call)
Step 2: read auth.ts AND read rate-limit.ts (2 parallel calls)
Step 3: start implementing

Don't force this. If the agent reads files in parallel on its own, great. If it doesn't, the search-first habit alone is the win.

Try It

Run a multi-file task with no specific file named:

bun run index.ts . "Find every place this project parses JSON and tell me which ones might fail on malformed input"

You should see grep calls before any read, and the reads should be on the files grep found.

Run a task that names a specific file:

bun run index.ts . "What's in src/sandbox-local.ts?"

The agent should go straight to read. No grep needed. The pattern adapts to whether the file is known.

npx tsc --noEmit

Commit

git add src/system.ts
git commit -m "feat(prompt): steer agent toward grep-first exploration"

Done-When

• Two new bullets in the Agency section
• Multi-file tasks use grep before read
• Specific-file tasks skip grep and go straight to read
• The total step count on an exploration task drops noticeably
• npx tsc --noEmit passes