Claude Code prompt templates for READMEs, changelogs, API reference, runbooks, and PR descriptions — without the marketing-speak that makes AI-written docs obvious.
AI-written documentation has a tell: marketing words ("powerful", "robust"), aspirational tense ("this project aims to"), and an aversion to working code in the first 30 lines. The prompts below ban those patterns explicitly and produce docs that read like a human engineer wrote them.
Write a README for [PROJECT].
Constraints:
- First sentence hooks a developer in 5 seconds. Forbidden openings:
"This project is a...", "[NAME] is a powerful...", "Welcome to..."
- Working code example in the first 30 lines (after the title)
- Banned words: powerful, robust, best-in-class, seamless, elegant,
comprehensive, cutting-edge, blazing-fast, simple yet powerful
- A "Non-goals" section with at least 3 bullets
- Max 250 lines total
- Use the actual installation command for THIS project (read package.json
or pyproject.toml first — don't say "npm install" if it's pnpm)
Read these files to understand the project:
- src/index.* (or main entry)
- package.json / pyproject.toml / Cargo.toml
- existing README.md if any (to extract correct claims, not tone)Read commits between [TAG_A] and [TAG_B]: git log --oneline [TAG_A]..[TAG_B]
Generate a CHANGELOG entry in Keep-a-Changelog format:
### Added
### Changed
### Fixed
### Removed
### Security
Rules:
- One line per entry, past tense ("added X", "fixed Y", not "adds X")
- No commit hashes in the user-facing lines
- Skip purely internal commits (refactors, lint fixes, dependency bumps
that don't change behaviour). Group those in a single line:
"### Internal — N commits for internal cleanup, deps, tooling"
- If a commit message is vague, infer the user-visible change from the diff
- Group related fixes into one line when they're the same surface area
End with the version header: ## [vX.Y.Z] — YYYY-MM-DDGenerate API reference docs for [FILE].
Read the actual function signatures, types, and docstrings.
Format per function/endpoint:
### functionName
Brief description (1 sentence).
**Signature:** `functionName(arg1: type, arg2?: type) => ReturnType`
**Parameters:**
- `arg1` (type) — what it represents, constraints
- `arg2` (type, optional) — default value, when to set
**Returns:** what the return value represents
**Throws / Errors:** specific error classes and when
**Example:**
```code
[3–8 line working example]
```
**See also:** [other related functions, by name]
Skip internal helpers (functions prefixed with _ or marked @internal).I want a runbook for: [INCIDENT TYPE — e.g. "database CPU spike", "queue
backlog growing", "5xx rate exceeds 1%"].
Structure:
## Symptoms
- What an on-call engineer sees first (specific metrics, alert names,
log patterns)
## Severity
- What makes this a P1 vs P2 vs P3 (specific thresholds)
## Immediate triage (under 5 minutes)
- Check 1: [specific command or dashboard URL]
- Check 2: ...
- Goal: confirm the problem is real and bound the blast radius
## Mitigation (buys time)
- Option A: [specific commands to run, with expected outcome]
- Option B: [if A fails]
## Root cause investigation
- Where to look in logs
- Which dashboards
- Common causes (from incident history if I describe past incidents)
## Postmortem checklist
- Artifacts to capture before alerts clear
- Communication template
No platitudes. Plain English. Bash commands and dashboard URLs where
applicable — write [DASHBOARD_URL] or [SLACK_CHANNEL] where I should
fill specifics.Read the current diff: git diff main...HEAD
Generate a PR description with sections:
## Why
1–2 sentences on the motivation. Specific — link to issue if mentioned
in commits, name the user-visible impact.
## What
3–6 bullets on the user-visible changes. NOT the implementation steps.
## How
2–4 sentences on the implementation approach. Include any non-obvious
design decisions (why X over Y).
## Risk
1–2 sentences on what could break and where to look first if it does.
## Test plan
- [ ] checklist of what's been verified
- [ ] what reviewers should verify themselves
Banned: "this PR aims to", "this enables", "to better support", marketing
words. Write like a senior engineer with a deadline.Write an ADR for the decision: [SHORT TITLE].
Format:
# ADR-[NUM]: [Title]
## Status
[Proposed | Accepted | Superseded by ADR-X | Deprecated]
## Context
The forces at play. What problem is this solving? Specific to this
codebase, not generic. Reference files or systems by name.
## Decision
What we decided. One paragraph. Active voice.
## Alternatives considered
For each rejected option: what it was, why it was rejected. Be honest about
the trade-offs.
## Consequences
- Positive: what gets easier
- Negative: what gets harder, what we accept as the cost
- Neutral: notable but not better or worse
## Out of scope / non-decisions
Things this ADR explicitly does NOT decide, to prevent future scope creep
in "this was decided in ADR-N" discussions.
Length: aim for 200–500 words. ADRs are reference documents, not essays.Write a tutorial for [TASK] using [PROJECT].
Hard rules:
- Every code block must be runnable as-is. No "// fill this in".
- Test each code block by reading the actual project source — do not
hallucinate function names.
- Each step has an expected output. State what success looks like.
- If a step might fail for common reasons, name them (e.g. "if you see
ECONNREFUSED, your DB isn't running — start it with docker compose up").
Structure:
1. Prerequisites (specific versions, env vars needed)
2. Setup (5 lines max)
3. Steps 1–N (each: action, expected output, what went wrong if it didn't)
4. What you have now (concrete deliverable)
5. Where to go next (links to deeper docs)
No "congratulations", no "you're now a master of X".For [FILE], add docstrings to every public function (not prefixed with _).
Format (Python — Google style):
"""One-line summary in imperative ("Compute X", not "This computes X").
Longer explanation only if non-obvious — skip it for trivial functions.
Args:
name (type): what it is, constraints
Returns:
what the return value represents
Raises:
ErrorClass: when this is raised
"""
Rules:
- Read the function body first. Document what the code ACTUALLY does, not
what the name suggests it does. Flag mismatches.
- Examples only when the call site isn't obvious from the signature.
- Skip docstrings on functions where the name fully conveys behaviour
(e.g. `get_user_id`, `is_valid`).| Word | Why | Use instead |
|---|---|---|
| powerful | Empty intensifier | State the specific capability |
| robust | Vague | "Handles X and Y failure modes" |
| seamless | Marketing | "Single-command install" |
| elegant | Self-flattery | Just show the code |
| cutting-edge | Dates immediately | State the version/release |
| blazing-fast | Show, don't tell | Benchmark numbers with hardware |
| simple yet powerful | Empty | One concrete example |
| just / simply | Lies about effort | Show the steps |
Add a ## Documentation prompts section to your project's CLAUDE.md with prompts 1, 2, and 5 — they're the ones you'll reach for weekly (README updates, changelog generation, PR descriptions). Now in any session: "use the PR Description prompt on the current diff" — Claude pulls from CLAUDE.md, no copy-paste.
This page has 8 documentation prompts. The full Claude Code Power Prompts pack has 30 across six categories — review, debugging, testing, architecture, docs, devops. £3 launch tonight (first 10 buyers), £5 standard. 8-page PDF, instant Stripe download.