File-context strategies for AI agents: what to feed, what to skip, what to summarize

You give Claude Code a goal. Behind the scenes it reads files. Which files? How many? In what order? Those choices determine whether the output is precise or hallucinated.

This post is the playbook for shaping that scope deliberately.

Three strategies

1. Narrow scope — feed only the surface area

For: changes you can describe in one sentence.

"Update the email validation in src/lib/validators.ts to allow + aliases.
Read only: src/lib/validators.ts, src/lib/validators.test.ts."

Why it works: a short context lets the model attend to every line. The output is a focused diff, easy to review.

When to escalate: when the agent says "I'd need to see X" — it usually means the change touches more than you scoped.

2. Summary-first — feed extracts, not full files

For: cross-cutting changes across many files.

"Refactor all instances of the legacy CookieAuth class to JwtAuth.
Files affected (you wrote the summaries last session):
  notes/CookieAuth-callsites.md   ← list of 12 files using it
  notes/JwtAuth-shape.md          ← target API

Read those summaries first; pull in actual files only as needed."

Why it works: you bypass the model's "wander the repo to discover" phase. Latency drops, accuracy rises.

When this fails: if your summaries are stale. Stale summaries are worse than no summaries because the agent trusts them. Revisit before re-using.

3. Fat tree — feed a directory, let the agent decide

For: exploratory or debugging tasks.

"There's a flaky test in tests/integration/auth.test.ts. Read the test
and any source it touches under src/auth/. Find the cause."

Why it works: when you don't know what's relevant, the agent's read-on-demand is faster than your guess.

When this fails: large directories. If src/auth/ has 300 files, the agent will burn tokens deciding what to look at. Pre-narrow first.

How to choose between strategies

File-system patterns that make scope decisions automatic

The directory layout matters because it pre-categorizes files for the agent.

Pattern: notes/ next to src/

project/
├── src/
├── tests/
└── notes/
    ├── architecture.md
    ├── auth-flow.md
    ├── known-issues.md
    └── decisions/
        ├── 001-why-postgres.md
        └── 002-feature-flags.md

When you ask the agent to do something with auth, you can point at notes/auth-flow.md for context without dumping src/auth/**/*. The note is small, dense, and human-curated.

Pattern: per-session CLAUDE.md

In session directories:

sessions/2026-04-22-auth-rewrite/
├── CLAUDE.md
└── …

The CLAUDE.md declares scope:

## Files in scope
- src/auth/CookieAuth.ts (read + edit)
- src/auth/JwtAuth.ts (read + edit)
- tests/auth/*.test.ts (read; edit only if behavior changes)

## Files NOT in scope (don't touch)
- src/users/* — separate session
- migrations/ — handled by infra team

The agent treats this as a contract. Combined with a session directory pattern (covered in the project layout post), scope is encoded in the directory itself.

Pattern: companion .notes.md files

For research or large-codebase work:

papers/cache-invalidation-zhao.pdf
papers/cache-invalidation-zhao.notes.md   ← extracted summary

When you reference 12 papers, you reference the notes — 1500 tokens each, dense — instead of full PDFs. The agent works with summaries; you keep the originals for verification.

What happens when scope is wrong

Three failure modes I've seen repeatedly:

Too narrow

Agent says: "I need more context — what does the User type look like?"

This is a good failure. You expand scope by 1 file, ask again, you're moving.

Too wide

Agent does: lots of confident edits across files, half of them subtly wrong.

This is the bad failure. The agent has too much context and no anchor. Detect by: review the diff, find that half the changes are unrelated to your stated goal. Cure by: shrink scope, restart.

Wrong files in scope

Agent does: edits the right kind of thing in the wrong files.

This happens when your summary or CLAUDE.md is stale. Cure by: regenerate the summary, then re-prompt.

Tooling that helps

• A file manager with preview: you can audit "is this the file I want in scope?" without opening an editor. mq-dir's per-tab preview shows the first 1000 lines instantly — enough to decide.
• tree -L 2 -I node_modules: a 30-line directory tree pasted into your prompt gives the agent navigation without dumping content.
• grep -l "pattern" -r src/: produce a file list, paste it as scope. Pre-narrows for the agent.

A concrete protocol

For any non-trivial agent task, three steps:

1. Decide the strategy before writing the prompt. Narrow / summary / fat tree.
2. State the scope explicitly in the prompt — "read only X, Y, Z" or "look only under directory D."
3. Capture the result: if the agent did well, save what worked into the session's notes.md for next time.

This sounds heavyweight but takes about 30 seconds per task. The savings are significant: agent runs are faster, more accurate, and re-runnable.

When the rule "feed less" reverses

Some tasks genuinely benefit from a wide window:

• Whole-codebase audits (security review, dependency upgrades)
• Multi-document synthesis (writing a survey, comparing 20 specs)
• Pattern detection ("find all places we do X across the codebase")

For these, fat tree wins. Just be explicit: "Read all files under src/ and tests/, then…" The agent will do the reads; you accept the latency for the breadth.

Takeaway

Modern agents have huge context windows. They still benefit from scope discipline. Pick a strategy, encode it in the directory layout, and the agent's quality improves without prompt-engineering tricks.

mq-dir's quad-pane setup makes this discipline easier in practice — you can have a pane for notes/, a pane for src/, a pane for tests/, and a pane for the session itself, all visible at once. Scope decisions stop being abstract.