Use Claude Code to Plan a Small Fix Before Editing

For: a builder who has a reproducible bug in a local project and wants to understand the change before an agent touches files.

Artifact: a reviewed plan, a bounded patch, and a short acceptance record.

Evidence label: Documentation-based guide. The workflow is based on current Claude Code documentation. No Claude Code execution is claimed here.

Advanced builder lesson: this requires a terminal, a local Git repository, and Claude Code access. If you do not use a coding tool, use the no-code alternative below.

The fictional task

Assume a small internal tool has a command called summarize-report. When the input file is empty, it prints a blank screen instead of a useful message. The requested fix is limited to that case. You do not want a new dependency, a redesign, or changes to the report format.

Acceptance rule:

An empty input file produces the message "No report rows found." and exits successfully.
A non-empty input produces the same report as before.

Three steps

Open the project root and capture a clean starting point:

cd /path/to/project
git status --short
find . -maxdepth 2 -type f | sort | sed -n '1,80p'

Use a disposable copy or a branch you can review. If the working tree already contains unrelated changes, stop and separate them.

Start Claude Code with claude. Ask it to investigate and plan without editing:

Investigate the empty-input behavior of summarize-report.

Do not edit files yet. Do not install packages or change configuration.

Please report:
- the command or function that handles the input file
- the smallest likely change
- the existing test or check that should cover the behavior
- any ambiguity or risk
- a proposed acceptance test for an empty file and a non-empty file

Stop after the plan so I can review it.

Claude Code’s documented workflows cover exploring a codebase, finding relevant code, fixing bugs, testing, and planning before edits. Surface, permissions, and available tools can vary.

After reviewing the plan, approve a narrowly scoped edit:

Proceed only with the smallest change that makes an empty input print "No report rows found." and exit successfully.

Constraints:
- edit only the files named in the approved plan
- do not add dependencies
- preserve non-empty report output
- add or update a focused test if the project already has a test pattern
- show the diff and run the relevant existing check
- stop before any commit, push, or deployment

Then inspect the result yourself:

git diff --stat
git diff
git diff --check

Run the project’s documented test command. Do not claim a pass when the project has no check or the command was not run.

Illustrative plan and result

This is a manually written example, not a Claude Code result:

Plan:
1. Trace summarize-report from its CLI entry point to the row parser.
2. Add an empty-row guard at the existing reporting boundary.
3. Reuse the current test fixture pattern for an empty file.
4. Run the focused test and the existing suite.

Boundary: src/report.js and test/report.test.js only.
Risk: a guard in the wrong layer could change whitespace or error handling for non-empty files.

A good result makes the boundary visible. It does not prove that the agent found the correct file or that the fix works.

Acceptance checks

Keep the patch only when:

the changed-file list matches the approved plan.
an empty input produces exactly the agreed message and successful exit.
a non-empty input keeps its previous output.
the relevant checks pass, or the missing checks are recorded.
no package, configuration, credential, commit, push, or deployment change slipped in.

Common failure fixes

Claude starts editing immediately. Stop the session and restate that the first turn is investigation only. Use a clean copy before trying again.

The proposed file is not the real entry point. Ask for the call path and a file reference. Do not approve a patch based on a guessed filename.

The empty-file test passes but normal output changes. Compare a known non-empty fixture before and after. Revert the patch if the acceptance rule is not met, then narrow the guard.

No-code alternative

Search the project for summarize-report, trace the input path in your editor, write down the smallest change, and run the existing checks yourself. The plan-first habit works without an agent.

Limits and access

Claude Code can read a codebase, edit files, run commands, and work across several surfaces, but access and permissions depend on the installation and account. Review proposed commands and diffs. Keep production credentials and private data out of a practice repository.

Sources

Want a weekly task like this? Join The Weekly Verdict.