Use Production Prompt Patterns for Features, Bugs, Refactors, and Reviews

Quick answer

An effective Claude Code prompt contains an outcome, relevant evidence, boundaries, verification, and a stop condition. Adapt that contract to the job: features need behavior and acceptance cases; bugs need reproduction and root-cause proof; refactors need invariant preservation; migrations need compatibility and rollback; reviews need a threat model and severity rules. Anthropic's prompt library and best practices provide current baseline patterns.

The five-part engineering contract

Outcome: What observable behavior must exist?
Evidence: Which error, issue, screenshot, or files establish the problem?
Boundaries: What must not change?
Verification: Which commands and cases prove success?
Stop: Which actions require review before proceeding?

This is not a rigid incantation. It prevents the most expensive ambiguity while leaving Claude free to investigate.

Feature pattern

Add saved searches to the orders page. Users can name a filter, reopen it, and delete it.
Follow the existing repository/service/component separation. Do not add a new state library.
Handle duplicate names, empty names, deleted searches, and unauthorized access.
First inspect analogous bookmark behavior and propose a plan. Then implement tests,
run the focused suite and browser flow at desktop and mobile widths, and show the diff.
Do not run migrations against any shared database.

This specifies user behavior while delegating file discovery and implementation details.

Debugging pattern

Production symptom: two simultaneous refresh requests sometimes revoke the new session.
Logs and the failing trace are below. Reproduce the race deterministically before editing.
Trace the state transitions and identify the earliest incorrect assumption with file references.
Fix the root cause without adding retries or suppressing errors. Add a regression test and
run it repeatedly. Report evidence, not just a conclusion.

Require reproduction before repair. Otherwise the first plausible explanation can become an anchor.

Refactoring pattern

Extract payment-provider selection from CheckoutService to remove the circular dependency.
Public types, error codes, transaction boundaries, and runtime behavior must remain unchanged.
Characterize current behavior with tests first. Make small commits or checkpoints, run focused
tests after each step, then typecheck and build. Stop if preserving behavior requires an API change.

Refactors need explicit invariants more than aspirational language such as “make it cleaner.”

Migration pattern

Specify expansion, backfill, cutover, and contraction separately. Demand idempotency, observability, and rollback:

Design a zero-downtime migration from `full_name` to `given_name` and `family_name`.
Old and new application versions overlap for 30 minutes. Provide forward/backward compatibility,
backfill batching, monitoring queries, rollback triggers, and the point after which rollback is unsafe.
Produce the plan only; do not execute database commands.

Review pattern

Review main...HEAD for correctness and security. Prioritize exploitable authorization gaps,
data loss, broken concurrency, and backward incompatibility. For every finding cite the file and
line, show a concrete failure path, and explain why existing tests miss it. Do not report style
preferences. If no actionable issues exist, say so and list residual test gaps separately.

Lab: one problem, four contracts

Take a small authentication change and write four prompts: implement, debug, refactor, and review. Run each in a fresh session. Compare changed-file count, correction count, context usage, and defects. The goal is to see how the contract changes the agent's search and evidence—not to discover a universal “perfect prompt.”

Course-correct with evidence

When a run diverges, interrupt early. State the observation that disproves the current direction, preserve constraints that still apply, and request a new discriminator before more edits. Avoid adding a stream of contradictory micro-instructions; once the accepted approach changes materially, summarize the new contract or start a fresh session.

Use separate prompts for investigation and mutation when trust boundaries or irreversible actions exist. A database incident might permit logs and read-only queries during diagnosis, local code edits during remediation, and no production action until an owner approves a written command. The prompt should make those phases visible.

Evaluate prompt quality by outcomes

Track first-pass acceptance, correction count, unnecessary files changed, verification completeness, and defects found in blind review. A prompt that produces beautiful prose but weak tests is not high quality. A terse prompt that succeeds only because the repository already contains excellent instructions may be perfectly adequate. Judge the whole harness: prompt, CLAUDE.md, tools, tests, and environment.

FAQ

Should I name every file Claude must edit?

Name known evidence and boundaries, but let Claude discover the smallest correct change. Overprescribing files can hide the real dependency.

Are long prompts always better?

No. Include discriminating constraints, not background that Claude can inspect or that does not change a decision.

What should be in every high-risk prompt?

A non-reversible-action boundary, explicit verification, and a request to stop when assumptions are unproven.