Writing a good pull request description is more important than ever
What differentiates a good engineer from a great one? One of the most impactful improvements you can make in your career is learning how to write well. This is an invaluable trait that will help you with everything from writing design docs and getting buy-in from your team, to composing better prompts and why not charming pull requests. This is especially important in the AI age; it can be a game changer.
Some years ago, I came across this blog post by Gergely Orosz: On Writing Well. It was an eye-opening revelation that we can put into practice in our day-to-day work. Check it out.
As you probably already know, AI is everywhere, especially in the software development lifecycle. Your work doesn’t end after "vibe coding" a 200k LOC solution to a bug; you need to get this change merged, and for that, you need to be able to convince people. This is where we go back to the basics. It is even more important when there are already AI agents reviewing these diffs; as usual with AI, context is king.
How to write a pull request
First things first: we judge a book by its cover. Your PR title is the most important part, try to make it as catchy and factual as possible. It should describe the intent, not necessarily the "how."
Don't forget the Semantic Conventions. A great PR starts with a searchable title. Adopting Conventional Commits (e.g., feat:, fix:, refactor:) isn't just for automation or generating changelogs; it gives the reviewer, human or AI, an immediate mental map of the scope of your changes. It’s the "Subject Line" that determines the priority of the review.
GitHub is arguably one of the masters of writing pull requests. Ten years ago, they wrote an excerpt that still stands: How to write the perfect pull request. In short, your PR description should answer the following questions:
- Why: Why this change is needed.
- What: What problem it solves.
- How: Explain clearly what the code does. This is probably one of the most important parts these days. If you don’t understand the code your favorite LLM agent has produced, you won’t get this code merged.
- How it has been tested: Was it by hand, a unit test, or an integration test?
- Extra context: Once this is provided, it is up to the reviewer (or LLM) to skim over your detailed implementation.
Take a look at this PR from the Tempo repository:
Hey! I wrote just too many code, can I use an AI as a Technical Writer?
Sure!, why not?
If you are a seasoned "vibe coder," you can just tell your favorite tool to do it for you! Tools like Cursor allow you to do that simply by using @Git (Diff of Working Copy) and asking for a description directly.
However, I propose a different workflow—one that is more ubiquitous and works with any tool:
1. Generate Real Context
Once you’ve finished your changes and tests, extract the exact diff of your work into a patch file. This prevents the AI from hallucinating based on files you might have open that aren't part of the actual submission:
git diff origin/main..HEAD > changes.patch2. The Master Prompt
Take that file to your trusted LLM (Cursor, Claude, ChatGPT) and use this prompt to get a professional description:
As always, review the output. Correct what is not accurate and try to give it your own tone. Don’t be a stochastic parrot.Conclusion
In a world where LLMs perform the code reviews, your PR description is now the master prompt guiding that review. A mediocre description will result in a mediocre review.
If you want technology to work for you, and not the other way around, mastering context communication is your new superpower. A machine can generate the code, but only you can provide the direction.