Claude Code makes documentation fast. The risk: "faster" can mean "more words, same amount of useful information." Here's how to get docs people actually use.
The docstring prompt that works
❌ "Add docstrings to all functions."
✅:
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 code into prose instead of explaining intent.
README structure
Write a README for this project.
1. What it does (one sentence — what it does for the user, not what it is)
2. Who it's for
3. Quick start (minimum steps to get something working)
4. Configuration reference
5. Common patterns (3-5 real use case examples)
6. Known limitations
Don't include: marketing language, or anything that says "powerful" or "robust".
Architecture Decision Records in 30 seconds
Write an ADR for the decision we just made.
- Title: [decision in 5 words]
- 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.
These take 30 seconds to generate and are invaluable 6 months later when someone asks "why is it designed this way?"
Runbooks that people follow
Write a runbook for [operation]. Audience: engineer who knows the
codebase but has never done this operation before.
- 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
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?)
Documentation debt is real debt.
Documentation prompts — docstrings, READMEs, ADRs, runbooks — are all in the Agent Prompt Playbook. $29.
Top comments (0)