Why I think we should write our own PR descriptions

I think we, as developers, should write our own pull request descriptions, even when an agent has done most of the implementation.

Not because Claude or Codex can’t write them. They can, and they’ll normally produce something far more comprehensive than I would.

I think we should write them ourselves for two reasons:

1. Writing the description forces us to understand and explain the change we’re putting up for review.

2. The person reviewing the PR needs context from us, not a summary of the diff from the agent that wrote it.

#Writing is a checkpoint

Many developers are handing the actual implementation of our work over to agents, which is not necessarily a bad thing. They’re good at it. Really good in most cases.

But as we hand over more of the writing of the code, I think it’s important that teams find ways to stay in touch with that code and the changes being made.

Pull request descriptions are one of those ways.

If an agent has written the code, the tests, the commit message, and the PR description, where exactly are we forcing ourselves to understand and explain the change?

Hopefully, we’re all reviewing the code our agents produce, and I’m certainly not suggesting that using an agent-generated description means you don’t understand your changes.

But writing the description yourself creates a kind of natural checkpoint.

1. “What actually changed here?”

2. “Why did it change?”

3. “Are there any consequences that aren’t obvious from the diff?”

4. “What does the person reviewing need to know?”

If you can’t answer those questions without asking the agent to explain its own work back to you, that’s probably a sign that you need to spend a little more time with the change.

#Claude confidence

There’s also something that I’m now calling “Claude confidence.”

Claude is incredibly confident. It'll make a change, run some tests, and then tell you that everything is correct, robust, backward compatible, and ready to ship.

And to be fair, quite often it’s right. But “Claude is confident” and “I understand this change” are two different things.

It’s easy to inherit the agent’s confidence, particularly when it wrote both the implementation and the explanation of why that implementation is correct.

As these tools improve, I think we need to be conscious of that. It’s easy to become good at describing a problem, sending an agent on its way, and then evaluating the result at a fairly high level.

#PR descriptions are for humans

There’s a more practical reason here too. The descriptions that Claude generates are comprehensive, telling you what changed, why it changed, which files changed, how it was tested, and what’s… load-bearing, for some reason.

A pull request description is not there to contain every detail about a change. That’s what the diff is for.

A pull request description is there for another human to read. It should give them enough context to understand:

• why this PR exists

• what it's changing

• how it fits into the wider piece of work

• anything weird, risky, or non-obvious

• anything you'd particularly like their thoughts on

It should be brief, but useful.

#What this looks like in practice

Here’s a slightly exaggerated version of the kind of PR description you often get when an agent opens a PR:

#Summary

This PR improves the workspace deletion flow by adding validation to prevent users from deleting a workspace while it has active deployments.

#Changes

• Added hasActiveDeployments check to deleteWorkspace

• Added a new WorkspaceHasActiveDeploymentsError

• Updated the workspace deletion API handler to return a 409 response

• Added unit tests covering workspaces with and without active deployments

• Updated the API response types

• Added error handling to the workspace settings UI

• Added a user-facing error message when deletion is blocked

#Implementation details

The deleteWorkspace function now queries the deployments repository before performing the existing deletion logic. If one or more active deployments are returned, the function throws a WorkspaceHasActiveDeploymentsError. The API layer catches this error and maps it to a 409 response...

#Testing

• Added unit test for deletion with no active deployments

• Added unit test for deletion with an active deployment

• Added unit test for deletion with multiple active deployments

• Verified existing workspace deletion tests continue to pass

• Ran pnpm test workspace

• Ran pnpm typecheck

#Backward compatibility

This change is fully backward compatible. Existing workspace deletion behavior remains unchanged for workspaces without active deployments.

There’s nothing particularly wrong with this description; it’s actually impressively thorough.

But most of it isn’t helping me review the change.

The implementation details are things I’m about to discover by reviewing the PR and reading the diff. The testing section mostly tells me that the tests that were written ran fine without issues. And I’m probably not going to take the claim that it’s “fully backward compatible” on trust alone; that’s going to be one of the things I’m reviewing.

What I’d much rather read from the person who owns and orchestrated the change is something like:

Prevents user from deleting a workspace while it still has active deployments.

We’re doing this because deleting the workspace currently leaves those deployments in a broken state. I considered cleaning them up automatically, but I think explicitly making the user remove them first is safer for now.

Worth looking at: I’m not completely convinced 409 is the right response here, so I’d particularly appreciate thoughts on that.

It’s shorter, but it gives more of what I actually need as a reviewer:

• why the change exists, not what changed

• context I might not get from reading the diff

• the decisions and trade-offs made along the way

• uncertainty, instead of every decision presented as obviously correct

• direction for the review, and where my attention would actually be useful

Tell me the what, why, and where. Not the how.

#Context matters more when we’re doing more things

As agents let us work on more things at once, I’ve personally found it harder to keep track of what’s happening.

Most of us at Laravel are working on the same big thing, Laravel Cloud, but within that big thing are an untold number of little things that all seem to happen simultaneously.

Who is working on what? Why does this pull request exist? How does it fit into the bigger piece of work? Where is the project actually going?

When I open a pull request from a teammate, I don’t want to read 1,500 words generated by a robot. I want the owner of that change, the human orchestrator behind the agent, to speak to me instead.

Then I’ll read the code.

#Closing words from yours truly

Let the agents write code. Let them help us explore problems, write tests, refactor things, and move faster.

But when it comes time to explain a change to another human, I think that part should come from a human.

Not because Claude and Codex can’t do it, but because if you own the change, you should own the explanation.