Use Claude Code on One Real Repo Task Without Letting the Shell Loop Drift

The first real Claude Code task should feel smaller than your ego wants.

That is not a joke. Most weak first impressions come from choosing a task that is too broad to grade. Once the prompt sprawls, Claude starts reading half the repository, the shell fills with side explorations, and you cannot tell whether the tool is helping or just being energetic.

The better first test is narrow enough to survive review:

• one bug fix inside a known package
• one failing test that already has a reproduction step
• one command-line or API edge case with a visible finish line
• one small refactor where you can name the files before Claude does

That is the kind of work Claude Code can make meaningfully faster without turning the shell into a wandering research session.

Click to enlarge

Official Claude Code runtime image checked on 2026-04-16. This is the working surface that matters for the first repo trial: one bounded shell session, visible exploration, and output you can inspect before trusting.

Pick A Task That Already Belongs In The Terminal#

Claude Code is strongest when the shell is part of the work, not just the place where the AI happens to live.

Good first tasks usually include at least two of these:

• inspect a repo and find the right file path
• run one narrow validation command
• patch code in a few related files
• confirm the fix with the same command or test

Bad first tasks usually sound larger and teach less:

• "clean up this service"
• "modernize the auth flow"
• "make this repo easier to maintain"
• anything where the stopping line is editorial instead of operational

If you could not tell a teammate where the task should stop, do not use it as your first Claude Code trial.

Start In Plan Mode When The Boundary Is Not Obvious#

Claude Code has a real advantage here: it can stay in a planning lane before it starts editing.

Current Claude docs position plan mode as the safe way to explore a codebase, gather requirements, and propose the change before execution. For a first repo task, that is usually the right starting posture.

You can begin that way from the shell:

claude --permission-mode plan

Or jump into it from an existing session:

/plan fix the failing billing webhook test without changing unrelated checkout logic

Why this matters on the first task:

• you see whether Claude picks the right files before touching them
• you force the task boundary to become explicit
• you avoid mistaking fast edits for good judgment

If the plan starts naming too many packages, config files, or cleanup ideas, you already learned something useful. The scope is loose. Fix that before you approve any execution.

Give Claude The Repo Rules In The Format It Actually Reads#

This is where many first runs stay unnecessarily sloppy.

Claude Code reads CLAUDE.md, not AGENTS.md. If the repository already uses AGENTS.md for other agents, the current memory docs recommend creating a CLAUDE.md that imports it and then appending Claude-specific notes.

That lets you avoid duplicating policy while still giving Claude the local rules it actually loads at session start.

Minimal example:

@AGENTS.md

## Claude Code
- Use plan mode first for tasks under `src/billing/`
- Run `pnpm test billing-webhook.test.ts` before proposing broader edits
- Do not modify generated API clients

If the repo has no CLAUDE.md, running /init is a reasonable starting point. Claude will draft a project guide with detected commands and conventions. The important part is what you do after that: trim it down and keep only the instructions that should matter in every session.

The docs are explicit on one point that is easy to ignore: shorter, more specific CLAUDE.md files produce better adherence than bloated ones.

Scope Early With @file And @directory, Not With Longer Explanations#

Claude Code's @ references are one of the easiest ways to keep a task grounded.

The current workflow docs say:

• @file pulls the file content directly into context
• @directory gives Claude the listing for that directory
• parent CLAUDE.md files load alongside those references

That means a tight prompt often beats a clever prompt.

This:

Investigate the bug in @src/server/webhooks/billing.ts and @tests/billing/webhook.test.ts.
Stay inside @src/server and @tests/billing unless you can show why another file is necessary.

is usually better than a long background essay about your architecture.

Directory references are useful when the first task is partly navigational. File references are better when you already know the likely blast radius.

A Strong First Prompt For Claude Code#

Start from the repo root and paste something close to this:

Work on one bounded repository task.

Task:
- [replace with one real task]

Before editing:
1. Summarize the problem in 3 to 5 lines
2. Name the files most likely involved
3. Explain the smallest fix that could work
4. Name one thing that must stay unchanged

Execution rules:
- stay inside @src/path and @tests/path unless you explain why expansion is needed
- do not do adjacent cleanup
- validate with [replace with one command]
- if the scope starts widening, stop and propose a smaller plan

