Writing PR Descriptions with Claude Code
Claude can write PR descriptions that actually explain what changed and why — not just what files were modified.
PR descriptions are one of those tasks that everyone acknowledges matters and almost no one does well under time pressure. Claude Code makes it fast to write good ones.
The prompt that works
At the end of a session, before opening the PR, I ask Claude:
"Write a PR description covering: what problem this solves, what approach was taken and why, what was considered but not done, and what a reviewer should focus on. Under 300 words."
Claude has full session context — it knows what was built, what decisions were made, what was rejected. The description it produces is significantly better than "implemented user auth" written when you just want to close the laptop.
What makes a PR description actually useful
The best ones answer the questions that would otherwise end up as review comments:
- Why this approach instead of the obvious alternative?
- What edge cases were handled, and which were deferred?
- Is there anything risky the reviewer should specifically test?
- What's the impact on existing behavior?
Claude addresses all of these if you ask. It won't include them by default because it doesn't know which questions your team typically asks.
Add a testing notes section
For PRs with non-obvious testing paths, I ask Claude to add a "how to test this" section. What to click, what to check, what state the system needs to be in. Reviewers who can actually run through the change are better reviewers.
What to fix in Claude's draft
Claude's PR descriptions are accurate but sometimes read like documentation rather than communication to a colleague. Light edit: make it more direct, cut anything that explains what the code does (the code shows that), keep anything that explains why.
The "why" is what PR descriptions are actually for.