Playbooks · Coding tasks
Write release notes with Claude Code, and only claim what shipped
Written October 27, 2026 · Edited October 28, 2026
For a solo developer × release notes for a real release × Claude Code, ending with notes a user can read in under a minute: every entry traced to a merged change, sorted by change type, and nothing described as shipped until it is actually live for users.
Before you start
You need a project with a git history, a changelog file or a place for one, the previous release tag, and the new version number you plan to ship. The workflow below uses one custom slash command, /changelog, defined in a single file in the project. The agent drafts from the commit range and the diff; you decide what counts as notable, and you decide what has shipped. A merged commit is not a shipped feature: code merged behind a flag, code deployed to staging only, and code in a build nobody has installed yet are all not yet shipped, and the notes must say so or leave them out.
The format used here is the Keep a Changelog shape: one section per version, newest first, each with a date, and changes grouped under Added, Changed, Deprecated, Removed, Fixed, and Security. An Unreleased section at the top collects changes as they land, so the notes are written continuously instead of in a rush on release day.
What "done" looks like
At the end of one sitting you have a /changelog command file in the project, a reviewed draft of the release section with every entry traced to a merged change, a separate list of merged work that is not yet shipped, held back in the Unreleased section, and the notes published in the changelog and in the release itself. A user reading the notes learns what changed, what will break, and what was pulled — and nothing in the notes describes a feature the user cannot yet use.
Steps
- Make the command, with its inputs written down. Create
.claude/commands/changelog.mdwith a short description in the frontmatter and instructions that name exactly what the command may read: the git log between the previous tag and HEAD, the diff summary for that range, and the existing changelog file. Tell it the argument it receives is the version number, as$ARGUMENTS, and that it must not invent entries, dates, or version numbers of its own. A command file is a Markdown file whose name becomes the slash command; the frontmatter description is what shows in the command menu. Commit the file with the project so the next release uses the same command. - Keep an Unreleased section during the cycle, not just at release time. At the top of
CHANGELOG.md, keep anUnreleasedsection with the six change-type headings. As work merges, add one short line per notable change under the right heading, in plain words a user would understand. This is the habit that makes release day a review instead of a reconstruction: at release time, the command moves the Unreleased lines into a new version section instead of rediscovering them from the commit log. Lines added from memory, weeks later, are where invented entries come from. - Run the command with the version number, and only the commit range. Run
/changelog 1.4.0from the project root, on the branch that will be tagged. The command drafts the release section from the git range between the previous tag and HEAD, grouped under the six headings, newest version first, with the release date in year-month-day form. If the draft contains an entry with no commit behind it in that range, delete the entry: the draft is a summary of the range, not a summary of what the agent thinks the release contains. - Cut the noise before you check the wording. Remove every entry a user cannot act on: merge commits, typo-only commits, refactors with no visible change, and changes no user can see. Commit logs are full of noise, and a changelog pasted from a commit log teaches users to ignore the changelog. What survives is what changes the user's experience: a new capability, a changed behavior, a removed feature, a fixed bug, a security fix. If an entry needs a paragraph to explain why it matters, it probably does not matter to the reader — shorten it or cut it.
- Run the shipped check on every Added and Changed entry. For each entry, ask one question and demand evidence: is this change live for users right now? A feature behind a flag that is off, a feature deployed to staging only, and a feature in a build that has not been released are all not yet shipped, whatever the merge status says. Evidence is specific: the flag is on in production, the deploy that carries the change has completed, the package or build carrying it is the one users get. An entry that fails the check stays in the Unreleased section with a short note saying it is merged but not yet available, or it is dropped from the notes entirely. Never describe work that has not shipped in the past tense as if users already have it.
- Put deprecations, removals, and breaking changes where they cannot be missed. Check the draft for every deprecation and removal, and make sure each one names what is going away, what replaces it, and the version in which it goes away. A user upgrading from one version to the next should see, without hunting, what will break. If a release removes something that was deprecated in an earlier release, the notes say so in the Removed section, and the deprecation that warned about it stays in the earlier version's section. Hiding a removal at the bottom of a long Added list is how upgrades break silently.
- Read the draft as a user, then publish it in both places. Read the finished section once from the top, as someone deciding whether to upgrade: is every line short, specific, and true? Rename the Unreleased section to the new version with the release date, leaving a fresh empty Unreleased section above it. Then publish the same text as the release notes: create the tag, draft the release from it, and paste the section in, or create it from the command line with the notes from a file. The changelog file is the portable record; the release page is where most users will read it. The two texts should match, word for word.
- If a release is pulled, say so in the notes. A version withdrawn because of a serious bug or a security problem stays in the changelog, marked
[YANKED]after its date, with a short line saying why it was pulled. Do not delete the section and do not rewrite the history: a user who installed the pulled version needs to find, in the notes, that they should move off it. The yanked marker is loud on purpose, and it stays loud.
Check the agent's work
- Check that every entry in the draft traces to a commit inside the release range. An entry with no commit behind it is invented, however plausible it reads.
- Check that the six headings are used correctly: Added for new features, Changed for changes in existing functionality, Deprecated for soon-to-be-removed features, Removed for now-removed features, Fixed for bug fixes, Security for vulnerabilities.
- Check the shipped status of every Added and Changed entry against real evidence: flag state, completed deploy, or released build. Merged is not shipped.
- Check that every deprecation and removal names what goes away, what replaces it, and when. A removal with no replacement named is an incomplete entry.
- Check that the version heading carries the release date in year-month-day form, and that the changelog text and the release-page text match.
- Check that the command file is committed with the project, and that a second run of
/changelogwith the same version produces the same section, not a new one.
What can go wrong
- Pasting the commit log as the changelog. Merge commits, obscure titles, and documentation churn bury the changes users care about. The changelog is a curated list of notable changes, written for humans, not a dump of the log.
- Claiming flagged-off work as shipped. Notes that describe a feature users cannot reach yet produce support questions and lost trust. The shipped check exists for exactly this entry: no evidence of availability, no past-tense claim.
- Writing the notes from memory on release day. Memory invents entries and drops the awkward ones. The Unreleased section, kept during the cycle, is the record the draft is compared with.
- Burying a breaking change. A removal hidden among additions breaks upgrades quietly. Deprecations and removals go where a skimming reader will see them, with replacements named.
- Deleting a yanked release from the notes. The users who installed it lose the one place that would have told them to move. A yanked version stays listed, marked, with the reason given.
Limits
- This workflow drafts and checks notes; it does not decide what to ship, and it does not test the release. The version number, the tag, and the decision to publish stay with the developer.
- The six change types are a convention, not a law. A project that uses different headings should keep its own convention consistent rather than switching formats mid-history.
- Nothing here generates notes from work outside the commit range. A change made in another repository, a documentation-only change, or a change with no commit is outside the draft and must be added by hand, with its source stated, or left out.
Related playbooks
- Auggie 0.37.0: first release after the takeover
- Agree what to build before building it: write a short product requirements document with BMad
- Qwen Code 0.27.3: the November 13 build
- Qwen Code 0.27.4: the November 15 build
Sources
Sources: Keep a Changelog, GitHub Docs — Managing releases in a repository, Claude Code slash commands, Claude Code custom slash commands.
Back to: Coding playbooks hub · Also: Document a codebase so a stranger can work in it · Upgrade dependencies one package at a time, with a rollback for each