How to give Claude context for a bug fix

When Claude suggests a bug fix that looks right but breaks the application, the usual problem is not the model’s coding ability. It did not have enough evidence to reproduce the failure, understand the intended behavior, or see the test boundary.

A useful bug-fix handoff is not a complete repository dump. It is a compact context pack that combines the symptom, the narrowest relevant code path, a failing test or reproduction, and only the configuration needed to explain the behavior.

Write the symptom before you collect files

Start with what a user or system actually observes. Include the expected behavior, actual behavior, affected version or environment, and exact reproduction steps. This prevents an AI assistant from fixing the implementation it imagines instead of the failure you have.

Expected: submitting the form retries a transient network failure once.
Actual: the first failure marks the request complete and the retry never runs.
Reproduction: disable the network for the first request, restore it within 2 seconds,
then submit the same form.
Scope: production web app, version 2.4.1.

Use facts rather than diagnoses. “The retry state is broken” may be true, but it nudges the model to accept your theory before it has inspected the evidence.

Include the smallest complete code path

For a bug fix, Claude needs the code that produces the failure and the files that explain its inputs, state, and expected output. Start with:

• The failing function or component.
• Its direct caller or event handler.
• Types, schemas, or state definitions touched by the path.
• The existing test file, even if the exact regression case is absent.
• A relevant configuration file or safe environment template.
• A sanitized error log, request trace, or stack trace when it demonstrates the failure.
• The issue description or acceptance criteria, when available.

Do not include every sibling module “just in case.” If Claude asks for a missing dependency, add that file in a second pack or update the first one. Iteration is safer than flooding the context window.

Know what each source contributes

Redact logs and configuration before sharing

Bug reports are unusually risky because the evidence often comes from production. Logs can contain session cookies, bearer tokens, email addresses, IP addresses, internal hostnames, or request bodies. Config files can contain database URLs and API keys.

Keep the shape of the evidence but remove sensitive values. A safe log excerpt should show timing, error type, request flow, and relevant identifiers replaced with placeholders. The same rule applies to a configuration file: include the flag name and an example value, not the live credential.

For debugging, preserving the sequence is usually more valuable than preserving a real secret.

Read the file-sharing safety checklist before sending production-derived context to any AI tool.

Ask Claude to diagnose before it edits

Separate diagnosis from implementation. Ask for a ranked root-cause hypothesis and the missing evidence first, then request a minimal patch. This reduces confident rewrites that bypass the established contract.

Using only the included context:
1. Explain the most likely root cause and cite the relevant files.
2. List any missing evidence that could change the conclusion.
3. Propose the smallest safe fix.
4. Specify the regression test and edge cases it must cover.

Do not invent APIs or assume files not present in the context pack.

Build a portable debugging pack locally

MarkDone’s AI Context Builder makes this handoff reviewable before it enters a chat. Choose individual files or a project folder, keep only the sources that explain the bug, scan them locally for common secrets, and generate one structured context.md with paths and token estimates.

Select the Bug fix profile to start with a task focused on diagnosis, a minimal safe change, and tests. The resulting Markdown works with Claude, Codex, ChatGPT, Gemini, or a local model; it is not tied to one provider.

When the bug spans too much code

Split the work by question. First prepare a diagnosis pack: symptom, trace, entry point, and relevant state. Once the failure mode is clear, prepare an implementation pack: changed module, interfaces, tests, and acceptance criteria. This avoids asking a model to solve an architecture problem and write a patch from an unfocused archive.

If you regularly prepare larger project handoffs, MarkDone Pro removes the Free plan’s file and token limits and can save local profiles for recurring workflows. Files are still processed locally in your browser.

Bug-fix context checklist

1. Describe expected and actual behavior, plus exact reproduction steps.
2. Add the affected module, caller, contract, and nearest relevant test.
3. Include a sanitized trace or log only when it clarifies the sequence.
4. Use configuration templates, not live secrets.
5. Ask for diagnosis, evidence gaps, minimal fix, and regression tests.
6. Split broad incidents into smaller, evidence-based packs.

For pre-merge review rather than a known regression, read how to prepare a codebase for AI code review. For the broader difference between repository access and portable context, see how to give Claude or Codex your whole project as context.