Prompt Library

When you want to restructure existing code without changing its behavior.

Refactor <FILE/MODULE> to improve <GOAL, e.g. readability/structure>.
Rules:
- Do NOT change external behavior (input/output, API, side effects must stay identical)
- Work in small, individually reviewable steps
- After each step, run the tests (<TEST COMMAND>) and show me the result
- Stop and ask if a step would change behavior
At the end, summarize all steps and the test results as evidence.

💡 Keep the diffs small — reviewing one step at a time beats reviewing everything at once.

Claude Code: Best practices ↗

When a function/method is too large or nested and you want to cleanly pull a part out.

In <FILE>, function <FUNCTION NAME>: extract the code block that does <DESCRIPTION OF THE PART> into its own, clearly named function.
- Behavior must stay exactly the same (same inputs -> same outputs, same error cases)
- Follow the file's existing naming/style conventions
- If no test exists yet: write one that locks in the current behavior first, then refactor
- Run the tests afterward and show me the result
Briefly explain why the new structure is clearer.

💡 No test yet? Write a characterization test first (see the Testing templates), then refactor.

Claude Code: Best practices ↗

When you're migrating a library, pattern, or API version across many files.

Migrate <OLD PATTERN/LIBRARY> to <NEW PATTERN/LIBRARY> in <SCOPE, e.g. folder/module>.
- First list ALL affected files before changing anything
- Migrate one file at a time (migrate interdependent files as one small group), show each change separately
- After each file, run the tests/build (<TEST COMMAND>) and show the result
- If unsure (e.g. unclear old behavior): stop and ask instead of guessing
At the end: list of migrated files plus any remaining open cases.

💡 For a large number of files, test on 2-3 first, refine the prompt, then run it on the rest.

Claude Code: Best practices ↗ · Anthropic: Building Effective Agents ↗

When a bug shows up and the cause isn't obvious.

Bug: <ERROR DESCRIPTION / ERROR MESSAGE>
Likely area: <FILE/MODULE, if known>
Proceed like this:
1. State 2-3 concrete hypotheses for the cause
2. Check each hypothesis deliberately (read code, logs, a small test) — don't guess
3. Write a test that reproduces the bug BEFORE fixing it
4. Fix the root cause, not just the symptom (no swallowing errors with try/catch)
5. Show the test failing before and passing after
Stop and ask if none of the hypotheses explain the bug.

💡 "Root cause, not symptom" — don't just catch the error, fix what's causing it.

Claude Code: Best practices ↗

When a test fails intermittently and you want to find the cause (timing, ordering, shared state).

Test <TEST NAME/FILE> is flaky (fails intermittently).
- Run the test <N, e.g. 20> times in isolation (<TEST COMMAND>) and log pass/fail
- Check typical causes: shared state between tests, race conditions, timing/order dependence, unmocked external calls
- State a hypothesis for the cause and back it with a targeted reproduction test
- Propose a fix that addresses the cause (not just retries/skip)
- After the fix: run the test multiple times again and show the result
If no clear cause is found, summarize what's been ruled out and what to check next.

💡 Retry logic or @skip isn't a fix — it's a band-aid this prompt explicitly rules out.

Claude Code: Best practices ↗

When a bug is reported but you don't yet have a reliable way to reproduce it.

Reported bug: <DESCRIPTION, e.g. from a ticket/support>
Expected behavior: <WHAT SHOULD HAPPEN>
Actual behavior: <WHAT HAPPENS INSTEAD>
1. Find the relevant code path (starting point: <RELEVANT AREA, e.g. src/auth/>)
2. Write a failing test that exactly reproduces the bug
3. Show me the failing test BEFORE writing the fix — I'll confirm it's the right bug
If you cannot reproduce the bug: stop and report what you checked and ruled out.
4. Only then: implement the fix, the new test must pass, and the whole test suite must stay green

💡 The confirmation stop before the fix prevents you from fixing the wrong bug.

Claude Code: Best practices ↗

Before marking a change done — have a fresh instance look at it critically.

Use a subagent/fresh session to review the diff of <SCOPE, e.g. PR/branch/file> against <PLAN/REQUIREMENT, e.g. PLAN.md or the ticket description>.
The reviewer gets ONLY the diff and the requirement — not the reasoning behind why the change was built this way.
Check:
- Is every requirement actually implemented?
- Are there edge cases from the requirement with no test?
- Was anything outside the scope changed?
Report only gaps that affect correctness or requirements — not pure style preferences.

💡 A reviewer told to hunt for gaps will almost always find some — don't chase every finding, only the ones that actually affect correctness.

Claude Code: Best practices ↗

When you want a structured review of a pull request/diff instead of one long unsorted list.

