半年前に自分が書いた認証ミドルウェアの仕様変更コードを開いたとき、「なぜここで httpOnly: true から httpOnly: false に戻したのか」がどうしても思い出せませんでした。コミットメッセージは fix: cookie issue の一行だけ。git blame をしても、自分が当時書いた PR の説明が見当たらず、結局 30 分かけて Slack の自分宛て DM を漁って、ようやく「ある特定のブラウザ拡張機能との衝突を回避するため」という理由を発掘したのです。
このような体験を何度も繰り返すうちに、個人開発でも CHANGELOG.md を書くべきだと実感するようになりました。とはいえ、毎回ゼロから書くのは続きません。私が今使っているのは、Antigravity に git ログを読ませて CHANGELOG のドラフトを作らせる「半自動」のフローです。完全自動ではないところが意外と続くコツでもあります。今日はその仕組みを共有します。
なぜ個人開発でも CHANGELOG.md が要るのか
「個人開発なんだから、自分が分かれば良い」とよく言われます。実際、私もそう思っていた時期がありました。けれど、自分が将来の自分を「他人」として扱うようになると、話が変わってきます。
3 ヶ月前のリファクタリング、半年前の SDK アップグレード、1 年前のデータベース設計変更 — こうした「過去の決断」が積み重なるほど、現在のコードを読み解く労力が増えていきます。CHANGELOG.md は、その労力を最小化するためのインデックスのようなものです。
それでも続かない最大の理由は、「書くタイミングが分からない」ことだと思います。リリースを切るたびに書こうとすると、リリースを切るまでの 1 週間分のコミットを見直すことになり、面倒で先延ばしになります。私は「土曜の朝、Antigravity を開いて 10 分だけ」と決めることで、ようやく続くようになりました。
緩めの Conventional Commits を素材として使う
Antigravity に CHANGELOG を書かせる前提として、コミットメッセージの形式をある程度揃えておく必要があります。ただし、フル装備の Conventional Commits（feat(scope): description のような厳格な形式）は個人開発には重すぎるというのが、私の今のところの結論です。
私が運用している「緩い Conventional Commits」のルールはこれだけです。
feat:新機能の追加fix:バグ修正refactor:動作を変えないコード整理chore:依存関係更新・ビルド設定変更など- それ以外のプレフィックスは禁止しない（自由に書いてよい）
このくらい緩いと、深夜に焦って書いたコミットでもルールから外れにくくなります。Antigravity 側で後から正規化すればよいので、人間側の負担を最小化することを優先しています。
git のコミットフックでメッセージを強制したい場合は、Husky と lint-staged で個人開発のコミット品質を底上げするで紹介している commit-msg フックを応用できます。ただし、私は強制までは行っていません。書く意欲を削がないことの方が長期的には大事だと感じているからです。
Antigravity に渡すプロンプトの設計
ここからが本題です。Antigravity に「git log を CHANGELOG にしてください」と雑に頼むと、どうしても抽象的なまとめになりがちです。具体性を引き出すには、入力データの形式と出力の構造を明示することが効きます。
私が使っているプロンプトはこんな構成です。本文の後に実際のシェルスクリプトも示します。
あなたは個人開発者の CHANGELOG エディタです。
以下の git log のうち、ユーザー視点で意味のある変更（feat / fix / 重要な refactor）だけを抽出して
CHANGELOG.md の Unreleased セクションに追記する Markdown を生成してください。
ルール:
- 内部実装の整理（chore, 内部 refactor）は省略してよい
- 同一機能に対する複数コミットは 1 行にまとめる
- 各エントリは「ユーザーが体感できる変化」で書く（コミットメッセージそのままを使わない）
- 推測でユーザー影響を盛らない。git log に書かれていない情報は補完しない
出力フォーマット:
### Added
- ...
### Fixed
- ...
### Changed
- ...
ポイントは「推測でユーザー影響を盛らない」と明示することです。これがないと、Antigravity は親切心で「パフォーマンスが向上しました」のような、確証のない文言を加えてくることがあります。
実装: 10 分で動くシェルスクリプト
次のスクリプトを scripts/draft-changelog.sh として保存し、bash scripts/draft-changelog.sh で実行します。直近 2 週間のコミットログを抽出して、Antigravity に貼り付けやすい形に整形してくれます。
#!/usr/bin/env bash
# scripts/draft-changelog.sh
# 直近2週間の git log を CHANGELOG ドラフト用に整形して標準出力に書き出す。
# 期待する出力: コミットハッシュ・タイトル・本文1行目を Markdown コードブロック形式で。
set -euo pipefail
SINCE="${1:-2 weeks ago}" # 第1引数で期間を変更可能（例: "1 month ago"）
OUTPUT_FILE=".changelog-draft-input.md"
echo "## git log since: ${SINCE}" > "$OUTPUT_FILE"
echo '' >> "$OUTPUT_FILE"
echo '```' >> "$OUTPUT_FILE"
# --no-merges で merge コミットを除外、--pretty で見やすく整形
git log --no-merges --since="$SINCE" \
--pretty=format:'%h %s%n%b%n---' >> "$OUTPUT_FILE"
echo '```' >> "$OUTPUT_FILE"
echo "✓ Wrote: $OUTPUT_FILE"
echo " → Antigravity を開き、このファイルの内容と CHANGELOG プロンプトを Side Panel に貼って実行してください"実行例の出力（一部抜粋）:
## git log since: 2 weeks ago
```
a3b8f12 feat: add Stripe webhook handler for subscription events
署名検証を Cloudflare Workers の SubtleCrypto で実装。
---
e2c0a91 fix: prevent double-charge when user retries Stripe Checkout
idempotency key を session id 由来にした。
---
（後略）
```
✓ Wrote: .changelog-draft-input.md
→ Antigravity を開き、このファイルの内容と CHANGELOG プロンプトを Side Panel に貼って実行してください
このファイルを Antigravity の Side Panel に貼り、先ほどのプロンプトと一緒に実行すると、CHANGELOG.md に追記する Markdown のドラフトが返ってきます。私はそれを目で確認して、不要な行を削り、表現が違和感のあるところだけ書き直して、CHANGELOG.md の ## [Unreleased] セクションに追記しています。
慣れると 10 分以内に終わります。何より、git log を眺めながら「あ、そういえばこの変更、ユーザーに告知してなかったな」と気付けるのが副産物として大きいです。
CHANGELOG にあえて書かないもの
何を書かないかを決めることは、何を書くかと同じくらい大事です。個人開発者が「全部書こう」とすると、たいてい燃え尽きるか、ノイズが多すぎて自分でも読み返さなくなります。
私が迷わず省略しているものはこんな内容です。
- 挙動が変わらない依存パッケージ更新: パッチバージョンのバンプは
package-lock.jsonの仕事であり、CHANGELOG.md の仕事ではありません。ただし、セキュリティアドバイザリ対応や Breaking Change を含む更新は別扱いで明記します。 - ユーザーに見えない内部 refactor: プライベート関数の名前を変えても、ユーザーには関係ありません。CHANGELOG はユーザー向け文書であり、コードの綺麗さの記録は git のコミット履歴で十分です。
- 同じ週にロールバックした実験: 入れて、気に入らなくて、リリース前に消した機能まで律儀に書き残す必要はありません。これは
git reflogの領域です。 - CI とビルド設定: GitHub Actions の構成変更は自分には興味深くても、ユーザーには関係ありません。記録したければ別ファイル（例えば
INTERNAL_NOTES.md）に分けることをお勧めします。
逆に、どんなに小さくても必ず書くものはこちらです。
- デフォルト動作を変えた変更: 設定 1 行の変更でも、ユーザーが気付けば問い合わせの種になります。書いておけば、未来の自分の回答コストが下がります。
- 料金・課金・認証に関わる変更: これらは「予告なく変わった」と感じられると一気に信頼を失う領域です。今のユーザーが「自分一人」だとしても、必ず記録します。
- データ形状の変更: 保存しているレコードに項目を追加・削除・リネームした場合、後から書く可能性のあるマイグレーションのために、必ずブレッドクラムを残します。
この「書く / 書かない」の判断軸は、Antigravity に渡すプロンプトの「ユーザー視点で意味のある変更だけ」という指示と完全に同じです。だからこそプロンプト側の精度が、そのまま CHANGELOG の質になります。
続けるための 3 つのコツ
このフローを 3 ヶ月運用してきて、続かなくなる原因がだんだん見えてきました。先回りして対策しておくと、習慣化しやすくなります。
1 つ目: 完璧を目指さない
最初の頃、私は「全コミットを CHANGELOG に反映しなきゃ」と気負っていました。けれど、内部のリファクタリングや CI の調整は、ユーザーには関係ない情報です。Antigravity が省略してきたものは基本的にそのまま省略でよいと割り切ると、続きやすくなります。
2 つ目: 「金曜の最後」より「土曜の朝」
書くタイミングを「金曜の仕事終わり」にすると、疲労感から先延ばしになります。土曜の朝、コーヒーを淹れて、新鮮な気持ちで読み返す方が、ユーザー視点での書き直しも丁寧になります。これは個人差があるので、自分の集中しやすい時間帯を探してみてください。
3 つ目: 月末に「Unreleased → vX.Y.Z」の昇格を儀式化する
毎週 [Unreleased] を更新していくと、月末にそれをバージョン番号付きの正式なリリースに昇格させる作業が必要になります。私はこの「昇格」を、月末の最後の土曜にカフェで行うようにしています。CHANGELOG をきちんと書いている自分への小さなご褒美のような時間です。
CHANGELOG の運用に慣れてきたら、そのデータを使って次の四半期の方針を立てる、という応用も効きます。Antigravity の .agentic/rules で CHANGELOG を必読資料に指定する方法は、Antigravity のカスタムルールでプロジェクト設定をマスターするで詳しく扱っているので、興味があれば併せてご覧ください。
次のひとつのアクション
今回のフローは、すでに git log がある方ならすぐに試せます。まずは git log --no-merges --since="2 weeks ago" --oneline を打って、自分の 2 週間分のコミットを眺めてみてください。「ユーザー視点で意味のあるもの」がどれだけあるか、それだけでも気付きがあるはずです。そこから、Antigravity に渡す形に整える 10 行のシェルスクリプトを足せば、来週の土曜から CHANGELOG.md は自然に育ち始めます。
CHANGELOG は単なる更新履歴ではなく、未来の自分にコードベースの歩みを伝えるラブレターのようなものだと、私は思っています。