DEV Community: Dev Prompts

10 Claude Prompts for Developer Documentation That People Actually Read

Dev Prompts — Fri, 17 Apr 2026 16:21:48 +0000

Bad documentation is not a writing problem. It is a prioritization problem.

Developers know what the code does. They wrote it. The issue is that explaining it to someone else — clearly, without assuming context, at the right level of detail — requires a different mode of thinking than building it did. So it gets deprioritized. The README stays sparse. The docstrings describe the "what" instead of the "why." The API docs assume the reader already knows the integration. The CHANGELOG reads like a git blame.

The result: teammates spend forty minutes reading source code for information that should have taken four minutes to find in a doc. New contributors file issues that are already answered somewhere, buried in prose no one told them to read. External developers bounce off your API because the error message says 422 Unprocessable Entity and the documentation says nothing at all.

Claude doesn't fix the prioritization problem — you still have to decide documentation is worth shipping. But it eliminates the time cost that makes documentation feel unaffordable. A good prompt plus two minutes of context produces documentation you'd be proud to merge. These 10 Claude prompts for documentation cover the types you write most often: READMEs, docstrings, API docs, changelogs, onboarding guides, and the formats developers forget exist until they need them badly. If you've read the code review prompts, the debugging prompts, or the system design prompts, you know what to expect: copy-paste ready templates with realistic example output and an explanation of why each one works.

Before You Start: How to Feed Claude Documentation Context

Documentation prompts fail for one reason: Claude doesn't know who the reader is or what they already know. A README for library maintainers looks nothing like a README for first-time users. API docs for internal teammates differ from API docs for external developers paying for access.

Four things to give Claude before any documentation prompt:

The target reader. Be specific. "A developer" is not a target reader. "A backend engineer evaluating this library for the first time, who knows Python but has never used this SDK" is. The reader determines vocabulary, assumed knowledge, and what counts as sufficient explanation.

What the thing does. Paste a two-sentence plain-English description of the code being documented. Don't make Claude infer the purpose from source code — tell it directly. "This class manages OAuth 2.0 token refresh, including retry logic and thread-safe caching" takes ten seconds to write and saves Claude from producing generic documentation that misses the point.

The output format you want. Markdown README, JSDoc comment, OpenAPI prose, plain English, Google-style docstring — these are different formats with different conventions. Specify the format explicitly or Claude will pick the one that looks most common in training data, which may not match your codebase.

The quality bar. "Good enough to ship without editing" is the standard for every prompt in this article. Tell Claude that explicitly. "Draft for review" produces hedged, incomplete output. "Ship-ready" produces output you can paste directly into the file.

The 10 Prompts

1. Write a README from Scratch

The Prompt

Write a README for this project. Target reader: [describe the reader — e.g. "a backend developer evaluating this library for the first time"]. The README should include: a one-paragraph description of what it does and why someone would use it, a prerequisites section, a quickstart (working code example — not pseudocode), the three most important configuration options, a brief explanation of the project structure, and a link placeholder for full docs. Tone: direct and practical, no marketing language. Output: ship-ready markdown.

Project name: [name]
What it does: [2-3 sentence plain-English description]
Language/framework: [e.g. Python 3.11, FastAPI]
Key dependencies: [list]
Main entry point or usage pattern: [describe or paste]

What it does
Produces a complete, opinionated README from minimal input. The section list prevents the two most common README failures: writing a vague description with no quickstart, or writing a quickstart with no context. The "no marketing language" constraint stops Claude from generating the vapid "blazing-fast, production-ready" opener that makes developers close the tab.

Example output

# rate-shield

Rate limiting middleware for FastAPI. Drop it in front of any route to enforce
per-user, per-IP, or per-API-key request limits with Redis-backed counters and
automatic sliding window resets.

Use it when you need rate limiting that survives server restarts and works
across multiple API instances without coordinating state yourself.

## Prerequisites

- Python 3.11+
- Redis 6.2+ (local or managed — Upstash, Redis Cloud)
- FastAPI 0.100+

## Quickstart

pip install rate-shield

from fastapi import FastAPI
from rate_shield import RateLimiter

app = FastAPI()
limiter = RateLimiter(redis_url="redis://localhost:6379")

@app.get("/search")
@limiter.limit("100/minute")
async def search(query: str):
    return {"results": []}

That's it. The decorator enforces 100 requests per minute per IP.
Exceeding the limit returns a 429 with a Retry-After header.

## Configuration

REDIS_URL        Redis connection string (default: redis://localhost:6379)
KEY_PREFIX       Namespace prefix for Redis keys (default: "rl:")
LIMIT_EXCEEDED_STATUS  HTTP status on limit hit (default: 429, can set 503)

## Project Structure

rate_shield/
  __init__.py      Public API — RateLimiter class and limit decorator
  backends.py      Redis backend and in-memory fallback for testing
  middleware.py    ASGI middleware layer
  exceptions.py   RateLimitExceeded with Retry-After calculation

tests/             Full test suite, runnable with pytest

## Full Docs

[Link to docs]

Why it works
Named sections force a complete README, not just a description. Most AI-generated READMEs omit the quickstart or bury it after three paragraphs of context. Specifying "working code example — not pseudocode" is the critical constraint: it produces something a developer can actually run in under five minutes.

Pro tip — If your project has a companion CLI, add "include a one-line CLI invocation example in the quickstart" to the prompt. Showing CLI and library usage together lets developers pick their entry point immediately.

2. Write Docstrings for a Function or Class

The Prompt

Write docstrings for this [function / class]. Style: [Google | NumPy | JSDoc | plain reStructuredText]. Include: a one-sentence summary, parameter descriptions with types, return value with type, any exceptions raised and when, and one usage example for any parameter combination that isn't obvious. Do not restate the implementation — document the contract (what, not how). Ship-ready.

Code:
[paste function or class]

Context (optional but improves output):
Why this exists: [1 sentence]
Non-obvious behavior to document: [describe any gotchas, edge cases, or constraints]

What it does
Produces contract-level docstrings rather than implementation summaries. The distinction matters: "Iterates through items and appends to results list" documents the implementation. "Returns items matching the predicate, preserving insertion order. Returns an empty list if no items match — never returns None" documents the contract. The first is useless. The second is what developers read when they don't want to open the source file.

Example output

def paginate_results(
    items: list[dict],
    page: int,
    per_page: int = 20,
    *,
    max_per_page: int = 100,
) -> dict:
    """Return a paginated slice of items with metadata.

    Args:
        items: The full list to paginate. Must be pre-sorted — this function
            does not sort. Empty lists return a valid response with zero results.
        page: 1-indexed page number. Page 1 returns the first `per_page` items.
            Requesting a page beyond the last page returns an empty results list,
            not an error.
        per_page: Number of items per page. Clamped to `max_per_page` silently
            if exceeded — callers should not rely on receiving more than
            `max_per_page` items regardless of what they pass.
        max_per_page: Upper bound on items per page. Defaults to 100.

    Returns:
        dict with keys:
            results (list[dict]): Items for this page. Empty list on out-of-range page.
            total (int): Total number of items across all pages.
            page (int): Current page (mirrors input).
            pages (int): Total number of pages given per_page.
            has_next (bool): True if a next page exists.
            has_prev (bool): True if a previous page exists.

    Raises:
        ValueError: If page < 1 or per_page < 1.

    Example:
        >>> paginate_results(items, page=2, per_page=10)
        {"results": [...], "total": 47, "page": 2, "pages": 5, ...}

        # Requesting beyond the last page returns empty results, not an error:
        >>> paginate_results(items, page=99, per_page=10)
        {"results": [], "total": 47, "page": 99, "pages": 5, "has_next": False, ...}
    """

Why it works
"Document the contract, not the implementation" is the constraint that separates useful docstrings from noise. Asking for exceptions and when they're raised forces Claude to think about failure cases, not just the happy path. The usage example requirement catches non-obvious edge cases — like page=99 returning empty results rather than an error — that developers discover by reading tests if they're lucky and by hitting a bug if they're not.

Pro tip — Add "flag any parameter names that are ambiguous or any behavior that surprised you" to the prompt. Claude occasionally surfaces naming issues or implicit behavior that the original author stopped noticing because it became familiar.

3. Write API Endpoint Documentation

The Prompt

Write documentation for this API endpoint. Target reader: [e.g. "an external developer integrating this API for the first time"]. Include: a one-sentence description of what the endpoint does, the HTTP method and path, all request parameters (path, query, body) with types and whether required or optional, the response schema with field descriptions, all possible error codes with plain-English explanations of what causes each one, an authentication note, and a complete working curl example. Output: markdown, ship-ready.

Endpoint: [HTTP method + path]
What it does: [plain English description]
Auth method: [e.g. Bearer token in Authorization header]
Request schema: [paste or describe]
Response schema: [paste or describe]
Error codes this endpoint can return: [list with causes]

What it does
Produces endpoint documentation an external developer can actually integrate from — not just the happy path schema. The error code section is the most important part. 400 Bad Request means nothing. "400 — Returned when amount is negative or when currency is not an ISO 4217 code. Check the errors array in the response for field-level details" is documentation that saves a support ticket.

Example output

## POST /v1/charges

Create a charge against a stored payment method. Returns the charge object
immediately — use webhooks to track async state changes after creation.

**Authentication:** Bearer token in `Authorization` header. Requires the
`charges:write` scope.

### Request

**Path parameters:** None

**Request body** (`application/json`):

| Field         | Type    | Required | Description |
|---------------|---------|----------|-------------|
| amount        | integer | Yes      | Charge amount in the smallest currency unit (e.g. cents for USD). Must be > 0. Max: 99999999. |
| currency      | string  | Yes      | Three-letter ISO 4217 currency code (e.g. "usd", "eur"). Case-insensitive. |
| payment_method| string  | Yes      | ID of a stored payment method (`pm_...`). Must belong to the authenticated account. |
| description   | string  | No       | Freeform note attached to the charge. Max 500 characters. Not shown to the payer. |
| idempotency_key | string | No     | If provided, duplicate requests with the same key return the original charge rather than creating a new one. Recommended for all charge creation. |

### Response — 201 Created

json
{
"id": "ch_abc123",
"amount": 4999,
"currency": "usd",
"status": "pending",
"payment_method": "pm_xyz789",
"created_at": "2026-04-17T10:32:00Z",
"description": null
}


`status` is `pending` on creation. It transitions to `succeeded` or `failed`
asynchronously. Subscribe to the `charge.succeeded` and `charge.failed` webhook
events rather than polling.

### Errors

| Code | Cause |
|------|-------|
| 400  | `amount` is zero or negative, `currency` is not a valid ISO 4217 code, or a required field is missing. The `errors` array in the response body identifies the offending fields. |
| 401  | Missing or invalid Bearer token. |
| 403  | Token lacks `charges:write` scope. |
| 404  | `payment_method` ID not found or does not belong to this account. |
| 409  | `idempotency_key` was used in a previous request with different parameters. |
| 422  | `payment_method` exists but cannot be charged (expired card, insufficient funds, blocked by issuer). Check `decline_code` in the response. |

### Example

bash
curl -X POST https://api.example.com/v1/charges \
-H "Authorization: Bearer sk_live_abc..." \
-H "Content-Type: application/json" \
-d '{
"amount": 4999,
"currency": "usd",
"payment_method": "pm_xyz789",
"idempotency_key": "order_12345_attempt_1"
}'

markdown

Why it works
The error code section with plain-English causes is the constraint that matters most. Without it, Claude produces schema documentation that stops at 200 OK. With it, Claude produces the table developers actually consult when the integration breaks at 2am. The curl example with realistic values (not "string" placeholders) is the difference between documentation developers copy-paste and documentation they have to mentally translate first.

Pro tip — Add "note any fields that behave differently in test mode vs. live mode" if your API has environment-dependent behavior. Stripe's documentation does this well; most APIs don't, and the omission causes hours of confusion.

4. Write a CHANGELOG Entry

The Prompt

Write a CHANGELOG entry for this release. Format: [Keep a Changelog | conventional | plain] format. Target reader: a developer upgrading from the previous version. For each change: classify it as Added, Changed, Deprecated, Removed, Fixed, or Security. Write the entry from the user's perspective — what changed for them, not what the implementation did. Flag any breaking changes with a migration note. Ship-ready.

Version: [e.g. v2.3.0]
Release date: [e.g. 2026-04-17]
Changes (git log or summary):
[paste git log --oneline output or describe changes]

Previous version: [e.g. v2.2.1]
Breaking changes (if any): [describe]

markdown

What it does
Turns a raw git log or commit list into a CHANGELOG that answers the one question developers actually ask: "What do I need to change in my code when I upgrade?" User-perspective writing ("The --output flag now accepts relative paths" instead of "Refactored path resolution in OutputHandler") is the critical difference between a CHANGELOG that saves time and one developers skip entirely.

Example output

## [2.3.0] — 2026-04-17

### Breaking Changes

**`Client.connect()` no longer accepts positional arguments.**
Previously: `Client.connect("host", 5432, "dbname")`
Now: `Client.connect(host="host", port=5432, dbname="dbname")`
Keyword-only arguments were enforced to prevent silent misconfiguration when
argument order changed in a previous internal refactor. Update all call sites
before upgrading.

### Added

- **Automatic reconnect on connection drop.** The client now retries dropped
  connections up to 3 times with exponential backoff before raising
  `ConnectionError`. Configure with `max_retries` and `retry_delay` parameters.
