Claude Code makes documentation dramatically faster. The risk: "faster" can mean "more words, same amount of useful information." Here's how to get documentation people actually use.
The docstring prompt
Bad prompt: "Add docstrings to all functions."
Good prompt:
Write docstrings for these functions. For each one:
- One sentence: what it does (start with a verb)
- Parameters: name, type, what it represents (not just the type)
- Return value: what it is, not just the type
- One example showing a non-obvious use case
- Any gotchas: what breaks if you call it wrong
Don't restate the function name. Don't describe the implementation.The "don't describe the implementation" constraint is the key one. Most auto-generated docstrings translate the code into prose instead of explaining intent. They tell you what happens, not what it's for.
README structure
Write a README for this project. Structure:
1. What it does (one sentence, not what it is — what it does for the user)
2. Who it's for (one sentence)
3. Quick start (minimum steps to get something working)
4. Configuration reference (machine-readable, not prose)
5. Common patterns (3-5 examples of real use cases)
6. Known limitations
Don't include: installation requirements already in package.json,
marketing language, or anything that says "powerful" or "robust".API documentation
Document this API endpoint. Include:
- Method and path
- Authentication requirements
- Request parameters: name, type, required/optional, constraints
- Request body schema with examples
- Response schema with examples for success and each error case
- Rate limiting information if applicable
Format as markdown that could go in a docs site.The error case examples are the part people skip. They're also the part most valuable to API consumers. Force Claude to include them explicitly.
Decision records
After any significant architecture decision:
Write an Architecture Decision Record for the decision we just made.
Format:
- Title: [decision in 5 words]
- Status: Accepted
- Context: what problem we were solving
- Decision: what we chose and why
- Alternatives: what we didn't choose and why not
- Consequences: what this makes easier, what it makes harder
Keep it to one page. No jargon.These take 30 seconds to generate and are invaluable six months later when someone asks "why is the system designed this way?"
Runbooks
Write a runbook for [operation]. Audience: an engineer who knows the
codebase but has never done this operation before.
Include:
- When to run this
- Prerequisites and required access
- Step-by-step instructions (numbered, not prose)
- How to verify it worked
- How to roll back if something goes wrong
- Common errors and fixes
Assume nothing. If a step requires a command, write the exact command.The documentation audit
For existing documentation:
Review this documentation as someone who has never seen this codebase.
For each section:
1. Is it accurate? (flag anything that might be outdated)
2. Is it complete? (what questions would a reader still have?)
3. Is it necessary? (what could be cut without losing anything useful?)
Be direct. Documentation debt is real debt.Documentation prompts — docstrings, READMEs, ADRs, runbooks — are all in the Agent Prompt Playbook. $29.