Automate PR Descriptions Claude Code: The Engineer Workflow
You finished the work an hour ago. The branch is clean, the tests are green, and now you’re staring at an empty pull request description box trying to remember why you renamed that function in the third commit. This is the gap the automate PR descriptions Claude Code workflow is built to close: it reads your diff and your commit history, then writes the summary you’d write if you weren’t already mentally on the next ticket. The description stops being the tax you pay at the end of a task and becomes a byproduct of the work you already did.
PR descriptions are a strange piece of engineering work. Everyone agrees they matter for review speed and for the archaeologist who reads them eighteen months later. Almost nobody writes them well under deadline. The result is a wall of “fixes stuff” and “address feedback” entries that make git blame a dead end. The good news is that the raw material for a great description already exists in your repository, and Claude Code is good at turning structured input into structured prose.
Why the Empty Description Box Wins Every Time
The reason PR descriptions are bad isn’t laziness. It’s ordering. By the time you open the PR, the context that would make the description good has already drained out of your head. You’re thinking about merge conflicts and the next task, not about explaining a decision you made ninety minutes ago.
The fix isn’t discipline. It’s moving the work to a tool that still has the full context sitting right in front of it. Your git diff holds every line that changed. Your commit messages hold the rough narrative. Claude Code can read both at once and reconstruct the story far faster than you can retype it.
Think about a backend engineer who just split a 400-line service into three modules. The diff is sprawling, but the intent is simple: reduce blast radius before a risky deploy. A human writes “refactor service” and moves on. Claude Code, handed the diff and a one-line prompt about intent, writes the three sentences a reviewer actually needs to approve quickly.
The Minimum Viable Workflow
Start with the simplest possible version before you automate anything. Open Claude Code in your repository, stage your branch, and ask it to read the diff against your base branch and draft a description.
The core command is a single git invocation that gives Claude the full picture of what changed. Run this inside a Claude Code session:
git diff main...HEAD
Then give Claude a prompt that sets the job clearly. The prompt matters more than the diff, because it decides whether you get a line-by-line readout or a reviewer-focused summary:
Read the diff above. Write a PR description with three sections:
Summary (why this change exists, 2 sentences), What Changed
(the substantive edits a reviewer should check, as bullets), and
Review Notes (anything you deliberately left out of scope, plus
the riskiest part of the change). Skip trivial formatting edits.
That last instruction does the heavy lifting. “Skip trivial formatting edits” is the difference between a description that says “updated imports in fourteen files” and one that says “the import churn is from the module split; the real change is the new retry logic in client.ts.” You’re teaching Claude to triage the diff the way a senior reviewer would.
Run it, read the output, and edit anything that’s wrong. The first few times, you’re calibrating. You’ll find the prompt needs one more constraint, or your team uses a section your template doesn’t have. Adjust and save the working prompt somewhere you’ll reuse it.
Make Claude Write in Your Team’s Voice
A generic PR description is better than an empty one, but the real value shows up when the output matches how your team already works. That’s a configuration problem, and it’s the same substrate covered in the Claude Code for engineering teams hub: your CLAUDE.md file.
Put your PR conventions in CLAUDE.md and Claude reads them at the start of every session. If your team requires a “Testing” section, a ticket reference, or a rollback plan for anything touching the database, write that down once. The description Claude drafts will then carry those sections automatically, because it’s working from your standards instead of a default template.
Here’s a CLAUDE.md fragment that shapes every description Claude writes in that repo:
## Pull Request Descriptions
Every PR description must include:
- A "Summary" explaining intent, not mechanics
- A "Testing" section stating what you ran and what you did not
- A linked ticket in the form PROJ-1234
- A "Rollback" line for any change touching migrations or config
Write for a reviewer who has not seen the ticket. Lead with the
riskiest change. Never describe formatting-only edits.
This is the same instinct that makes the rest of your Claude Code setup work. Conventions live in one file, every session inherits them, and the output stops looking like a generic model and starts looking like a member of your team. Anthropic’s Claude Code memory documentation explains how that persistent context gets loaded.
Wire It to the GitHub CLI
Once the draft quality is reliable, take yourself out of the copy-paste loop. The GitHub CLI lets you open a pull request from the terminal, which means Claude Code can do the whole thing in one move: read the diff, write the description, and open the PR.
A simple version chains the steps together. Claude generates the body, writes it to a temporary file, and hands it to gh:
gh pr create --title "Add retry logic to API client" \
--body-file /tmp/pr-body.md --base main
You can let Claude Code run this directly. Ask it to draft the description, save it, and open the PR, all in the same session. For the headless version that fits in a script, Claude Code’s command-line mode can take a prompt and emit just the description text, which you pipe straight into gh. The Claude Code CLI reference covers the flags for running it non-interactively.
The payoff is that the description is generated at the exact moment you have the most context: the second the branch is done. No tab-switching to the GitHub web UI, no blank box, no “I’ll write it properly later.” Later never comes, and Claude doesn’t need it to.
Where to Draw the Line
Automating the description is not the same as automating the judgment. Claude writes a strong first draft, but you own what ships. It can misread intent when the diff and the commits disagree, and it cannot know the thing you decided in a hallway conversation that never made it into code.
Read every generated description before you open the PR. The check takes ten seconds and catches the cases where Claude confidently summarized the wrong thing. The point of the workflow is to move the writing off your plate, not to move the responsibility.
This is the same boundary that governs the rest of an engineering team’s Claude Code setup. The tactical version of where automation helps and where it doesn’t shows up across the workflow: in code review automation, where Claude handles the first pass and humans handle design; in documentation automation, where generated docs still need a human owner; and in bug triage automation, where the model proposes and the engineer disposes. Description writing is one more place where Claude carries the assembly and you keep the call.
Roll It Out Without a Mandate
The fastest way to spread this is not a policy. It’s a teammate seeing a clean PR description and asking how you wrote it so fast. Ship the workflow for yourself first, get it reliable, then share the prompt and the CLAUDE.md fragment in your team channel.
If you’re onboarding new engineers, fold it into their setup from day one so they never form the bad habit. The same approach in engineering team onboarding applies directly: a new hire who writes good PR descriptions from their first merge raises the floor for everyone reviewing their code. Standards that arrive on day one stick better than standards retrofitted later.
Frequently Asked Questions
Does Claude Code need access to my GitHub account to write PR descriptions?
Not directly. Claude Code reads your local git diff and commit history, then drafts the description text. You paste that into the PR yourself, or you wire it to the GitHub CLI so Claude runs the command that opens the PR. Either way, the description is generated from your local repository state, not from a hosted integration you have to grant.
Will the generated description just restate the diff line by line?
Only if your prompt asks for that. A good PR-description workflow tells Claude to explain why the change exists, what reviewers should focus on, and what was deliberately left out. The diff is the input; the description is an interpretation of it. When you give Claude your CLAUDE.md conventions and a template, it writes for the reviewer, not for the parser.
Can I make this run automatically every time I open a pull request?
Yes. The cleanest setup is a slash command or a small script that runs the git diff, passes it to Claude Code in headless mode, and pipes the output into gh pr create. Some teams wrap it in a git alias so the whole thing is one command. Start manual, confirm the quality, then automate the trigger once you trust the output.
Is it safe to send proprietary code through Claude Code for this?
Follow your company’s data handling policy and whatever your security team has approved for Claude Code. The diff you send is the same code Claude Code already reads during normal sessions, so if the tool is approved for development, generating PR descriptions sits inside that same boundary. When in doubt, confirm scope with your platform team before automating.
Pick your next pull request and run the minimum viable version once: open Claude Code, hand it git diff main...HEAD, and use the three-section prompt above. If the draft is good, save the prompt and you’ve built the habit. To go from one-off prompts to a configured team workflow with CLAUDE.md templates and the headless gh integration, the Claude Code course walks through the full setup.