- **`Client.ping()` method** for health checks. Returns `True` if the server is
  reachable, `False` otherwise — does not raise.
- **Connection pool metrics via `Client.pool_stats()`.** Returns active, idle,
  and waiting connection counts. Useful for debugging pool exhaustion.

### Changed

- `Client.query()` now returns `QueryResult` objects instead of raw tuples.
  `QueryResult` has a `.rows` attribute that behaves identically to the
  previous tuple return. Accessing `.rows` requires no code changes for most
  callers; direct tuple unpacking will break.
- Default connection timeout increased from 5s to 30s to match common
  cloud database cold-start times.

### Fixed

- Fixed race condition in connection pool that caused `NullPointerError` under
  high concurrency when connections were acquired and released within the same
  event loop tick.
- Fixed `Client.execute_many()` silently swallowing errors on batch item
  failure. Failed items now raise `BatchExecutionError` with per-item results.

### Security

- Updated `cryptography` dependency to 42.0.8 to address CVE-2026-12345
  (key material exposure in certain AES-GCM operations). Upgrade recommended
  for all users.

Why it works
"Write from the user's perspective" reframes every entry from an implementation description to a behavior description. The migration note format for breaking changes — old syntax vs. new syntax, side by side — is what developers need to upgrade quickly. Without it, they have to read the source code change to understand what their code needs to do differently.

Pro tip — Add "sort entries within each section by impact — highest blast radius first" to the prompt. Developers scan CHANGELOGs from the top; breaking changes and security fixes should never be buried below minor additions.

5. Write an Onboarding Guide for New Contributors

The Prompt

Write an onboarding guide for a new contributor joining this project. Target reader: [e.g. "a mid-level backend engineer who knows Python but has never contributed to an open-source project" or "a new employee joining the platform team"]. Include: how to set up the local development environment (exact commands, no "install the usual stuff"), how to run tests, where to find the most important code (top 5 files/directories to read first), how the deployment pipeline works (briefly), and one common mistake new contributors make and how to avoid it. Tone: welcoming but direct. Ship-ready markdown.

Project: [name]
Stack: [languages, frameworks, infra]
Repo structure: [paste ls output or describe top-level directories]
Key development commands: [e.g. make dev, make test, make lint]
Common gotcha for new contributors: [describe if you know one]

What it does
Produces a day-one guide that gets a new contributor from zero to first commit without needing to ask questions in Slack. The "exact commands" constraint eliminates the single most common onboarding doc failure: assuming the reader knows what "install dependencies" means in your stack. The "common mistake" section is the most time-saving part — it surfaces the thing every senior developer knows to avoid and no one thought to write down.

Example output

# Contributing to payments-service

## Local setup

These steps get you from a fresh checkout to a running local instance.

Prerequisites: Docker Desktop 4.x, Node 20+, make. Verify:
  docker --version
  node --version
  make --version

1. Clone and install:
   git clone https://github.com/acme/payments-service
   cd payments-service
   npm install

2. Start the local stack (Postgres + Redis in Docker):
   make dev-deps

   This pulls two containers. Takes 2-3 minutes on first run.
   Subsequent starts: under 10 seconds.

3. Seed the database:
   make db-seed

4. Start the dev server:
   make dev

   Server runs on http://localhost:3001. Changes hot-reload automatically.

## Running tests

make test           # Full suite (~90 seconds)
make test-unit      # Unit tests only (~8 seconds) — run this constantly
make test e2e       # End-to-end tests against local stack (~4 minutes)

Tests require the local stack running (step 2 above).

## Where to start reading

Read these five files before touching anything else:

1. src/core/payment-processor.ts — the main entry point for all payment operations
2. src/adapters/ — one file per payment provider (Stripe, PayPal, etc.)
3. src/types/index.ts — shared types used across the whole service
4. tests/fixtures/ — the test data shapes, which map to the real API contracts
5. docs/architecture.md — a 10-minute read that explains why the adapter pattern exists

## Deployment

PRs merge to `main`. CI runs automatically (unit + integration tests, ~8 minutes).
Merging to `main` triggers a deploy to staging automatically. Production deploys
are manual: a team lead runs `make deploy-prod` after staging validation. You won't
need to run this unless you're on the core team.

## Common mistake: modifying Stripe fixtures directly

The test fixtures in `tests/fixtures/stripe/` are copies of real Stripe API responses.
If you need a new fixture, run `make record-fixtures` with a real Stripe test key —
don't hand-edit existing ones. Hand-edited fixtures cause test passes that hide real
integration bugs. Ask in #payments-eng before adding new fixture types.

Why it works
"Exact commands, no 'install the usual stuff'" is the constraint that makes onboarding docs actually work. Every documentation team thinks their setup is obvious until a new hire spends two hours on it. The "common mistake" section is the institutional knowledge that typically lives only in Slack threads and the memory of whoever's been around longest.

Pro tip — Add "identify any step that commonly fails on macOS ARM / M-series chips" if your team is mixed Mac. Silicon-specific gotchas account for a disproportionate share of new contributor setup time.

6. Audit Existing Documentation for Gaps

The Prompt