Review the diff in <SCOPE, e.g. PR #123 / branch name>.
Sort every finding into exactly one level:
- CRITICAL: bug, security issue, or risk of data loss
- MAJOR: wrong behavior in a realistic case, missing error handling
- MINOR: style, naming, small improvements
For each finding: file:line, what the problem is, a concrete fix suggestion.
No generic praise comments. If nothing is found, say so explicitly instead of inventing findings.

💡 Explicit levels stop a nitpick from carrying the same weight as a real bug.

Claude Code: Best practices ↗

After implementing a planned task — check whether everything from the plan actually got done.

Compare the current implementation in <SCOPE> with the plan in <PLAN SOURCE, e.g. PLAN.md or the ticket>.
Build a checklist from the plan and go through it point by point:
- Implemented and tested
- Implemented but without a test
- Not implemented
- Done in addition (not in the plan, but present in the diff)
Back up every point with a file/line reference or test result, no guessing.

💡 Use this as your stop criterion — the task only counts as done once every point is 'implemented and tested'.

Claude Code: Best practices ↗

For tasks that touch multiple files, have an unclear approach, or involve a module you don't know well.

Before changing anything: read <RELEVANT AREA, e.g. src/auth/> and understand how <TOPIC, e.g. login/sessions> currently works.
Then create a plan for <GOAL/FEATURE>:
- Which files need to change?
- What order of steps makes sense?
- What edge cases/risks do you see?
- How will this be verified at the end (which tests/checks)?
Show me the plan first. Only start coding after I've confirmed the plan.

💡 For small, obvious changes (typo, one line) the planning step isn't worth it — just have it implement directly.

Claude Code: Best practices ↗

When a feature is too big for one pass and needs to be broken into checkable pieces.

I want to build <FEATURE DESCRIPTION>.
Break the feature into stages, where each stage:
- runs/tests on its own (no half-broken intermediate state)
- has a clear verification step (test, build, manual check)
List the stages in order with 1-2 sentences each.
Implement ONLY stage 1, run the verification, and show me the result before moving to the next stage.

💡 This keeps every stage reviewable instead of ending up with one giant diff.

Claude Code: Best practices ↗ · Anthropic: Building Effective Agents ↗

For bigger/new features where you haven't thought through every detail yet.

I want to build <SHORT FEATURE IDEA>. Interview me about it in detail before anything gets built.
Ask about technical implementation, UX, edge cases, and tradeoffs — skip the obvious questions, dig into the hard parts I might not have considered.
Keep asking until everything important is covered.
Then write a complete spec (files/interfaces involved, what's explicitly OUT of scope, an end-to-end verification step) to <SPEC FILE, e.g. SPEC.md>.

💡 Start a fresh, clean session for the actual implementation, with the finished spec as context.

Claude Code: Best practices ↗

When you need to touch unfamiliar/untested legacy code and want to lock in current behavior first.

File/module <TARGET> currently has no (or not enough) tests, and I need to change it soon.
First write characterization tests: tests that document and lock in the CURRENT behavior — including edge and error cases, even if the behavior looks strange.
- No behavior change to the code itself in this step
- Run the tests and show that they pass
- Briefly list any behavior that seemed surprising/questionable (for later clarification)

💡 These tests are your safety net for the next refactoring step — don't delete them, even once the behavior is later changed on purpose.

Claude Code: Best practices ↗

When you're fixing a specific bug and want to make sure it can't silently come back.

Bug: <DESCRIPTION/ERROR MESSAGE> in <FILE/MODULE>
1. First write a test that currently fails and reproduces exactly this bug
2. Show me the failing test
3. Only then implement the fix
4. The new test must pass, and all existing tests must stay passing
Example cases the test should cover: <TEST CASES, e.g. input X gives Y>

💡 The test stays in the repo after the fix — it's what stops this exact bug from silently coming back as a regression.

Claude Code: Best practices ↗

When getting started in a new/unfamiliar codebase or module.

Give me an overview of <SCOPE, e.g. this repo / the src/payments folder> on 3 levels:
1. Big picture: what does the system do, what are the main building blocks (1 paragraph + list)
2. Structure: the most important folders/modules and their responsibility
3. Details: for <SPECIFIC PART, e.g. the request flow of one call>: step by step, which files/functions are involved
Only use what's actually in the code, no guessing — where something is unclear, say so explicitly.

💡 Follow up with targeted questions afterward instead of asking for everything at once — it keeps context small.

Claude Code: Best practices ↗

When you want to understand where data comes from and where it flows in a specific path.

Trace the data flow starting from <STARTING POINT, e.g. function/endpoint X>.
- Where does the input data come from (caller, request, DB, etc.)?
- Which functions/modules process the data, in what order?
- Where does state get mutated (state, DB writes, side effects)?
- Where does the flow end (response, storage, hand-off)?
Present this as a numbered step-by-step list with file:line references. If a step is unclear/ambiguous, flag it instead of guessing.

💡 For more complex flows, also ask for a short Mermaid diagram alongside the list.

Claude Code: Best practices ↗