10 Claude Prompts for Developer Documentation That People Actually Read

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]

# 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]

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]

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, ...}
    """

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]

## 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

`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

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]

## [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.

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]

# 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.

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]

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).

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]

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.

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]

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

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]

# 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.

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.]

## 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.