Audit this documentation for gaps and inaccuracies from the perspective of [describe target reader]. Identify: missing information a reader needs to use this effectively (not nice-to-haves — things they'll actually need), sections that assume knowledge the reader doesn't have, steps that are ambiguous or could be interpreted multiple ways, error scenarios with no guidance on what to do, and anything that is likely outdated or contradicts common behavior for this stack. Do not rewrite — produce a prioritized gap list with severity (blocks the reader / slows the reader / minor) and a one-sentence fix note for each.

Documentation to audit:
[paste documentation]

Target reader: [describe]
Stack/context: [language, framework, what this docs covers]

What it does
Produces a gap analysis from the reader's perspective rather than the author's. The severity levels force prioritization — a "blocks the reader" gap (missing auth instructions) is a different priority than a "minor" gap (inconsistent formatting). The "do not rewrite" constraint stops Claude from producing a full rewrite when you just needed a diagnostic.

Example output

Audit: Node.js SDK quickstart documentation
Target reader: Backend developer integrating for the first time

BLOCKS THE READER (fix before publishing):

1. Auth instructions missing entirely.
   The quickstart calls sdk.init() but never explains where the API key comes
   from, how to get one, or where to store it safely. The reader cannot proceed.
   Fix: Add a "Get your API key" step before the init() call, with a link to
   the dashboard and a note to use environment variables, not hardcoded values.

2. No error handling in any code examples.
   Every example shows the happy path. The reader has no model for what to do
   when a call fails. sdk.charge() throws on network errors — undocumented.
   Fix: Add a try/catch block to at least the first major example with a note
   on what error types to expect.

SLOWS THE READER (fix in next pass):

3. "Install dependencies" step has no command.
   "Install the SDK" is listed as step 1 but no npm/yarn command is shown.
   Obvious to the author, not obvious to a developer coming from Python.
   Fix: `npm install @acme/sdk` on its own line.

4. Response object fields undocumented.
   The quickstart shows `response.id` being used but never explains what other
   fields exist. Developers will open the source code to find this.
   Fix: Add a brief "What you get back" section or link to the API reference.

5. Node version requirement unstated.
   The SDK uses top-level await in examples, which requires Node 14.8+.
   Readers on older Node will get a cryptic syntax error.
   Fix: Add "Requires Node 14.8+" to prerequisites.

MINOR:

6. Inconsistent capitalization of "API Key" vs "API key" vs "api key" throughout.
7. The "Next steps" section links to docs that no longer exist (404s).

Why it works
Auditing from the reader's perspective produces different gaps than auditing as the author. Authors know the context; readers don't. The severity tiers prevent a flat list that forces the author to triage everything themselves. The "blocks the reader" framing identifies what actually stops someone from using the product — which is the only gap that matters urgently.

Pro tip — Paste two or three real support questions alongside the documentation. Claude will identify which documentation gaps caused each question, giving you a direct line from gap to user pain.

7. Rewrite Dense Technical Prose to Be Readable

The Prompt

Rewrite this technical documentation to be readable without losing accuracy. Rules: sentence length max 20 words, one idea per sentence, no passive voice, no nominalizations (don't turn verbs into nouns — use "configure" not "the configuration of"), no filler phrases ("in order to", "it should be noted that", "please be aware"). Keep all technical accuracy. Do not simplify the content — simplify the delivery. Target reading level: an experienced developer who is skimming, not studying. Ship-ready.

Original text:
[paste]

What it does
Rewrites documentation that is technically accurate but unreadable — the kind produced by engineers who are writing to cover every edge case rather than to communicate quickly. The named anti-patterns (passive voice, nominalizations, filler phrases) are the specific constructs that make technical prose dense. Naming them explicitly prevents Claude from just paraphrasing the original.

Example output

Original:
"It is important to note that the configuration of the retry mechanism should be
performed prior to the initialization of the client object, as the parameters
that have been specified will be utilized during the establishment of the initial
connection, and any modifications to these parameters following initialization
will not be reflected in the connection behavior until the client has been
reinitialized."

Rewritten:
Configure retry settings before initializing the client. The client reads these
parameters once, at startup. Changes after initialization have no effect until
you reinitialize.

If you need to change retry behavior at runtime, destroy the client and create
a new one with the updated config.

Why it works
The named anti-patterns act as explicit targets. "No nominalizations" is the single highest-impact constraint for technical writing — turning "the implementation of" back into "implementing" removes an entire layer of abstraction that slows reading. The "experienced developer who is skimming, not studying" frame stops Claude from over-explaining. Developers read documentation differently than students read textbooks.

Pro tip — Run this on your onboarding docs and your error messages, not just your API reference. Dense prose in an error message is the worst place for it — the developer is already stressed.

8. Write Inline Code Comments

The Prompt

Write inline comments for this code. Rule: explain the "why," not the "what." Do not comment obvious operations. Comment: non-obvious decisions (why this algorithm, why this limit, why this order), constraints that aren't visible from the code (external API behavior, legal limits, performance requirements), known footguns or edge cases, and anything a developer would need to know before modifying this code. Style: [language-appropriate — e.g. # for Python, // for JS]. No block comments for things that belong in a docstring. Ship-ready.

Code:
[paste]

Context (what would surprise a developer reading this for the first time):
[describe any non-obvious decisions or constraints]

What it does
Produces comments that justify decisions rather than narrate code. "Loop through users" on a for loop wastes a line. "Process in batches of 50 — Mailgun's bulk send API rejects payloads larger than 1MB" on a batch loop is worth reading. The "what would surprise a new developer" context field is the most important input — it tells Claude exactly where the non-obvious decisions live.

Example output

def send_notifications(user_ids: list[str]) -> dict:
    results = {"sent": 0, "failed": 0, "skipped": 0}

    # Process in chunks of 100. The push notification provider (Firebase FCM)
    # accepts max 500 tokens per request, but 100 keeps individual request
    # payloads under the 1.5MB limit when notification bodies are long.
    for chunk in chunked(user_ids, 100):

        # Filter unsubscribed users here, not before chunking. The subscription
        # check is a DB call — doing it per-user before batching causes N+1 queries.
        active = [uid for uid in chunk if subscription_cache.is_active(uid)]
        results["skipped"] += len(chunk) - len(active)

        if not active:
            continue

        try:
            response = fcm_client.send_multicast(
                tokens=active,
                notification=build_notification(),
                # android_config TTL is 0 — deliver now or drop. These are
                # time-sensitive alerts; stale delivery is worse than no delivery.
                android_config=AndroidConfig(ttl=0),
            )
        except FirebaseError as e:
            # FCM errors are per-request, not per-token. Log and continue —
            # failing one chunk shouldn't block the rest of the batch.
            logger.error("FCM batch failed", chunk_size=len(active), error=str(e))
            results["failed"] += len(active)
            continue

        results["sent"] += response.success_count
        results["failed"] += response.failure_count

    return results

Why it works
"Explain the why, not the what" is the single rule that separates useful comments from noise. The constraint list (non-obvious decisions, external constraints, footguns) gives Claude a mental checklist to apply to every block of code. Without it, Claude comments the obvious operations and misses the non-obvious ones, which is exactly backwards.

Pro tip — Add "note any line that should not be modified without reading [external documentation or internal doc]" for code that interfaces with external systems. Comments like "# Do not change this header name — AWS SigV4 requires lowercase" save hours.

9. Write an Architecture Decision Record (ADR)

The Prompt

Write an Architecture Decision Record (ADR) for this decision. Structure:

Title: [short imperative phrase — e.g. "Use PostgreSQL for session storage"]
Status: [Proposed | Accepted | Deprecated | Superseded]
Context: What situation forced a decision? (3-5 sentences)
Decision: What did we decide? (1-2 sentences, direct)
Alternatives considered: What else was on the table and why rejected? (list, 2-3 alternatives)
Consequences: What becomes easier? What becomes harder? What new risks does this introduce?
Revisit trigger: What specific condition would cause us to reconsider?

Decision to document: [describe the decision and reasoning]
Why alternatives were rejected: [brief notes]
Known downsides accepted: [list]

What it does
Produces a complete ADR that future engineers can use to understand a decision without reading the Slack thread it was buried in. The "revisit trigger" section is the most underrated — it makes the decision reversible by design rather than permanent by default, and it forces the author to think about what conditions would make the decision wrong.

Example output

# Use Background Job Queue for Webhook Delivery

**Status:** Accepted

## Context

Our webhook delivery currently runs synchronously within the request that triggers
it. If the receiving server is slow or unreachable, our server holds the thread for
up to 30 seconds. Under load, this causes thread exhaustion and cascading slowness
across unrelated endpoints. Three incidents in the past six weeks have been traced
to a single customer's webhook endpoint going down and holding our threads hostage.

## Decision

Move all webhook delivery to a background job queue (BullMQ backed by Redis). The
triggering request enqueues the job and returns immediately. A worker pool handles
delivery asynchronously with retry logic.

## Alternatives Considered

**Fire-and-forget with Promise (no queue):** Faster to implement, but no retry
logic, no visibility into failures, and unhandled rejections in background Promises
are silent in Node 18 without explicit handling. Rejected: trades correctness for
convenience.

**Dedicated webhook microservice:** Correct architecture at scale, but introduces
a new service, inter-service auth, distributed tracing requirements, and a deploy
dependency. Rejected: operational overhead exceeds the problem's current size.

**Synchronous with timeout reduction:** Capping the webhook timeout at 3s reduces
thread hold time but doesn't eliminate it. Still fails under load. Doesn't add
retry logic. Rejected: partial mitigation, not a solution.

## Consequences

Easier:
- Endpoints that trigger webhooks no longer block on delivery latency
- Failed deliveries are automatically retried (3x, exponential backoff)
- Delivery attempts and failures are visible in the job dashboard

Harder:
- Webhook delivery is now eventually consistent — callers receive `202 Accepted`,
  not confirmation of delivery
- Local development requires Redis running
- Debugging delivery failures requires checking the job queue, not just logs

New risks:
- Redis becomes a dependency for webhook delivery; Redis outage means no webhooks
- Queue depth can grow unboundedly if the worker pool falls behind

## Revisit Trigger

Reconsider if: Redis operational cost exceeds $200/month before reaching 10k
webhooks/day, or if the product requires synchronous delivery confirmation
(certain financial compliance use cases). At that point, evaluate a dedicated
webhook service with its own SLA.

Why it works
ADRs are written infrequently and read constantly — often years later when the context is gone. The revisit trigger is the constraint that makes the document most useful: it tells the reader not just what was decided, but under what conditions the decision expires. The "alternatives considered + why rejected" section prevents future engineers from relitigating settled decisions without the context of what was already evaluated.

Pro tip — If your team uses a specific ADR template or wiki format, paste it into the prompt. Claude will match your format exactly. This prompt works equally well for decisions already made and decisions you're about to make — run it in "Proposed" status as a writing exercise before finalizing.

10. Write Error Message Documentation

The Prompt

Write documentation for these error messages. For each error: state the error code and message exactly as it appears, explain in plain English what state caused it (not just what the message says), list the two or three most common causes, and give the developer a clear resolution path — what to check, what to change, and what to do if none of those work. Do not just paraphrase the error message. Ship-ready markdown, formatted as a reference table + expandable details per error.

Errors to document:
[list error codes + messages, or paste from your error definitions file]

Context:
What system produces these errors: [describe briefly]
Target reader: [developer integrating this API / user of this SDK / etc.]

What it does
Turns error codes into actionable troubleshooting guides. The constraint "do not just paraphrase the error message" is what makes this prompt valuable — a documentation entry that says "INVALID_TOKEN: The token is invalid" adds nothing the developer didn't already know. "INVALID_TOKEN: The JWT signature verification failed. Common causes: wrong signing secret (check you're using the live key, not the test key), token generated by a different environment, or token expired and re-signed with a rotated key" saves 40 minutes of debugging.

Example output

## Error Reference

### AUTH_001 — Invalid or expired token

**Message:** `Authentication failed: token is invalid or has expired`

**What caused it:** The JWT presented in the `Authorization` header failed
signature verification, or the `exp` claim is in the past.

**Most common causes:**
1. **Wrong key environment.** You're using a test-mode key against the live API,
   or vice versa. Live keys start with `sk_live_`; test keys start with `sk_test_`.
2. **Token expired.** JWTs from this API expire after 1 hour. If you're caching
   tokens, check your cache TTL — it should be shorter than 1 hour to account
   for clock skew.
3. **Rotated signing secret.** If you rotated your API secret in the dashboard
   after generating the token, tokens signed with the old secret are immediately
   invalid.

**Resolution:** Generate a new token. If the error recurs immediately after
generating a fresh token, verify the key environment matches the API endpoint
you're hitting.

**Still stuck?** Open a support ticket with your `request_id` (in the response
header as `X-Request-ID`). Do not include the token itself in the ticket.

---

### RATE_001 — Rate limit exceeded

**Message:** `Rate limit exceeded: too many requests`

**What caused it:** Your integration has exceeded the allowed request rate for
your current plan. The `Retry-After` response header contains the number of
seconds until your rate limit resets.

**Most common causes:**
1. **Retry loop without backoff.** If your error handling retries immediately on
   any error, a single 5xx response can trigger a retry storm that trips the rate
   limit.
2. **Parallel requests from multiple processes sharing one key.** If you run
   multiple workers or servers, they share the same rate limit bucket per API key.
3. **Batch operation sending one request per item.** Use the `/batch` endpoints
   for bulk operations — they count as one request regardless of item count.

**Resolution:** Read the `Retry-After` header and wait before retrying. Implement
exponential backoff. If you need a higher rate limit, contact support — limits
are adjustable for production accounts.

Why it works
The "most common causes" pattern is the critical structure. Developers reading error documentation are already frustrated — they want to scan three options and try the most likely one, not read an essay. Numbering by likelihood (most common first) is an unconscious UX choice that significantly reduces the time-to-resolution for the average reader. The "still stuck" fallback with support escalation instructions closes the loop entirely.

Pro tip — Pair this with Prompt #6 (audit existing documentation) and ask Claude specifically to identify error messages in the codebase that have no documentation. Every undocumented error is a future support ticket.

The Bigger Principle

Documentation debt compounds the same way technical debt does. One sparse README means one hour of onboarding questions. Ten sparse READMEs, undocumented errors, and no ADRs means a codebase where institutional knowledge lives exclusively in the heads of whoever was there at the beginning.

The pattern across all 10 prompts is the same as the rest of this series: context + constraint + format. Context means the target reader and what the code actually does. Constraint means the rule that prevents Claude from defaulting to generic output — "document the contract, not the implementation," "explain the why not the what," "do not paraphrase the error message." Format means the specific structure that makes output paste-ready.

None of these prompts require reading ten pieces of documentation first. They require two minutes of context — who's the reader, what does this do, what's non-obvious. That's the trade: two minutes of context in exchange for documentation you'd be proud to ship.

Start with whatever type of documentation you've been putting off the longest. It is probably a README, because it always is.

Want the full pack?
This article covers 10 prompts. The Claude Prompts for Developers pack includes 55 prompts across 6 categories — code review, debugging, architecture, docs, productivity, and 5 multi-step power combos. The Writing & Documentation section alone has 15 prompts: full coverage for API references, SDK guides, runbooks, incident post-mortems, migration guides, and more. One-time download, copy-paste ready.

10 Claude Prompts for Better Architecture Decisions (With Examples)

Dev Prompts — Mon, 13 Apr 2026 14:52:56 +0000

Architecture decisions are the most expensive code you write — because you never write them.

They live in Slack threads, whiteboard photos, and the head of whoever was in the room that Thursday. When they go wrong, you don't get a stack trace. You get six months of "why is everything so hard to change?" — a codebase shaped by a conversation no one can fully reconstruct.

Most developers don't skip system design because they don't care. They skip it because the feedback loop is too slow. You design something, build it, then discover it was wrong three sprints later. AI doesn't fix bad judgment, but it can compress that feedback loop from weeks to minutes: surface trade-offs before you commit, stress-test assumptions before they calcify, document decisions before everyone forgets why.

These 10 Claude prompts for system design cover the architecture tasks that actually recur: decomposing vague requirements, analyzing trade-offs, reviewing systems for risk, writing ADRs, designing APIs, finding failure modes. If you've read the code review prompts or the debugging prompts, you know the format: copy-paste ready, paired with real example output, explained so you know when to reach for each one. Those prompts catch bugs in code and bugs in production. These catch bugs in decisions — before you write any code at all.

Before You Start: How to Feed Claude an Architecture Problem

Architecture is the hardest domain to AI-prompt because the context is massive. A code review prompt needs a diff. A debugging prompt needs a stack trace. An architecture prompt needs your entire system's shape — its constraints, scale, team, history, and the specific thing that's forcing a decision right now. Dumping all of that into every prompt is impractical. Trimming too much makes the answer useless.

The solution is to treat Claude's context window as a budget and spend it deliberately. Three tiers:

Always include (non-negotiable): A 5–10 sentence plain-text overview of what your system does and how data flows through it. Your tech stack and versions. The specific constraint or question driving the decision.

Include when relevant: Scale numbers — requests per second, data volume, growth rate. Team size and skill profile (three senior Go engineers is a different design space than twenty mixed-skill engineers). Existing pain points and tech debt. Compliance or regulatory constraints that eliminate certain options.

Trim aggressively: Implementation details of components not involved in the decision. Historical context older than six months unless it's directly relevant. Source code — architecture prompts rarely need code, they need descriptions of code.

The format that works: paste your system context as a labeled block at the top of every prompt, before the question. Here is a template you can copy once and reuse:

SYSTEM CONTEXT:
- What it does: [1-2 sentences]
- Architecture: [monolith | microservices | serverless | hybrid]
- Key components: [list services, stores, queues]
- Scale: [requests/day, data size, growth trajectory]
- Tech stack: [languages, frameworks, databases, infra]
- Team: [size, seniority, relevant expertise]
- Constraint: [the specific thing driving this decision]

Every prompt below assumes you paste this block first. The prompts are the question. The context block is what makes the answer worth reading.

The 10 Prompts

1. Break Down a Vague Requirement Into System Components

The Prompt

Given this product requirement, decompose it into concrete system components.
For each component: name it, define its single responsibility in one sentence,
identify its inputs and outputs, and flag any component where the requirement
is ambiguous. Do not recommend specific technologies yet — just map the
components and their boundaries.

Requirement: [paste requirement here]

SYSTEM CONTEXT:
[paste context block]

What it does
Takes a fuzzy product requirement — "we need real-time notifications," "we need an activity feed," "users should be able to collaborate on documents" — and breaks it into concrete system components with defined boundaries. Turns a whiteboard idea into something you can actually design.

Example output

Requirement: "Users need a real-time activity feed showing actions by people they follow."

Components:

1. Event Producer
   Responsibility: Emit a structured ActivityEvent whenever a tracked user action occurs
   Inputs: User action (create, like, follow, comment) from app services
   Outputs: ActivityEvent { actor_id, action_type, object_id, object_type, timestamp }
   Ambiguity: Which actions qualify? "Follow" and "post" seem clear; "view" is not mentioned
   but implies stalking risk — clarify before including.

2. Event Ingestion Pipeline
   Responsibility: Accept ActivityEvents and route them to the appropriate stores
   Inputs: ActivityEvents from producers
   Outputs: Written records to feed store + push notifications to delivery layer
   Ambiguity: None — standard fan-out problem.

3. Feed Storage
   Responsibility: Store pre-computed or on-demand feed entries per user
   Inputs: Routed ActivityEvents
   Outputs: Paginated feed entries on read
   Ambiguity: Fan-out-on-write vs. fan-out-on-read depends on follower counts not specified.
   High follower counts (>10k) break fan-out-on-write — need that number.

4. Real-Time Push Layer
   Responsibility: Deliver new feed events to connected clients without polling
   Inputs: ActivityEvents routed from ingestion
   Outputs: WebSocket/SSE push to active client sessions
   Ambiguity: "Real-time" — sub-second or eventual (a few seconds)? Different architectures.

5. Feed Read API
   Responsibility: Serve paginated feed to clients on request
   Inputs: authenticated user_id, pagination cursor
   Outputs: ordered list of ActivityEvents with actor metadata

Clarifying questions to take back to product:
- Which actions trigger an event?
- Max expected followers per user?
- Definition of "real-time" — latency SLA?

Why it works
Forcing component decomposition before technology selection prevents the most common architecture failure: choosing a tool before understanding the problem. The ambiguity-flagging instruction turns the prompt into a requirements clarification tool, not just a design tool.

Pro tip — After decomposition, run each component through Prompt #5 (API contract design) to define how they talk to each other before you start building any of them.

2. Analyze Trade-offs Between Two Architectural Approaches

The Prompt

Compare these two architectural approaches for my use case. For each approach,
evaluate it across these dimensions: implementation complexity, operational
complexity, scalability ceiling, time-to-ship, team skill fit, data consistency
guarantees, and reversibility (how hard is it to migrate away from this later).

Produce a comparison table. Then give me a direct recommendation — which approach
for my current context, and at what trigger point does the other approach become
the better choice?

Approach A: [describe first approach]
Approach B: [describe second approach]

SYSTEM CONTEXT:
[paste context block]

What it does
Takes two candidate approaches and produces a structured comparison across dimensions that matter — not just theoretical benefits, but fit against your actual constraints. Prevents "gut feel" decisions by making the trade-off surface explicit.

Example output

Context: Order management system, 3-person team, 8k orders/day, considering
event sourcing vs. CRUD + soft deletes.

| Dimension              | CRUD + soft deletes     | Event sourcing              |
|------------------------|-------------------------|-----------------------------|
| Implementation         | Low — patterns are      | High — CQRS, projections,   |
| complexity             | well-understood         | replay logic, event schema  |
| Operational complexity | Low — standard DB ops   | High — event store ops,     |
|                        |                         | projection rebuilds          |
| Scalability ceiling    | ~50k orders/day before  | Effectively unbounded for   |
|                        | write contention matters| write throughput             |
| Time-to-ship           | 2-3 weeks               | 6-10 weeks                  |
| Team skill fit         | Strong — standard ORM   | Low — team has no event     |
|                        | patterns                | sourcing experience          |
| Data consistency       | Strong — ACID           | Eventually consistent for   |
|                        |                         | read projections             |
| Reversibility          | High — standard schema  | Low — migrating away from   |
|                        | migration               | an event store is painful   |

Recommendation: CRUD + soft deletes for current context.

At 8k orders/day with a 3-person team and no event sourcing experience, the
operational overhead of event sourcing exceeds its benefits. You don't need the
audit trail, temporal queries, or write throughput that justify it.

Trigger point for reconsidering: if you need to replay business logic over
historical orders (e.g., recalculating loyalty points retroactively), or if
write throughput exceeds 30k orders/day and you've already optimized the CRUD
path. Either trigger means a migration — build the CRUD path with clean domain
events as a stepping stone.

Why it works
Enumerated comparison dimensions prevent Claude from writing a generic "it depends" essay. The "reversibility" dimension is the one most architects forget — it forces consideration of how painful the wrong choice is to undo, not just how good the right choice is.

Pro tip — Add your team's actual constraints: "We have 3 months, 2 backend engineers, and zero Kafka experience." Constraints collapse the theoretical trade-off space down to what actually matters for you.

3. Audit an Existing System for Scalability Risks

The Prompt

Review this system description and identify the components most likely to
become bottlenecks under 10x current load. For each risk: name the component,
describe the failure mode, estimate how close we are to hitting it (distance-
to-failure: near / medium / far based on current scale), and suggest one
mitigation. Rank by severity × proximity. Stop at the top 5.

SYSTEM CONTEXT:
[paste context block — include current traffic numbers]

What it does
Takes a description of your current system and identifies what breaks first under growth. Ranking by severity × proximity makes the output actionable: fix the near-term risks, plan for the medium-term ones, note the far-term ones and move on.

Example output

Current load: 800 req/s, 2M users, PostgreSQL + Redis, Node monolith, single region.

Risk 1 — PostgreSQL single writer (NEAR)
Failure mode: All writes (user events, orders, session updates) funnel through one
primary. At ~3,000-5,000 writes/sec the write-ahead log becomes a bottleneck.
At 800 req/s now with ~40% write ratio, you're at ~320 writes/sec. 10x puts you
at 3,200 — directly in the failure zone.
Mitigation: Audit write patterns now. Move high-frequency, low-value writes
(event logs, analytics) to a separate store. Read replicas for the read path.

Risk 2 — Redis with no eviction policy (NEAR)
Failure mode: Cache grows unbounded. When Redis runs out of memory it either
crashes (noeviction) or starts evicting arbitrarily (allkeys-lru, if set).
Either causes a cache stampede against Postgres.
Mitigation: Set maxmemory + allkeys-lru today. This is a one-line config change.

Risk 3 — Synchronous image processing on request threads (MEDIUM)
Failure mode: Image uploads block a Node worker thread for 200-800ms. At current
scale this is masked by low concurrency. At 10x, thread exhaustion causes
request queue backup across all endpoints.
Mitigation: Offload to a background job queue (BullMQ, SQS). Return a job ID,
poll or push for completion.

Risk 4 — Single-region deployment (MEDIUM)
Failure mode: Regional outage takes down the entire service. No failover path.
At 2M users, this is a business risk more than a scalability risk.
Mitigation: Multi-region read replicas first (lower blast radius, minimal cost),
active-active later if SLA demands it.

Risk 5 — Monolithic deploy unit (FAR)
Failure mode: As team grows, deployment coupling slows release velocity and a
bad deploy in one area takes down everything. Not a load problem — a team
scaling problem. Expect this to matter at 15+ engineers.
Mitigation: Not urgent. Extract high-churn modules into separate deploy units
when team size crosses the threshold, not before.

Why it works
"What breaks first under 10x" is a sharper question than "is this scalable." Forcing a ranked list with distance-to-failure estimates prevents Claude from producing an exhaustive academic analysis and keeps the output actionable.

Pro tip — Include your current traffic numbers in the context block. Without them, Claude can only say a risk exists. With them, it can estimate when the risk becomes a real problem.

4. Write an Architecture Decision Record (ADR)

The Prompt

Write an Architecture Decision Record (ADR) for this decision. Structure it as:

Title: [short imperative phrase]
Status: [Proposed | Accepted | Deprecated | Superseded]
Context: What is the situation that forced a decision?
Decision: What did we decide?
Alternatives considered: What else was on the table and why was it rejected?
Consequences: What are the trade-offs accepted? What becomes easier? What becomes harder?
Revisit trigger: What condition would cause us to revisit this decision?

Decision to document: [describe the decision and the reasoning behind it]

SYSTEM CONTEXT:
[paste context block]

What it does
Takes a decision you've already made (or are about to finalize) and produces a structured ADR that future engineers can actually use. The "revisit trigger" section is the most underrated part — it makes the decision reversible by design instead of permanent by default.

Example output

Title: Use DynamoDB for session storage

Status: Accepted

Context:
Our PostgreSQL primary currently stores all user sessions. Session reads account
for ~60% of total DB queries. Sessions have a simple key-value access pattern
(read by session_id, write on auth, delete on logout/expiry), no relational
requirements, and a 24-hour TTL. As we approach 5M users, session read volume
is becoming the largest contributor to Postgres connection pool exhaustion.

Decision:
Migrate session storage to DynamoDB. Use session_id as partition key, store
session payload as a JSON attribute, configure DynamoDB TTL on the expiry field
to handle automatic cleanup.

Alternatives considered:
- Redis: Evaluated first. Strong latency characteristics, but operational overhead
  of managing Redis cluster at scale (failover, eviction policy, memory sizing)
  exceeds DynamoDB's managed cost at our volume. Redis remains for application
  caching where sub-millisecond reads matter.
- Keep in Postgres with read replicas: Deferred the problem without solving it.
  Read replicas add ops cost; session data has zero relational value in Postgres.
- ElastiCache (Memcached): No persistence guarantees — session loss on node failure
  is unacceptable without application-level handling we don't want to own.

Consequences:
+ Removes ~60% of Postgres read load
+ Managed TTL eliminates session cleanup job
+ Scales independently of application DB
- Adds a new dependency (DynamoDB) to the data layer
- Session data is no longer queryable via SQL — admin tooling needs updating
- Local development now requires DynamoDB Local or a mock

Revisit trigger:
If session access patterns become relational (e.g., "list all active sessions for
a user" becomes a product requirement), or if DynamoDB costs exceed $500/month
before we reach 10M users, reconsider Redis with managed ElastiCache.

Why it works
ADRs are universally recognized as high-value and universally skipped because writing them is tedious. Claude handles the structure and prose; you supply the decision and enough context to make it accurate. The output is paste-ready into any ADR file or wiki.

Pro tip — If your team has an existing ADR template, paste it into the prompt. Claude will match your format exactly. If you don't have a template, this output is your template.

5. Design an API Contract Between Two Services

The Prompt

Design the API contract between these two services for the use cases described.
Produce: endpoint or method signatures, request and response schemas, error codes
and their meanings, idempotency strategy, versioning approach, and authentication
method. Design the failure case first — what does the caller do when this service
is unavailable or returns an error?

Service A (caller): [describe the calling service]
Service B (provider): [describe the service being called]
Use cases to support: [list the operations needed]

SYSTEM CONTEXT:
[paste context block]

What it does
Takes two services and the operations they need to exchange, and produces a concrete API contract — not just the happy path. The "design the failure case first" instruction is the key constraint. Most API design produces a sunny-day spec; this prompt produces a contract you can actually build against.

Example output

Services: Order Service (caller) → Inventory Service (provider)
Use case: Reserve stock for a new order before payment is captured.

--- CONTRACT ---

POST /v1/reservations
Authorization: Bearer {service-token}
Idempotency-Key: {order_id}  // Required — enables safe retries

Request:
{
  "order_id": "ord_abc123",       // string, required — used as idempotency key
  "items": [
    {
      "sku": "WIDGET-RED-M",
      "quantity": 2
    }
  ],
  "expires_at": "2026-04-13T12:30:00Z"  // when to auto-release if not confirmed
}

Response 201 — Full reservation successful:
{
  "reservation_id": "res_xyz789",
  "status": "reserved",
  "items": [{ "sku": "WIDGET-RED-M", "quantity": 2, "reserved": 2 }],
  "expires_at": "2026-04-13T12:30:00Z"
}

Response 207 — Partial reservation (some items unavailable):
{
  "reservation_id": "res_xyz789",
  "status": "partial",
  "items": [{ "sku": "WIDGET-RED-M", "quantity": 2, "reserved": 1 }]
}

Response 409 — Duplicate reservation (idempotency key already used):
{
  "error": "DUPLICATE_RESERVATION",
  "reservation_id": "res_xyz789"  // return existing reservation
}

Response 422 — Validation error:
{ "error": "INVALID_REQUEST", "details": "expires_at must be in the future" }

Response 503 — Inventory service unavailable

DELETE /v1/reservations/{reservation_id}
// Called if payment capture fails — releases reserved stock

Failure handling (caller's responsibility):
- 503 / network timeout: Retry with exponential backoff (100ms, 200ms, 400ms).
  Use Idempotency-Key — safe to retry.
- 207 partial: Order Service decides: proceed with partial items, cancel order,
  or return partial-availability response to the customer. Do not assume.
- If no response within 3s: assume failure, retry. Reservation auto-expires
  via expires_at if never confirmed — no manual cleanup needed.

Versioning: /v1/ prefix. Breaking changes increment to /v2/. v1 supported for
minimum 6 months after v2 ships.

Why it works
Listing "error codes," "idempotency strategy," and "failure handling" as explicit output requirements prevents the most common API design failure: specifying the happy path and leaving the rest to "we'll figure it out." The caller's failure handling section is the part that gets skipped most often and causes the most incidents.

Pro tip — After generating the contract, run it through Prompt #10 (failure modes) with "what are the most likely ways this API contract causes a production incident?"

6. Map the Single Points of Failure in a System

The Prompt

Given this system description, identify every single point of failure (SPOF) —
any component whose failure takes down the entire system or a critical user path.
For each SPOF: identify the component, describe the failure mode, estimate the
blast radius (what percentage of users/functionality is affected), and suggest
the minimal mitigation. Include human SPOFs — people, credentials, or knowledge
held by only one person.

SYSTEM CONTEXT:
[paste context block]

What it does
Maps every component in your system that is "one failure away from an outage." The blast-radius framing makes output actionable rather than a vague concern list. The human SPOF instruction catches the fragility that doesn't show up in architecture diagrams.

Example output

System: E-commerce checkout flow. PostgreSQL primary, Redis, Stripe, single
DNS provider (Cloudflare), 3 backend engineers.

SPOF 1 — PostgreSQL primary
Failure mode: Primary DB failure takes down all write operations — no orders can
be placed, cart cannot be saved, inventory cannot be updated.
Blast radius: 100% of transactional functionality. Read-only browse still works
if reads are on replicas.
Mitigation: Promote a read replica to primary (RDS Multi-AZ does this automatically
in ~60s). Verify your app reconnects on failover — not all ORMs handle this cleanly.

SPOF 2 — Stripe API
Failure mode: Payment gateway unavailability blocks all order completion.
Blast radius: 100% of checkout — users can browse and add to cart but cannot pay.
Mitigation: Circuit breaker in the payment service to fail fast and return a
clear error instead of hanging. Optionally: secondary processor (Braintree) on
the circuit-open path. Minimum: test your graceful-degradation path exists.

SPOF 3 — Single DNS provider (Cloudflare)
Failure mode: Cloudflare outage makes your domain unresolvable.
Blast radius: 100% of traffic — no users can reach the site at all.
Mitigation: Multi-provider DNS (Cloudflare primary + Route53 secondary) via
NS record delegation. Low cost, high payoff.

SPOF 4 — Synchronous email send blocking order confirmation
Failure mode: Email provider timeout (SendGrid, SES) causes order confirmation
HTTP request to hang or fail. If the transaction rolls back on email failure,
orders are lost silently.
Blast radius: Potentially 100% of orders if the code path is synchronous and
non-resilient. Risk is highest during email provider degradation events.
Mitigation: Decouple email send from order confirmation transaction. Place email
job in a queue; confirm the order regardless of email delivery.

SPOF 5 — Human: One engineer holds all production credentials
Failure mode: That engineer is unavailable during an incident. No one else can
access the production database, deploy a hotfix, or rotate a compromised key.
Blast radius: Operational paralysis during the engineer's absence.
Mitigation: Rotate all credentials into a shared secrets manager (1Password
Teams, AWS Secrets Manager). Document runbooks. At least two people should be
able to independently perform every production operation.

Why it works
"Single point of failure" is a precise enough concept that Claude can apply it systematically — tracing each path through the system and asking what happens if this node is gone. Requesting blast-radius estimates forces prioritization rather than an equal-weight concern list.

Pro tip — Run this before every major launch, not just during architecture reviews. Systems accumulate new SPOFs as features are added.

7. Evaluate Whether to Split a Monolith Into Services

The Prompt

Evaluate whether extracting [component/module] from our monolith into a separate
service is justified right now. Analyze: deployment coupling (how often does this
component cause deploys it doesn't own?), team ownership (does a different team
need to own this independently?), data coupling (how many DB tables does it share
with the rest of the monolith?), independent scalability (does this component
have meaningfully different load characteristics?), and operational cost (what
new concerns does a service split introduce?).

Give a go / no-go recommendation with the specific condition that would flip it.

SYSTEM CONTEXT:
[paste context block]

What it does
Applies the actual preconditions for microservices — not the theoretical benefits — to your specific situation. Most premature splits fail on operational cost and data coupling, not on architecture principles.

Example output

Question: Should we extract the notification system into its own service?

Current state: Notification logic lives in the monolith. Shares 3 DB tables
(users, preferences, notification_log) with core app. Called synchronously from
2 endpoints (post creation, follow event). Same team owns everything. 200k
notifications/day, growing at 15%/month.

Analysis:

Deployment coupling: LOW — notification code changes ~2x/month. Core app deploys
8-10x/month. When core deploys, notification code comes along for the ride, but
there's no evidence this is causing incidents or blocking releases.

Team ownership: LOW JUSTIFICATION — same team owns both. No organizational
forcing function for a service boundary.

Data coupling: HIGH — notifications directly read from users and preferences
tables. A service split requires either duplicating that data (sync problem) or
making cross-service DB calls (coupling traded for network latency).

Independent scalability: MODERATE — notification volume will diverge from app
volume as the product grows. At current scale (200k/day), this is not yet a
problem. At ~5M/day it likely is.

Operational cost introduced: Service registry, inter-service authentication,
network failure handling, separate deployment pipeline, distributed tracing,
separate on-call runbook. That's real overhead for a 3-person team.

Recommendation: NO — not yet.

Extract the notification system as a well-bounded *module* first: clear interface,
no direct DB access from outside the module, event-based integration internally.
That gives you the architectural discipline without the operational overhead.

Flip condition: Go when (a) a second team needs to own notifications independently,
or (b) notification throughput needs to scale independently and you've exhausted
in-process optimization, or (c) the notification module's data model has fully
decoupled from the core schema.

Why it works
The five-dimension analysis forces evaluation of preconditions, not benefits. Every "go microservices" decision should pass the ownership, data coupling, and operational cost tests first. The specific flip condition makes the recommendation time-bounded rather than permanent.

Pro tip — Add "assume we split — list every new operational concern we take on" to make the hidden cost visible before the decision is made, not after.

8. Design for a Specific Non-Functional Requirement

The Prompt

Design the architecture required to meet this specific non-functional requirement.
Work backward from the number: what components, patterns, and configuration changes
are required to hit it? Where are the trade-offs? What is the cheapest architecture
that meets this requirement — do not over-engineer.

NFR: [latency target | availability SLA | throughput target | consistency guarantee]
Current architecture: [brief description]

SYSTEM CONTEXT:
[paste context block]

What it does
Anchors the design to a concrete, measurable target and works backward from it. Prevents the most common NFR failure: designing for a vague goal ("it needs to be fast") and discovering the real requirement six months later.

Example output

NFR: API response time < 200ms at P99 under 10,000 req/s
Current: Node monolith, PostgreSQL, no cache, single region, average latency ~180ms

Working backward from 200ms P99 at 10k req/s:

At 10k req/s, your current ~180ms average will have a P99 well above 200ms
(typically 3-5x average under load). You're not currently meeting this at your
current traffic levels, let alone 10k req/s.

Required changes, cheapest to most expensive:

1. Read-through Redis cache for hot data ($50-100/month)
   Target: cut DB reads for top 80% of traffic by caching frequently accessed
   records with 30s TTL. Expected P99 impact: -60 to -80ms on cached paths.
   Trade-off: stale reads for up to 30s. Acceptable if data is not user-specific
   or safety-critical.

2. Database connection pooling via PgBouncer (free, self-hosted)
   Target: eliminate connection establishment overhead (~20-40ms per cold query
   under load). At 10k req/s, Postgres connection limits become a bottleneck
   before cache hits save you. Set pool size = (2 × CPU cores) + effective_spindle_count.

3. Move synchronous DB writes off the hot path (engineering cost)
   Audit writes on the P99 path. Audit log writes, analytics events, non-critical
   updates — queue them. Only block the response on writes the user actually needs
   to see.

4. CDN for static responses (negligible cost)
   Any response that is the same for all users in a 30s window can be cached at
   the CDN edge. Check if your public API endpoints qualify.

What you don't need yet: multi-region, read replicas, sharding, or event streaming.
Those are right answers for the wrong problem. The 200ms P99 target is achievable
with cache + connection pooling + async writes before you need any of that.

Estimated outcome: 200ms P99 achievable at 10k req/s with items 1-3. Validate
with load testing against production data shapes before shipping.

Why it works
A concrete number ("200ms P99") eliminates vague performance advice. Every recommendation must justify itself against that target. The "cheapest architecture" constraint prevents the response from escalating to Kubernetes and distributed caching for a problem that a Redis instance solves.

Pro tip — Pair with Prompt #3 (scalability audit) to make sure the NFR solution doesn't introduce new bottlenecks at 10x.

9. Translate a Technical Decision for a Non-Technical Stakeholder

The Prompt

Translate this technical architecture decision into language for a non-technical
stakeholder. Cover: what we're doing (no jargon), why in business terms (not
technical terms), what it costs (time, engineering effort, opportunity cost),
what happens if we don't do it, and what risks remain after we do.

Audience: [CFO | CEO | PM | Board member — choose one]
Decision: [describe the technical decision]

SYSTEM CONTEXT:
[paste context block]

What it does
Reframes a technical decision around what stakeholders actually care about: cost, risk, timeline, and consequences of inaction. The audience specification matters — a CFO cares about cost and downtime risk; a PM cares about feature timeline impact; a CEO cares about competitive and reputational risk.

Example output

Audience: CFO
Decision: Migrate from a single-server database to a distributed database cluster

What we're doing:
Right now, all of our customer data lives on a single database server — one
machine. We're moving it to three servers that work together, so no single
machine failure can take down the business.

Why in business terms:
Last quarter we had two database outages totaling 4 hours of downtime. Each hour
of outage costs approximately $12,000 in lost transactions plus support volume.
We also failed our enterprise SLA with two customers who are contractually owed
uptime credits. A three-node cluster eliminates the single point of failure that
caused both incidents.

What it costs:
6 weeks of engineering time (two engineers, full focus). $2,200/month increase
in infrastructure cost. Two weeks of feature development deprioritized while
migration is in progress.

What happens if we don't:
Based on current growth, we will exceed the capacity of the single server within
5-6 months. When that happens, we face either a planned migration under pressure
or an unplanned outage during a traffic spike. The enterprise contract renewals
in Q3 include uptime requirements we cannot currently guarantee.

Risks that remain after we do this:
The migration itself carries a risk of a 2-4 hour maintenance window, which we
will schedule off-peak. After migration, a regional cloud outage could still
take down the cluster — full geographic redundancy is a separate project.

Why it works
"No jargon" alone is not enough — Claude will just simplify the technical explanation. Explicitly requiring business-framing dimensions (cost, consequence of inaction, remaining risk) forces Claude to reframe the decision around what the stakeholder needs to make a decision, not what the engineer wants to communicate.

Pro tip — Specify the audience precisely. A PM who needs to adjust a roadmap cares about different dimensions than a CFO who needs to approve a budget line.

10. Run a Pre-Mortem on a Proposed Design

The Prompt

Run a pre-mortem on this proposed architecture. Assume it is 12 months from now
and this system has failed in production in a significant way. What are the most
likely causes? Cover: data loss scenarios, cascading failure paths, performance
cliffs that only appear at scale, operational complexity that overwhelms the team,
and failure modes that only surface under specific conditions (high concurrency,
partial network failures, specific data shapes).

Rank by likelihood × impact. Give me the top 5 only, with a one-sentence
mitigation for each.

Proposed design: [describe the architecture]

SYSTEM CONTEXT:
[paste context block]

What it does
Activates pessimistic reasoning against a design before any code is written. The "assume it has already failed" framing bypasses optimism bias. Ranking by likelihood × impact ensures you focus on the failures that are both plausible and consequential — not just the most dramatic theoretical scenarios.

Example output

Proposed design: Async job queue (Redis-backed BullMQ) with retry logic for
order fulfillment processing. Workers consume from the queue, call third-party
fulfillment API, update order status in Postgres.

Pre-mortem — top 5 failure modes:

1. Poison pill messages cause worker death spiral (HIGH likelihood × HIGH impact)
   A malformed fulfillment response causes a worker to throw on every retry.
   BullMQ retries it indefinitely (or to max attempts), keeping the worker busy
   on an unprocessable job. Other jobs queue up behind it.
   Mitigation: Dead-letter queue with alerting on DLQ depth > 0. Any job that
   fails N times moves to DLQ and pages on-call.

2. Queue depth grows unbounded when fulfillment API is slow (HIGH × HIGH)
   Fulfillment API degrades to 10s response time. Workers are all occupied on
   in-flight requests. New orders queue up faster than they're processed. Redis
   memory grows until OOM or jobs are dropped silently.
   Mitigation: Set max queue length. Alert on queue depth exceeding 15-minute
   processing capacity. Circuit-break when fulfillment API P99 > 5s.

3. Duplicate order fulfillment on worker crash mid-processing (MEDIUM × HIGH)
   Worker calls fulfillment API, job succeeds externally, worker crashes before
   marking job complete. BullMQ retries — fulfillment API is called again with
   same order. Duplicate shipment or charge.
   Mitigation: Idempotency key on all fulfillment API calls using order_id.
   Verify the fulfillment API supports idempotent retries before relying on this.

4. Silent data inconsistency when Postgres write fails after API success (MEDIUM × HIGH)
   Fulfillment API confirms the order; the subsequent Postgres status update fails
   (connection timeout, constraint violation). Order is fulfilled externally but
   shows "pending" internally. Customer support has no visibility.
   Mitigation: Wrap the status update in a retry with idempotency check. Add a
   reconciliation job that cross-checks fulfillment API status against DB state
   every 15 minutes.

5. No alerting on queue depth or worker count (HIGH likelihood × MEDIUM impact)
   This is the meta-failure: you won't know any of the above is happening until
   a customer complains. Queue depth, DLQ count, worker error rate, and
   fulfillment API error rate need to be in your monitoring before go-live.
   Mitigation: Add these four metrics to your dashboard and set alerts before
   shipping. Non-negotiable.

Why it works
"Pre-mortem" framing explicitly activates pessimistic reasoning — Claude looks for what goes wrong, not what could theoretically be improved. The specific failure categories (data loss, cascading failures, performance cliffs, operational complexity) prevent a generic "consider error handling" response. The top-5 constraint prevents an exhaustive catalog of everything that could theoretically fail.

Pro tip — The failures you anticipate here become the tests you write before launch. Take the top 3 failure modes and turn them into load tests or chaos engineering scenarios before the system ships.

The Bigger Principle

Architecture prompts are different from code-level prompts in one fundamental way: the quality of the output is bounded by the quality of the context you provide, not the quality of the question. A mediocre debugging prompt with a full stack trace still produces useful output. A brilliant architecture prompt with vague context produces confident-sounding nonsense.

The pattern across all 10 prompts is consistent: context block + specific question + output structure. The context block does the heavy lifting. The question narrows the focus. The output structure prevents the rambling "it depends" answer that architecture questions tend to attract.

These prompts don't replace an experienced architect. They replace the part of architecture work that is mechanical: enumerating trade-offs, checking for SPOFs, formatting ADRs, translating decisions into stakeholder language. The judgment is still yours. The prompts just make sure you're exercising that judgment with complete information — rather than whatever you can hold in your head during a 30-minute design meeting.

Start with the one that covers the decision you're staring at right now. The context block takes five minutes to fill out once. After that, each prompt takes 30 seconds to run.

10 Claude Prompts for Faster Debugging (With Examples)

Dev Prompts — Sun, 12 Apr 2026 10:40:30 +0000

Debugging is not about finding the bug. It is about finding the bug fast.

The actual fix is usually one line. Maybe two. The problem is everything before it — the hour you spend reading the wrong file, the three hypotheses that turned out wrong, the log statements you added and then forgot to remove. Stack traces point at symptoms, not causes. Error messages describe what broke, not why. And the real culprit is almost always three function calls away from where the exception surfaced.

The loop that kills time: read error → guess cause → add log → re-run → wrong guess → repeat. You are not debugging. You are narrowing down, very slowly, by trial and error. The bottleneck is not the fix. It is the diagnosis.

These 10 Claude prompts for debugging shortcut the narrowing-down phase. Each one targets a specific debugging scenario — cryptic stack traces, flaky tests, performance regressions, concurrency bugs — and gives Claude enough structure to produce a diagnosis, not just a restatement of the error. Copy-paste ready, with realistic examples showing what useful output actually looks like. If you use the code review prompts from the previous article to catch bugs before they ship, these are for the ones that got through anyway.

Before You Start: How to Feed Claude Error Context

No setup required. Claude works directly in the chat window, but the quality of the diagnosis depends entirely on the quality of the context you paste in.

Stack trace: Copy the full trace, not just the last line. Claude needs the call chain to distinguish root cause from symptom. The frame where the exception was thrown is rarely the frame where the bug lives.

Logs: Include 10–20 lines around the error timestamp. Trim irrelevant noise but keep the lines immediately before the failure — they often contain the state that caused it.

Relevant code: Paste the function or file the stack trace points to. If you are not sure which, paste the function you think is involved and the one that calls it. Two functions is almost always enough.

Repro steps + environment: A one-line description of how to trigger the bug beats nothing. "Click checkout with an expired card — expected error modal, got blank screen." Add language version and framework version in the same line. Claude can hallucinate version-specific behavior if you leave it unanchored.

The golden rule: more context equals a better diagnosis. A stack trace alone gets you a guess. A stack trace plus code plus repro steps gets you a root cause.

The 10 Prompts

1. Interpret This Stack Trace and Find the Root Cause

The Prompt

Analyze this stack trace and identify the root cause — not just the line that threw, but the code that caused it. Distinguish between the symptom (where the error surfaced) and the cause (where the real bug is). Ignore framework internals. Focus on my code. Show me the specific line responsible, explain why it causes this error, and suggest a fix.

Stack trace:
[paste here]

Relevant code:
[paste the file or function the trace points to]

What it does
Takes a raw stack trace and maps it to the actual root cause instead of the line that threw. Most stack traces point at library internals — Claude cuts through them to find the caller-side mistake.

Example output

Root cause: line 12 in process_order(), not line 47 where the TypeError surfaced.

  # orders/processor.py, line 12
  total = sum(item["price"] for item in cart_items)

  cart_items is None here — passed from get_cart() on line 8, which
  returns None when the cart session has expired instead of an empty list.

  The TypeError on line 47 ("NoneType is not iterable") is the symptom.
  The bug is the missing None check in get_cart()'s return path.

Fix:
  def get_cart(session_id: str) -> list:
      cart = db.get(f"cart:{session_id}")
      return cart if cart is not None else []

  # Or at the call site:
  cart_items = get_cart(session_id) or []

Why it works
Explicitly instructing Claude to separate symptom from cause prevents it from just restating the error message. Without that constraint, Claude defaults to explaining the exception type — not where it came from.

Pro tip — Add "ignore framework internals, focus only on my application code" when debugging Django, Rails, or Spring traces where the framework stack is 40 frames deep.

2. Explain Why This Error Happens, Not Just What It Says

The Prompt

I'm seeing this error. Explain why it happens at the mechanism level — not just what the message means, but what state in my code or environment causes it. Then tell me the 3 most likely causes given the code I've pasted, ranked by probability.

Error:
[paste error message]

Code:
[paste relevant function or file]

Language/framework: [e.g. Node.js 20, Express 4.18]

What it does
Translates cryptic error messages into plain-English explanations of the underlying mechanism. Goes beyond "what does this mean" to "what state in my code triggered this."

Example output

ECONNRESET means the remote server closed the TCP connection while your
code was still reading from it. This is different from a timeout — the
connection was open, then forcibly terminated mid-transfer.

3 most likely causes in your code, ranked:

1. (Most likely) Missing keepalive config on your http.Agent.
   Your createConnection() on line 14 uses the default agent, which
   doesn't send TCP keepalives. The upstream server is closing idle
   connections after ~30s. Fix: pass keepAlive: true to the agent.

2. The upstream server is crashing or restarting mid-request. The
   response body on line 29 is being consumed in a stream — if the
   server dies, you get ECONNRESET instead of a proper error code.
   Fix: add an 'error' event handler on the response stream.

3. Rate limiting at the network level (less likely given your logs).
   Some load balancers reset connections when a threshold is hit
   without returning an HTTP 429. Check upstream logs if #1 doesn't fix it.

Why it works
"Not just what it says" is the critical constraint. Without it, Claude produces dictionary definitions. The ranked-probability format makes the output actionable — you start with #1, not a list of ten equally-weighted possibilities.

Pro tip — Include the language and framework version. Error messages and their underlying causes change across versions. ECONNRESET in Node 14 has a different default behavior than Node 20.

3. Find the Bug: Here's What I Expected vs. What Actually Happened

The Prompt

Here is a function, what I expected it to do, and what it actually does. Find the specific line(s) causing the discrepancy. No stack trace — this is a logic bug that doesn't throw. Show the exact bug, explain why it produces the wrong output, and fix it.

Code:
[paste function]

Input: [paste sample input]
Expected output: [what you thought would happen]
Actual output: [what actually happened]

What it does
Diagnoses logic bugs that don't throw exceptions — the ones where the code runs fine and produces the wrong answer. The expected/actual framing gives Claude a concrete test oracle to reason against.

Example output

Bug: line 8, the comparison function does not handle ties.

  // Current
  const sorted = users.sort((a, b) => b.score - a.score)

  // When a.score === b.score, this returns 0.
  // JavaScript's Array.sort() is not guaranteed stable in all engines
  // for elements that compare equal — the relative order of tied users
  // is undefined, which is why the order changes on each run.

Fix (stable sort on ties — break by name alphabetically):
  const sorted = users.sort((a, b) => {
    if (b.score !== a.score) return b.score - a.score
    return a.name.localeCompare(b.name)
  })

  // If you need original-order stability for ties, use:
  const indexed = users.map((u, i) => ({ ...u, _i: i }))
  const sorted = indexed.sort((a, b) =>
    b.score !== a.score ? b.score - a.score : a._i - b._i
  )

Why it works
The expected/actual framing constrains Claude to a specific outcome to reason toward. "Find bugs" is open-ended and produces generic feedback. "Here is what I expected, here is what I got" is a test assertion — Claude solves backward from the failing case.

Pro tip — Include two or three sample input/output pairs, not just one. Edge cases in the data often reveal the bug faster than the primary example.

4. Debug This Flaky Test

The Prompt

This test sometimes passes, sometimes fails. I cannot reproduce it reliably. Analyze the test and the code it's testing for sources of nondeterminism. Check for: shared mutable state between tests, timing dependencies (sleeps, timeouts, async ordering), test-order dependencies, uncontrolled randomness, environment variable leakage, and database/filesystem state not cleaned up between runs.

Test code:
[paste test]

Code under test:
[paste relevant functions]

Failure output (when it fails):
[paste the error]

Passing output (when it passes):
[paste if different]

What it does
Identifies the nondeterminism source in tests that fail inconsistently. Flaky tests are usually one of six things — this prompt makes Claude check all six instead of guessing.

Example output

Source of flakiness: database state not cleaned up between test runs.

  # test_user_signup.py, line 31
  def test_signup_duplicate_email():
      create_user(email="test@example.com")
      with pytest.raises(DuplicateEmailError):
          create_user(email="test@example.com")

  This test passes when run in isolation. It fails when test_login_success
  runs first — that test also calls create_user("test@example.com") and
  does not clean up. On the second call here, the first insert from
  test_login_success is already in the DB, so the "duplicate" check fires
  on the first create_user() instead of the second.

  The test also has an implicit ordering dependency on test_login_success.
  In pytest, test execution order is deterministic by default but changes
  with -p randomly or across machines.

Fix:
  @pytest.fixture(autouse=True)
  def clean_users_table(db_session):
      yield
      db_session.execute("DELETE FROM users WHERE email LIKE '%@example.com'")
      db_session.commit()

  # Or use a transaction rollback fixture (preferred):
  @pytest.fixture(autouse=True)
  def rollback(db_session):
      yield
      db_session.rollback()

Why it works
Enumerated category lists act as a diagnostic checklist. Without the list, Claude picks the first plausible explanation. With it, Claude systematically checks each category before settling on a cause — which matters because flaky tests are often caused by the non-obvious category.

Pro tip — Include both the passing and failing output when available. The diff between them is often the fastest path to the root cause — the failure usually contains state from a previous test that the passing run doesn't have.

5. What Changed That Could Have Caused This Regression?

The Prompt

A regression appeared after the latest deploy. Here is the symptom and here is the git diff (or list of recent commits). Identify which change most likely introduced the bug. Explain the mechanism — how does that change produce this symptom? Then tell me what to verify to confirm it's the right suspect.

Symptom:
[describe what broke — error message, wrong behavior, performance change]

Git diff or recent commits:
[paste diff or git log --oneline output]

Affected code (if known):
[paste relevant function]

What it does
Narrows from "something broke after the last deploy" to "this specific change broke it, for this specific reason." Combines the diff with the symptom to do targeted bisection instead of reviewing the whole diff generically.

Example output

Most likely culprit: the ORM change in models/order.py (commit a3f9c2).

  # Before
  orders = Order.objects.filter(user=user)

  # After
  orders = Order.objects.filter(user=user).prefetch_related("items__product")

  The prefetch_related call looks like an optimization, but it's loading
  all items and products for every order in the queryset — not just the
  orders on the current page. With 500 orders per user, this is now
  fetching 8,000–12,000 rows on every request instead of 20–40.

  This matches your symptom: response time went from ~180ms to ~3.4s
  exactly when this commit deployed, and only for users with large order histories.

To confirm:
  1. Run EXPLAIN ANALYZE on the query for a user with 200+ orders
  2. Add Django Debug Toolbar to the endpoint and count the queries
  3. Check if the issue is absent for new users (< 10 orders) — if so,
     it confirms the data-volume dependency

Why it works
Giving Claude both the diff and the symptom lets it do targeted causal reasoning. A diff alone produces a generic review. A symptom alone produces speculation. Together, they constrain the problem space to where the diff's changes intersect with the symptom's behavior.

Pro tip — Use git log --oneline -20 as the input when you don't have a specific diff. Claude can rank which commits are worth investigating based on the files touched relative to the symptom.

6. Debug This Performance Bottleneck

The Prompt

This code is slow. Here are the symptoms (latency numbers, profiler output, or observed behavior). Identify the bottleneck. Check for: algorithmic complexity issues, unnecessary or sequential I/O that could be parallelized, N+1 queries, blocking calls in async code, memory allocation patterns causing GC pressure, and missing indexes. Show the specific line(s) causing the slowness and suggest a fix.

Code:
[paste slow function or endpoint handler]

Performance symptoms:
[e.g. "P99 latency 3.2s, was 200ms before commit abc123" or profiler output]

Language/framework: [e.g. Go 1.22, Gin]

What it does
Identifies the specific bottleneck in slow code. Covers the categories that are responsible for 90% of real performance issues: I/O patterns, query problems, algorithmic complexity, and memory.

Example output

Bottleneck: three sequential database calls on lines 18, 24, and 31 that can run concurrently.

  // Current — sequential, ~900ms total
  user, err := db.GetUser(ctx, userID)          // ~300ms
  orders, err := db.GetOrders(ctx, userID)      // ~300ms
  prefs, err := db.GetPreferences(ctx, userID)  // ~300ms

  These three queries are independent — none depends on the result of
  another. Running them sequentially is costing you ~600ms of unnecessary
  wait time.

Fix (parallel with errgroup):
  var (
      user  *User
      orders []Order
      prefs  *Preferences
  )
  g, gctx := errgroup.WithContext(ctx)
  g.Go(func() error { user, err = db.GetUser(gctx, userID); return err })
  g.Go(func() error { orders, err = db.GetOrders(gctx, userID); return err })
  g.Go(func() error { prefs, err = db.GetPreferences(gctx, userID); return err })
  if err := g.Wait(); err != nil {
      return nil, err
  }

  Expected result: ~300ms total (limited by the slowest single query).

Secondary issue: GetOrders() on line 24 is missing a WHERE clause index.
Run EXPLAIN ANALYZE — if you see Seq Scan on orders, add:
  CREATE INDEX idx_orders_user_id ON orders(user_id);

Why it works
Listing specific bottleneck categories prevents Claude from defaulting to generic advice ("add caching," "use a CDN"). The categories act as a scan checklist. The request for specific lines forces a concrete diagnosis rather than a performance lecture.

Pro tip — Include actual latency numbers or profiler output. "It's slow" gets generic advice. "P99 went from 200ms to 3.2s after deploying commit abc123" gets a diagnosis.

7. Debug This Async/Concurrency Bug

The Prompt

This code has a concurrency bug. Analyze it for: race conditions on shared state, deadlocks, missing awaits or unhandled promise rejections, incorrect assumptions about execution order, and goroutine/thread leaks. Trace two concurrent executions of this code step by step to show the exact interleaving that causes the bug. Then show the fix.

Code:
[paste the async or concurrent function(s)]

Symptom:
[describe what you observe — panic, wrong value, hang, intermittent failure]

Language/runtime: [e.g. Go 1.22, Node.js 20]

What it does
Analyzes concurrent code for the class of bugs that are invisible to line-by-line reading. Race conditions, deadlocks, and ordering bugs only appear when you trace multiple execution paths simultaneously — which is exactly what this prompt forces.

Example output

Race condition: concurrent writes to the shared cache map on lines 8 and 14.

  var cache = map[string]int{}  // shared across goroutines

  func increment(key string) {
      val := cache[key]     // READ  — goroutine A
      cache[key] = val + 1  // WRITE — goroutine A
  }

Two concurrent executions:

  Goroutine A: reads cache["hits"] → 5
  Goroutine B: reads cache["hits"] → 5  (before A writes)
  Goroutine A: writes cache["hits"] = 6
  Goroutine B: writes cache["hits"] = 6  (overwrites A, loses one increment)

  After 2 increments: cache["hits"] == 6 instead of 7.
  At high concurrency this also triggers "concurrent map read and map write" panic.

Fix (atomic counter):
  var counters sync.Map

  func increment(key string) {
      val, _ := counters.LoadOrStore(key, new(int64))
      atomic.AddInt64(val.(*int64), 1)
  }

  // Or with a mutex if you need the full map readable:
  var (
      mu    sync.RWMutex
      cache = map[string]int{}
  )
  func increment(key string) {
      mu.Lock()
      defer mu.Unlock()
      cache[key]++
  }

Why it works
Asking Claude to "trace two concurrent executions step by step" forces multi-path reasoning. Without that instruction, Claude reads the code sequentially and misses the interleaving. The step-by-step trace also makes the explanation immediately understandable — you see exactly where the paths collide.

Pro tip — Add "check for goroutine leaks — are there paths where a goroutine could block forever?" for Go code involving channels or context.WithCancel.

8. Debug This Third-Party API Integration Error

The Prompt

I'm getting an error from a third-party API. Here is the full HTTP request I'm sending (or the SDK call), the full response I'm receiving (headers + body), and the relevant calling code. Diagnose the integration issue. Check for: auth errors (wrong key, wrong header, wrong scope), payload format mismatches (wrong field names, wrong types, missing required fields), rate limiting, wrong API endpoint or version, and timeout configuration.

API: [name and version, e.g. Stripe API v2023-10-16]
Error response: [paste full response including headers]
Your request: [paste the outgoing request or SDK call]
Relevant code: [paste the function making the call]

What it does
Diagnoses integration errors between your code and external APIs. API errors are notoriously misleading — a 400 Bad Request can mean a wrong field name, a missing required field, a type mismatch, or an outdated API version. This prompt makes Claude check all of them.

Example output

The 400 error is caused by a webhook signature verification mismatch.

  # Your code (line 22)
  stripe.webhook.construct_event(
      payload, sig_header, os.environ["STRIPE_WEBHOOK_SECRET"]
  )

  STRIPE_WEBHOOK_SECRET is set to your test mode webhook secret
  (starts with whsec_test_...), but the webhook is coming from a
  live mode endpoint. Stripe uses separate signing secrets for test
  and live webhooks — they are not interchangeable.

How to confirm:
  1. Go to Stripe Dashboard → Webhooks → your endpoint
  2. Check which mode the endpoint is in (test or live)
  3. Copy the correct signing secret for that mode

Also check: your endpoint is consuming the raw request body before
parsing it. If you run body-parser or any middleware that reads the
stream before this handler, the signature verification will fail
even with the correct secret.

  # Flask — must use request.get_data(as_text=True) not request.json
  payload = request.get_data(as_text=True)

Why it works
API errors often have misleading messages that describe the consequence, not the cause. Claude cross-references the error code, the request, and the code together — something you can't do by Googling the error message alone.

Pro tip — Always include full HTTP headers in the request and response, not just the body. Auth issues hide in headers (Authorization, Stripe-Signature, X-API-Key) and are invisible if you only paste the JSON body.

9. Write a Minimal Reproduction Case for This Bug

The Prompt

Here is a bug and the code it occurs in. Write the smallest possible standalone script that reproduces the issue. Requirements: (1) it should run with zero external dependencies if possible, (2) it should reliably trigger the bug when executed, (3) it should contain only the code necessary to show the bug — strip out everything else. Show the expected vs. actual output when the script runs.

Bug description:
[describe what goes wrong]

Relevant code:
[paste the functions involved]

Language: [e.g. Python 3.12]

What it does
Produces a minimal, standalone reproduction case — the thing you need for bug reports, teammate communication, and regression tests. Stripping out framework and dependencies isolates the core bug and often reveals it more clearly than the original code does.

Example output

# Minimal reproduction — race condition in cache invalidation
# Run with: python repro.py
# Expected: cache["value"] == 0 after both threads complete
# Actual:   cache["value"] is nondeterministic (usually 1 or 2)

import threading

cache = {"value": 0}

def increment_and_reset():
    val = cache["value"]       # read
    cache["value"] = val + 1   # write
    cache["value"] = 0         # reset

threads = [threading.Thread(target=increment_and_reset) for _ in range(100)]
for t in threads: t.start()
for t in threads: t.join()

print(f"Final value: {cache['value']}")  # should be 0, usually isn't

# Root cause: read-modify-write is not atomic.
# Two threads can read val=0, both write val=1, then both write val=0.
# But if thread A writes 1 after thread B's reset, final value is 1.

Why it works
"Minimal" and "standalone" are the critical constraints. Without them, Claude pastes back your original code with minor edits. The minimum-dependencies constraint forces distillation to the bug's essence — which is useful for bug reports, sharing with library maintainers, and writing a regression test that will never have setup issues.

Pro tip — Add "make it runnable with zero dependencies" for maximum portability. A repro case that requires a running database is harder to share and harder to run in CI as a regression test.

10. Explain the Fix So I Can Prevent This Class of Bug in Future

The Prompt

I just fixed this bug. Explain it at the class level — not just why this specific instance happened, but what category of bug this is, why this category is common, what programming patterns or practices prevent it, and where else in my codebase the same class of bug is likely to exist. Then suggest one linting rule or test pattern that would catch it automatically.

The bug: [describe what it was]
The fix: [describe or paste what you changed]
Codebase context: [language, framework, rough size — e.g. "Python Django monolith, ~40k lines"]

What it does
Turns a one-time fix into a permanent skill upgrade. After you find and fix a bug, this prompt extracts the generalizable lesson: what class of bug it was, why it recurs, and how to prevent the whole category rather than this one instance.

Example output

Class: Fencepost error (off-by-one in boundary conditions).

This is one of the most common bugs in any code that works with
sequences, ranges, or pagination. The name comes from the problem of
counting fence posts vs. fence sections: N sections require N+1 posts.
Developers consistently conflate "number of elements" with "last valid index."

Why it recurs:
  Arrays are 0-indexed but lengths are 1-indexed. Page numbers are
  1-indexed but offsets are 0-indexed. Date ranges use inclusive or
  exclusive bounds inconsistently. Every time you write a loop bound
  or a slice, you're making an implicit decision about which convention
  you're following — and it's easy to get it wrong silently.

Where to look in your codebase:
  Any function containing: page, offset, limit, slice, range, index,
  chunk, batch, cursor, or start/end parameters. Specifically search for:
  - `OFFSET (page - 1) * limit` — wrong if page is 0-indexed
  - `items[0:n]` — check if n is inclusive or exclusive
  - `range(1, len(items))` — check if 0 should be included

Linting rule: write a parametrized test fixture that runs every
pagination function with page=0, page=1, page=last, and page=last+1.
Fencepost bugs almost always appear at exactly these four boundaries.

  @pytest.mark.parametrize("page,expected_first_id", [
      (1, 1),     # first page
      (2, 11),    # second page
      (10, 91),   # last full page
      (11, None), # beyond last page — should return empty, not error
  ])
  def test_pagination_boundaries(page, expected_first_id):
      results = get_items(page=page, per_page=10)
      ...

Why it works
"Class of bug" framing forces Claude to abstract from the specific instance to the reusable lesson. The "where else in my codebase" question makes the output immediately actionable — you get a search pattern you can run right now, not just a general principle.

Pro tip — Add "suggest a linting rule or static analysis check that would catch this automatically" to turn the lesson into an enforceable guardrail that catches future instances without any manual review.

The Bigger Principle

Debugging with AI is not "paste error, get fix." That works for trivial cases. For real bugs — the ones that cost hours — the value is in the narrowing. These prompts work because they give Claude a specific diagnostic task with enough context to reason about, not an open-ended "help me debug this."

The pattern is always the same: context + constraint + format. Context means the stack trace, the code, the repro steps — whatever Claude needs to reason about state and execution paths, not just syntax. Constraint means what to focus on: root cause not symptom, mechanism not definition, minimal reproduction not paraphrased description. Format means how to deliver the output: specific line numbers, step-by-step execution trace, ranked hypotheses with verification steps.

A prompt that gives Claude all three produces a diagnosis. A prompt that gives Claude one or two produces a lecture. The difference between debugging for 10 minutes and debugging for two hours is usually the quality of the question you ask first.

Build a personal prompt library for your recurring debugging scenarios. The prompts you reach for every week are worth tuning to your stack and your codebase. The ones you use once are fine as-is. Start with the one that matches your most expensive debugging pain — the class of bug that reliably costs you the most time. Build from there.

Bookmark this. Next time a stack trace lands in your terminal, paste one of these before you add a single log statement.

Want the full pack?
This article covers 10 prompts. The Claude Prompts for Developers pack includes 55 prompts across 6 categories — debugging, architecture, docs, productivity, and 5 multi-step power combos. One-time download, copy-paste ready.

10 Claude Prompts for Faster Code Reviews (With Examples)

Dev Prompts — Thu, 09 Apr 2026 02:06:01 +0000

Code reviews are not the hard part of shipping. They are the slow part.

Not because the feedback is difficult to give — because most of it is mechanical. Pointing out that a variable name is ambiguous, that an error is not being handled, that a helper function already exists three files over. That is not high-order thinking. That is cognitive tax on work that should have been caught before the PR was opened.

The result: reviewers burn their best focus on style nits and boilerplate comments. Real issues — the ones about architecture, data flow, edge cases that will haunt you in production — get a skim. PRs pile up. Context decays. The person who opened the PR rewrites the diff in their head three times before anyone looks at it.

These 10 Claude prompts fix the mechanical half. They are the ones I actually use — not assembled from a listicle, but refined through the kind of trial and error that happens when a PR queue gets genuinely out of hand. Each prompt is copy-paste ready, explained so you know when to reach for it, and paired with a real example showing what useful output looks like.

Here is what to do with them.

Before You Start: How to Feed Claude a Diff

No plugin, no IDE extension, no setup required. The fastest path: run git diff HEAD~1 | pbcopy (macOS) or git diff HEAD~1 | xclip (Linux), then paste directly into Claude's chat window. For a full file review, just open the file and paste the contents. For a PR diff from GitHub, hit the "Files changed" tab, copy the raw diff, paste it in. That's the entire workflow. The 10 prompts below are designed to be dropped in immediately after your diff — each one targets a different failure mode that human reviewers consistently miss.

The 10 Prompts

1. Find Bugs, Not Style Issues

The Prompt

Review this diff for logic errors, null dereferences, race conditions, and off-by-one errors only. Ignore formatting, naming conventions, and style. For each bug found, show me the exact line, explain why it's a bug, and suggest a fix. If you find nothing, say so explicitly.

[paste diff here]

What it does
Focuses Claude entirely on correctness bugs — the ones that ship to production. By explicitly excluding style feedback, you stop Claude from burying a real null deref under six comments about variable naming.

Example output

Bug 1 — Null dereference (line 34)
  const user = await db.findUser(id)
  return user.profile.email  // user can be null if id not found

Fix:
  const user = await db.findUser(id)
  if (!user) throw new NotFoundError(`User ${id} not found`)
  return user.profile.email

Bug 2 — Race condition (lines 51-58)
  async function incrementCounter(key: string) {
    const val = await redis.get(key)  // read
    await redis.set(key, Number(val) + 1)  // write — not atomic
  }

Fix: Use redis.incr(key) instead — single atomic operation.

No other bugs found.

Why it works
Negative constraint prompting ("ignore X") prevents attention dilution — Claude stays on the high-signal task.

Pro tip — Pipe in a specific file instead of a diff: cat src/payments.ts | pbcopy, then add "focus on the payment processing logic only."

2. Review This Diff as a Senior Engineer on the Team

The Prompt

You are a senior engineer who has worked on this codebase for 2 years. You care about maintainability, pragmatic architecture, and not over-engineering. Review this diff. Comment on architectural trade-offs, whether abstractions are at the right level, and anything that will hurt the team in 6 months. Be direct, not diplomatic.

[paste diff here]

What it does
Shifts Claude out of generic reviewer mode into an opinionated senior engineer persona. The "2 years on this codebase" framing produces taste-driven feedback about abstractions and trade-offs, not just correctness.

Example output

The new UserService class looks fine on the surface, but you've split
what was one simple fetch + transform into 4 layers: repository,
service, mapper, and DTO. For a read-only endpoint that never changes
business rules, that's accidental complexity.

The mapper is doing work that could be a one-liner in the controller:
  // Before
  return UserMapper.toResponseDTO(UserMapper.fromEntity(entity))

  // What you actually need
  return { id: entity.id, name: entity.name, email: entity.email }

The abstraction will pay off if the domain logic grows. Right now it
doesn't exist. I'd collapse the mapper until you actually need it.

The repository pattern here is fine — keep it. DB access should be
abstracted. The service layer boundary is also correct. Just cut the mapper.

Why it works
Role + tenure + value system = highly specific persona. Claude produces opinions, not hedged suggestions.

Pro tip — Add your actual stack: "You're a senior Go engineer who hates global state and prefers explicit error returns over panics."

3. What Edge Cases Does This Code Miss?

The Prompt

Given this code, list every edge case it does not handle. Think about: empty inputs, nil/null values, boundary values (0, -1, MaxInt), concurrent access, network timeouts, malformed data, and unexpected types. For each edge case, show what would currently happen and what should happen instead.

[paste diff or function here]

What it does
Forces a systematic adversarial pass through your code. This is the prompt to run before writing tests — it maps the territory first, then you can cover it.

Example output

Edge case 1 — Empty slice input
  func Average(nums []float64) float64 {
    total := 0.0
    for _, n := range nums { total += n }
    return total / float64(len(nums))  // divide by zero if len == 0
  }
  Currently: panic: runtime error: floating-point division by zero
  Should be: return 0, ErrEmptySlice or return math.NaN()

Edge case 2 — Concurrent writes to shared cache
  var cache = map[string]string{}
  func Set(k, v string) { cache[k] = v }
  Currently: data race — map writes are not goroutine-safe
  Should be: sync.RWMutex or sync.Map

Edge case 3 — Negative pagination offset
  GET /items?page=-1
  Currently: generates SQL OFFSET -20, driver-specific behavior
  Should be: validate page >= 1 before query execution

Why it works
Enumerated category lists ("think about: X, Y, Z") act as a mental checklist that prevents Claude from stopping at the first few obvious cases.

Pro tip — Append "then write a test for the three most dangerous ones" to get code immediately.

4. Summarize This PR in 3 Bullet Points for a Reviewer With Zero Context

The Prompt

Summarize this PR in exactly 3 bullet points for a reviewer who has never seen this codebase. Each bullet should answer one of: (1) what changed, (2) why it changed, (3) what could go wrong. Be concrete — reference actual class names, function names, and file paths where relevant. No marketing language.

[paste diff here]

What it does
Generates the PR description your team actually needed. Also useful as a sanity check — if Claude can't summarize the PR clearly, the PR is probably too large or lacks coherent scope.

Example output

- **What changed:** `AuthMiddleware` in `src/middleware/auth.ts` now
  validates JWT expiry using server time instead of the token's `iat`
  claim, fixing a 6-hour clock skew bug that let expired tokens pass.

- **Why it changed:** Tokens issued on mobile clients with misconfigured
  clocks were passing validation indefinitely. Reported in issue #441.

- **What could go wrong:** Any client that relies on the old behavior
  (token valid for `exp - iat` seconds regardless of server time) will
  now get 401s on previously valid tokens. Check `AuthService.refresh()`
  — it may need a corresponding update to issue tokens with corrected timestamps.

Why it works
The three-question structure forces completeness — "what/why/risk" covers the full reviewer mental model in minimal words.

Pro tip — Use it in reverse: paste this output back to Claude and ask "does the diff actually match this summary?" to catch scope creep.

5. Does This Change Break Backward Compatibility?

The Prompt

Analyze this diff for backward compatibility issues. Check for: removed or renamed public API methods, changed function signatures, modified database schema without migration, changed JSON field names in request/response bodies, changed environment variable names, and altered default behavior. List each breaking change with its severity (breaking vs. deprecation-worthy) and a migration path.

[paste diff here]

What it does
Runs a compatibility audit against the most common sources of silent breakage — API contracts, schema changes, and configuration drift. Critical before any library release or service deployment.

Example output

Breaking change (BREAKING) — Renamed method
  // Before
  client.createUser(params: UserParams): Promise<User>
  // After
  client.addUser(params: CreateUserParams): Promise<UserRecord>

  Three things changed: method name, param type name, return type name.
  Any caller using the old signature breaks at compile time (TypeScript)
  or runtime (JavaScript). Migration: keep createUser as a deprecated
  alias for one minor version.

Breaking change (BREAKING) — Schema change without migration
  // users table: `display_name` column renamed to `full_name`
  // No migration file found in /db/migrations/

  Existing rows are unaffected but all queries using `display_name`
  will fail with column-not-found. Need: migration + ORM model update
  + API response field rename (separate BC issue).

Deprecation-worthy — Removed default timeout
  fetchData() previously defaulted to 5000ms. Now requires explicit
  timeout param. Old callers will hang on slow responses.

Why it works
Explicit enumerated checklist ("check for: X, Y, Z") ensures coverage across the 6 most common BC failure modes, not just the obvious ones.

Pro tip — Add your semver policy: "We follow semver. Flag anything requiring a major bump separately."

6. Write the Test Cases This PR Is Missing

The Prompt

Based on this diff, write the unit tests that are missing. Use [TypeScript/Jest | Python/pytest | Go testing] — match whatever is in the diff. Write actual test code, not descriptions. Cover: the happy path if not already tested, the top 3 edge cases, and at least one failure/error scenario. Use realistic test data, not placeholder strings like "test" or "foo".

[paste diff here]

What it does
Produces runnable test code, not a list of "you should test X." The realistic-data constraint matters — placeholder strings hide bugs that only appear with real-world input shapes.

Example output

# Python/pytest — for process_payment(amount, currency, user_id)

def test_process_payment_success():
    result = process_payment(amount=99.99, currency="USD", user_id="usr_abc123")
    assert result.status == "succeeded"
    assert result.amount_charged == 9999  # stored as cents

def test_process_payment_zero_amount_raises():
    with pytest.raises(ValueError, match="Amount must be greater than 0"):
        process_payment(amount=0, currency="USD", user_id="usr_abc123")

def test_process_payment_unsupported_currency():
    with pytest.raises(UnsupportedCurrencyError):
        process_payment(amount=10.00, currency="XYZ", user_id="usr_abc123")

def test_process_payment_invalid_user_id_raises():
    with pytest.raises(UserNotFoundError):
        process_payment(amount=10.00, currency="USD", user_id="usr_NOTREAL")

def test_process_payment_negative_amount_raises():
    with pytest.raises(ValueError):
        process_payment(amount=-5.00, currency="USD", user_id="usr_abc123")

Why it works
"Write actual code, not descriptions" is the critical constraint. Without it, Claude defaults to a bulleted test plan. The language-matching instruction keeps output paste-ready.

Pro tip — Add "also write a test that would have caught the bug this PR fixes" if there's a bug fix in the diff.

7. Rate the Error Handling: What Fails Silently?

The Prompt

Audit the error handling in this code. Find: swallowed exceptions (catch blocks that don't re-throw or log), errors returned but never checked by callers, operations that can fail but have no error path, and places where errors are logged but execution continues incorrectly. Rate overall error handling 1-10 and explain the rating.

[paste diff here]

What it does
Targets the category of bugs that cause 2am incidents — the ones that don't throw, don't log, just silently corrupt state or return wrong data. The numeric rating gives you a quick signal for whether to approve or request changes.

Example output

Rating: 4/10

Issues found:

1. Swallowed exception (line 23)
   try {
     await sendWelcomeEmail(user.email)
   } catch (e) {
     // TODO: handle this
   }
   User creation succeeds, email silently drops. Caller has no idea.
   Fix: log the error + consider whether email failure should fail
   the whole operation or be queued for retry.

2. Unchecked return value (line 41)
   db.exec("DELETE FROM sessions WHERE user_id = ?", userId)
   // result is ignored — could be sql.ErrNoRows, driver error, etc.
   Fix: check err return; a failed session delete is a security issue.

3. Error logged, execution continues incorrectly (lines 67-72)
   if err := cache.Set(key, val); err != nil {
     log.Error("cache write failed", err)
   }
   // then immediately reads from cache as if write succeeded
   Fix: branch on err; fall back to DB read or abort the operation.

Why it works
Naming the specific anti-patterns ("swallowed exceptions," "never checked") gives Claude a concrete taxonomy to scan against rather than a vague "check error handling."

Pro tip — Add "flag anything that would cause data inconsistency if it fails silently" to prioritize the critical issues.

8. Explain This Code to a New Team Member

The Prompt

Explain this code to a new team member joining the project today. They're a competent developer but have zero context on this codebase. Cover: what this code does, why it exists (what problem it solves), any non-obvious decisions or gotchas, and what they'd need to know to safely modify it. Write it as a comment block they could paste above the function.

[paste function or file here]

What it does
Acts as a readability gut-check: if Claude can't explain the code clearly, the code probably can't explain itself. The comment-block output format means you get a usable artifact, not just a review opinion.

Example output

// OrderProcessor handles payment capture and inventory reservation
// in a single atomic-ish operation.
//
// WHY THIS EXISTS: We had incidents where payments succeeded but
// inventory reservation failed, leaving orders in a zombie state.
// This processor uses a two-phase approach: reserve inventory first
// (cheap to roll back), then capture payment. If payment fails,
// inventory is released.
//
// NON-OBVIOUS DECISIONS:
//   - ReserveInventory uses a 30s advisory lock, not a transaction.
//     The lock TTL is intentional: long enough for payment (typically
//     <5s) but short enough to self-heal if the process dies.
//   - We call Stripe's capture endpoint, not charge. Pre-auth happens
//     at checkout. This function only finalizes it.
//
// SAFE TO MODIFY IF:
//   - You understand the inventory lock lifecycle (see InventoryService)
//   - You've read the Stripe capture docs — partial captures behave
//     differently from full captures
//   - You test with the "payment_intent.payment_failed" webhook fixture
//
// DO NOT: add sleeps or synchronous external calls between Reserve and
// Capture. The lock window is tight by design.
func (p *OrderProcessor) Process(ctx context.Context, order Order) error {

Why it works
Asking for a paste-ready comment block makes the output immediately actionable and forces Claude to be structured rather than conversational.

Pro tip — Ask "what would a new engineer most likely break if they modified this?" for a focused risk summary.

9. Suggest a Simpler Way to Achieve the Same Result

The Prompt

Look at this code and suggest a simpler implementation that achieves the same result. Prioritize: fewer lines, less state, built-in language/library features over custom code. Show the simplified version side by side with the original. Only suggest changes that are genuinely simpler — don't trade one kind of complexity for another. If the code is already optimal, say so.

[paste function or block here]

What it does
Runs a complexity-reduction pass. Catches over-engineered solutions, unnecessary abstractions, and hand-rolled versions of standard library functions. The "don't trade one complexity for another" constraint prevents Claude from suggesting clever one-liners that are harder to read.

Example output

// Original (31 lines)
function groupByStatus(orders: Order[]): Record<string, Order[]> {
  const result: Record<string, Order[]> = {}
  for (const order of orders) {
    if (!result[order.status]) {
      result[order.status] = []
    }
    result[order.status].push(order)
  }
  return result
}

// Simplified (1 line, same behavior)
const groupByStatus = (orders: Order[]) =>
  Object.groupBy(orders, o => o.status)
// Note: Object.groupBy is available in Node 22+ / TS 5.4+
// If targeting older environments, use:
const groupByStatus = (orders: Order[]) =>
  orders.reduce((acc, o) => ({
    ...acc,
    [o.status]: [...(acc[o.status] ?? []), o]
  }), {} as Record<string, Order[]>)

Why it works
The "only suggest genuinely simpler" constraint prevents the common failure mode of Claude suggesting complex abstractions in the name of simplification.

Pro tip — Add "flag any simplification that changes behavior in edge cases" to stay safe during the refactor.

10. Write the Review Comment I Should Leave on This Code

The Prompt

I need to leave a code review comment on this diff. The issue I want to flag is: [describe the issue in plain English]. Write the review comment I should post. It should be: specific (reference the exact lines), constructive (explain why, not just what), actionable (include a suggestion or example fix), and professional but direct. Avoid filler phrases like "Great work, but..." Write it as plain text I can paste directly into GitHub.

[paste the specific lines in question]
[describe the issue: e.g. "this function is doing too much, the DB query and business logic are mixed together"]

What it does
Eliminates the blank-page problem when you know something is wrong but can't phrase it constructively. Also useful for junior reviewers learning to write good review comments — the output is a template they can study.

Example output

Lines 45-67: This function is handling both the database query and the
discount calculation logic, which makes it hard to test either piece in isolation.

The SQL on line 48 reaches directly into order_items to compute the
total, then the loop on lines 52-61 applies business rules on top.
If the discount logic changes (which it will — marketing owns this),
you'll need to touch the same function that owns the raw DB query.

Suggestion: extract the discount logic into a pure function:

  // Pure, testable, no DB dependency
  function applyDiscounts(subtotal: number, coupons: Coupon[]): number {
    ...
  }

Then call it from the service after the DB fetch. The repository layer
stays ignorant of business rules, and you can unit test applyDiscounts
without mocking a database.

Why it works
Filling in the issue in plain English lets you offload the translation from "I know something's wrong" to "I can articulate exactly why" — Claude does the translation into review-ready language.

Pro tip — Add "make the tone [direct | gentle | questioning]" to match the culture of your team or the seniority of the author.

The Bigger Principle

These prompts work for one reason: they constrain Claude's output to what a reviewer actually needs. Not a summary of what the code does. Not a list of every possible improvement. A targeted analysis of the specific thing most likely to cause a problem — delivered in a format you can act on in the next five minutes.

That is the principle worth keeping. Generic prompts produce generic feedback. The more precisely you describe the review task — the language, the risk surface, the context of where this code runs — the more useful the output.

Start with one prompt. The one that covers the review task you dread most: the security check you always feel slightly uncertain about, the refactor suggestion you struggle to articulate diplomatically, the consistency audit you keep skipping because it takes too long. Build from there. A personal library of 10 well-tuned prompts beats a library of 100 you never open.

Bookmark this. Next time a PR sits in your queue, paste one of these before you write a single comment.

And if you want to go further — there is a Claude Prompts for Developers pack with 55 battle-tested prompts covering code review, debugging, architecture analysis, documentation, and productivity. The same kind of prompts. Built for daily use.