One Claude Code Tip a Day: Hand Claude the Folder, Not the Whole Repo

This post is part of the “One Claude Code Tip a Day” series — a daily guide to using Claude Code more effectively.

The real failure: repo-wide wandering

The worst Claude Code sessions do not fail loudly. They drift. You ask it to fix a settings page bug, it searches the whole monorepo, finds three `SettingsPanel` components, edits a shared hook, updates snapshots, and then discovers the route you care about uses a package-specific drawer. Nothing is obviously incompetent; the problem is that the working set was too wide.

Use `@folder` when the task belongs to a subsystem, not a single file. It is the middle ground between `@file` precision and “please explore the whole repo.” You are telling Claude Code: start here, build the local map, and do not treat the entire repository as equal evidence.

Start with a bounded read

Imagine a frontend bug: users can save notification preferences on desktop, but the mobile settings drawer silently drops the “weekly digest” toggle. You know the relevant code lives somewhere under `apps/web/src/features/settings`, but you do not know the exact component.

Start like this:

`Read @apps/web/src/features/settings. Do not edit anything yet. Build a short map of the folder: routes, components, hooks, API calls, tests, and any mobile-specific code. Then identify the most likely path for the weekly digest toggle and list the exact files you need to inspect next.`

That prompt is stronger than “fix settings.” It gives Claude a boundary and a job: create a local subsystem map before touching code. The first useful output should not be a patch. It should be a file map with a hypothesis.

Make Claude prove the active path

A good `@folder` workflow has one extra checkpoint: ask Claude to prove which files are actually on the failing path. Folder context can still include dead code, old components, stories, and test fixtures.

Follow up with:

`Before editing, prove which component renders the mobile drawer. Trace from the route entry point to the toggle component. If there are two possible drawers, explain how we can tell which one is used in production.`

In a real session, this is where Claude might find `SettingsDrawer.mobile.tsx` and `NotificationForm.tsx`, but also an older `MobileSettingsPanel.tsx` that is still covered by a snapshot. Without this step, the agent may patch the most obvious file, not the active one.

When the answer is still vague, make it inspect evidence:

`Use the folder map and search only inside @apps/web/src/features/settings. Find where weeklyDigest is read, written, and serialized. Do not edit. Return a three-row table: source state, UI binding, API payload.`

Now you are turning folder context into a trace, not a scavenger hunt.

The edit contract

Once the active path is clear, narrow the permission boundary. Do not let the existence of `@folder` become permission for a folder-wide rewrite.

`Edit only the files needed under @apps/web/src/features/settings. Fix the mobile weekly digest toggle so it is included in the save payload. Do not refactor desktop settings, rename shared types, or update snapshots unless a targeted test requires it. After editing, run the smallest relevant test and show git diff.`

This prompt gives Claude enough room to touch a component and a serializer, but not enough room to “clean up” the feature. That matters. Claude Code is often helpful enough to improve nearby code you did not ask about, which is exactly how a small bug fix becomes an unreviewable diff.

Verification after the first patch

After Claude edits, inspect three things.

First, the diff:

`Show git diff for files under apps/web/src/features/settings only. Summarize the behavior change in two bullets and call out any unrelated formatting changes.`

Second, the test evidence:

`Run the targeted settings test. If no test covers mobile save payloads, add one focused test before claiming success.`

Third, the user-visible path:

`If a browser or Playwright check is available, verify the mobile drawer flow: toggle weekly digest, save, and confirm the request payload contains weeklyDigest: true.`

The important habit is that `@folder` does not replace verification. It makes verification easier because you can name the subsystem and reject evidence from unrelated paths.

Failure modes

The first failure mode is pointing at a folder that is too high. `@apps/web` is often just a polite way to say “read the whole frontend.” Prefer the smallest folder that still contains the route, component, hook, and test you need.

The second failure mode is trusting the folder map as truth. Folder names lie. Old components survive. Stories render fake paths. Ask Claude to trace from route to component before editing.

The third failure mode is letting Claude update everything in the folder. A folder boundary is for context; the edit boundary should still be narrow. If the first diff touches twelve files, stop and ask which touched files were necessary for the failing behavior.

Second-pass correction

When the fix fails, do not widen immediately. Re-anchor on the same folder and the failed evidence:

`The Playwright mobile settings test still fails: the request payload does not include weeklyDigest. Re-read @apps/web/src/features/settings. Do not edit yet. Explain why the previous patch did not affect the submitted payload, then name the smallest second patch.`

This is a better “try again” prompt because it forces Claude to connect the failed verification to the local architecture. Maybe the component state updates, but `buildSettingsPayload.ts` filters unknown keys. Maybe the mobile drawer uses a separate submit handler. The second pass should become more precise, not more desperate.

Rule of thumb

Use `@folder` when you can name the subsystem but not the exact file. Start with a folder map, prove the active path, convert the map into a trace, then edit only the files required by that trace. If `@file` is a scalpel and repo-wide search is a floodlight, `@folder` is the workbench: enough context to reason, enough boundary to keep the session honest.