At the end:
- summarize what changed
- show the validation result
- call out anything still risky

That prompt works because it asks Claude to prove file judgment first, not because the wording is magical.

What Good First-Run Output Looks Like#

The first successful Claude Code run usually looks less ambitious than people expect.

You want to see:

• a believable file shortlist
• a plan that sounds tied to this repo, not generic software advice
• one validation command that actually matches the task
• a contained diff you can inspect without opening twenty tabs

The key test is not "did Claude type quickly." The key test is "did Claude stay inside a boundary that still makes sense after reading the diff."

Watch For These Early Drift Signals#

Claude Code drift usually shows up before the code edit itself.

The common warning signs are:

• it starts reading unrelated packages after already finding the likely file
• it proposes config cleanup that was never part of the task
• it keeps broadening the explanation instead of shrinking the plan
• the validation step becomes "run everything"

Once that happens, do not reward the drift with more freedom. Tighten the surface.

Two good ways to do that:

1. add direct @file references for the two or three files that matter most
2. restate the stopping line in operational terms, not outcome terms

Bad correction:

Please focus more.

Better correction:

Keep this to @src/server/webhooks/billing.ts and @tests/billing/webhook.test.ts.
Do not edit configuration or retry infrastructure.
Stop after the failing webhook test passes.

Use /diff Before You Trust The Summary#

Claude Code has a built-in diff viewer for a reason. Use it.

The commands docs show /diff as the fastest way to inspect the current uncommitted changes and the per-turn diffs. For the first repo task, that matters more than polished prose at the end of the run.

If the summary says the task stayed narrow but /diff shows a surprise edit in a distant package, trust the diff.

That is one of the real strengths of Claude Code compared with looser agent setups: the shell and diff can keep you honest if you actually look at them.

If the diff is already noisy and you are not sure whether the problem is permissions, memory, or task logic, open Debug a Claude Code Run With Logs, File Scope, and a Tighter Follow-Up Prompt before you keep editing. The right recovery move depends on which failure bucket you are actually in.

If Claude Repeats A Repo Mistake, Move The Rule Out Of Chat#

Do not keep paying the same prompt tax.

If Claude ignores the same repo-specific rule twice, move that rule into CLAUDE.md or inspect existing project memory with /memory. The current docs describe /memory as the place to edit loaded CLAUDE.md files, inspect auto memory, and toggle auto memory on or off.

That does not mean every correction belongs in persistent memory. It means repeated corrections do.

Good candidates for CLAUDE.md:

• always run pnpm test path/to/test.ts before claiming success
• never edit generated clients under src/generated/
• billing code lives under src/server/webhooks/

Bad candidates:

• one-off product decisions for this ticket only
• a temporary workaround you do not want reused later
• a debugging theory that is still unproven

When Claude Code Is The Wrong Surface#

Claude Code is not the right first tool for every task.

Open something else when:

• the real work is visual and belongs in an IDE preview loop
• the task is mostly backlog delegation and delayed PR review
• you already know you want editor-first pair programming

If the friction comes from the shell itself rather than from Claude's judgment, the better answer may be Cursor, not a longer Claude prompt.

If the friction comes from wanting a more asynchronous handoff, Codex may fit better than a live terminal loop.

A Simple Pass-Fail Rubric For The First Trial#

After one real task, ask five blunt questions:

1. Did Claude pick the right files before editing?
2. Did the scope stay smaller than a normal human cleanup instinct?
3. Did the validation command actually prove anything?
4. Was the returned diff easier to review than doing the task later from your own queue?
5. Would the same task have felt more natural in Cursor or Codex?

If the answer to the first four is mostly yes, the trial worked.

If the answer to the fifth is clearly yes, that does not mean Claude failed. It means you learned the task belongs on a different surface.

Official References#

• Common workflows
• Permission modes
• Commands
• How Claude remembers your project
• CLI reference

What To Read Next#

Read Debug a Claude Code Run With Logs, File Scope, and a Tighter Follow-Up Prompt if your first real task came back noisy, incomplete, or off-target.

Read Install Claude Code Before Your First Real Repo Task if setup, auth, or Windows shell choice still feels unstable.

Read Use GitHub MCP With Claude Code to Find the Right Files From an Issue if the next problem is repository navigation rather than pure code editing.