セマンティックバージョニングの自動化とは、つまり「次のリリースをどれだけ上げるか」を commit メッセージに決めさせることだ。Conventional Commits の対応では、feat は minor、fix は patch、BREAKING CHANGE: を含む commit は major になる。semantic-release の commit analyzer が読むのもメッセージそのもので、その commit がどのファイルを変えたかは見ない。
この方式は、commit を書く人が各種類のバージョンへの影響を理解している、という前提に立っている。commit を coding agent が書くことが増えるほど、この前提は揺らぐ。エージェントは「何かを追加した」というだけで feat と書くかもしれない。monorepo でドキュメントサイトの不具合を直して fix(site) と書けば、analyzer はそれもパッケージの patch として数える。リファクタリングに BREAKING CHANGE: フッターを付ければ、次のマージでそのまま major が出る。どのルールも破られていないのに、出てくるバージョンはもうメンテナーが意図したものではない。
もう一つの前提はツール側にある。よくある構成は、リリースを semantic-release、commit の検査を commitlint が担い、そこに release notes 用の changelog preset を加えるものだ。三つのツールはそれぞれ設定形式が違うので、同じ種類のルールを release.config.js、commitlint.config.js、preset に別々に書くことになる。ルールを変えれば、検査、バージョン解析、release notes の三か所で同じように効くかを確かめなければならない。エージェントにとっても、ルールが設定ファイルとプラグインに散らばっていると、「この種類は何をリリースするのか」を一か所で読み取れない。
aronrepo は、この問題のために私が作ったツールだ。エージェントとメンテナーが同じルールで作業し、誤ってリリースされる commit はエージェントの判断ではなくルールが止める。
一つのパッケージ、固定された一組のルール
aronrepo は commit の検査、バージョンの計画、release notes、npm への公開、GitHub Release を一つのパッケージにまとめている。semantic-release、commitlint、conventional-changelog を別途入れる必要はない。
自分のプロジェクトに導入するには、aronrepo の GitHub リポジトリで README の「AI Coding Integration」にある導入用プロンプトをコピーし、coding agent に貼り付ければ、プロジェクトの環境に合わせて設定を進められる。
この設計にはいくつかのトレードオフがある。
種類は固定、意味はそれぞれ一つ
リポジトリが commit の種類を追加したり名前を変えたりすることはできない。Feat は新しい機能、Improve は既存機能の改善、Fix は公開済みの動作のバグ修正、Upgrade は実行時依存の変更、Chore はメンテナンス作業だ。Docs、Test、Build、CI などはリリースしない。一覧にない種類や、要約が句点で終わる commit は aronrepo check が拒否し、正しいヘッダーを提案する。種類と scope は大文字小文字を区別しない。fix(core): repair cache と Fix(Core): Repair cache は同じ commit として扱われ、release notes では要約の先頭が大文字になる。Conventional Commits から移行するリポジトリも、ほとんどの commit をこれまで通り書ける。
種類を固定すると、プロジェクトごとのカスタマイズはできなくなる。私はその代償を受け入れている。種類をカスタマイズできると、エージェントはまず各リポジトリの方言を覚えなければならない。固定されていれば、今回の変更がどの種類かを判断するだけで、リリースのレベルはルールが決める。
minor と major はオーナーが決める
デフォルトの explicit モードでは、Bump(Minor) と Bump(Major) 以外の種類はすべて最大でも patch しか出さず、BREAKING CHANGE: フッターは拒否される。つまりエージェントが Feat と書いても出るのは patch までで、minor や major には明示的な Bump commit が要る。Conventional Commits の動作が必要なリポジトリは auto モードに切り替えられ、Feat で minor、破壊的変更のフッターで major が出る。
二つのモードの違いは、バージョン番号が利用者にとって何を意味するかにある。

explicit は、minor と major を対外的なリリースとして扱うプロジェクトに向いている。たとえば移行ガイドを公開しているフレームワーク、デザインシステム、UI コンポーネントライブラリだ。こうしたプロジェクトの major には移行ドキュメント、告知、互換期間が伴うことが多く、minor もリリースノートやドキュメント改訂と対応する。そのタイミングはオーナーが決める。日々マージされる機能や修正は patch として出し続け、外に向けて説明できるだけたまったら Bump(Minor) を一つ push する。Bump はリリースパスの検査の対象外なので、空の commit でもよい。たとえば git commit --allow-empty -m "Bump(Minor): Release the new theme API" だ。代償は、新機能がまず patch として出ることだ。~ の範囲で patch に固定している利用者にも新しい API が届くが、セマンティックバージョニングの厳密な定義ではこれは minor にあたる。
auto は、バージョン番号を主に人ではなくツールや依存範囲が読むプロジェクトに向いている。チーム内で共有するパッケージ、自社アプリケーションが使う SDK、機能の単純な CLI や utility などだ。利用者は ^ の範囲で自動的に更新し、「新しい API があるか、互換性が壊れたか」をバージョンが正確に表すことを求める。一方で、minor ごとに誰かが時期を決める必要はない。この場合、commit の種類と BREAKING CHANGE: フッターがそのままバージョン番号になるので、PR のレビューでは commit のヘッダーとフッターも確認しなければならない。CI の aronrepo check --title は形式の誤りを止められるが、変更が本当に互換性を壊すかどうかまでは判断できない。
モードを選ぶこと自体もオーナーの判断だ。aronrepo がエージェントに渡すルールにはこう書かれている。導入時にはどちらのモードを使うかオーナーに尋ねなければならない。導入済みのリポジトリでは、ユーザーがその会話の中で求めない限り、エージェントは Bump(Major)、Bump(Minor)、破壊的変更のマーカーを書いてはならない。
公開ファイルに触れない commit はリリースしない
aronrepo はリリースパスを使って、commit が公開される内容に触れたかどうかを判断する。デフォルトは公開 workspace パッケージのディレクトリで、テスト、fixture、benchmark、サンプル、changelog などは除外される。リリース種類の commit がどのリリースパスも変更していなければ、aronrepo check がマージ前に拒否し、リリースも起きない。先ほどの Fix(Site) は、リリースしない種類に書き直すよう求められる。

すべての判断に理由がある
aronrepo explain は次のバージョンと、各 commit がリリースする理由、しない理由を示す。aronrepo release も公開時に同じ判断を記録し、--dry-run では計画と release notes だけを出力する。エージェントはリリースブランチに push する前に explain を実行でき、PR をレビューするメンテナーも同じ結論を見ることになる。explain --json はリリースされる commit(head)と release notes 全文も出力するので、CI がそれをジョブのサマリーに載せれば、承認する内容と実際に公開される内容が一致する。
中断したリリースを最後まで終えられる
monorepo のリリースは途中で失敗しがちだ。一部のパッケージは npm に上がったのに、tag はまだ push されていない。aronrepo release はまずすべてのパッケージをステージング用の dist-tag で公開し、レジストリがすべてを配信できることを確認してから正式な dist-tag を動かし、そのあと tag を push して GitHub Release を作る。同じジョブを再実行すると、同じ commit から公開済みのバージョンはスキップされ、足りない tag や release は補われる。バージョンは vX.Y.Z の tag からだけ読み取り、package.json に書き戻して commit することはない。
いつ出すかはメンテナーに任せられる
push したらリリースする、というのは CI のデフォルトの書き方にすぎない。リリース日が決まっているプロジェクトでは、PR は main にマージし続け、ステージング環境へのデプロイもいつも通り行い、正式リリースだけはメンテナーが時期を決めたいことが多い。これに release ブランチも Release PR もいらない。aronrepo のバージョンは直前の tag からリリースする commit までで計算されるので、月曜から木曜にマージした 4 つの Fix を金曜に出しても patch 1 回分になり、release notes には 4 件がまとめて並ぶ。
変えるのはトリガーだ。main への push では explain --json だけを実行し、バージョン、commit、release notes をジョブのサマリーに書き出す。正式リリースは手動で起動する workflow にして、プレビューの commit とバージョンを入力として受け取り、required reviewers を設定した GitHub Environment で実行する。承認は GitHub のデプロイ履歴に残る。リリースのステップでは次を実行する。
aronrepo release --branch main --expect 1.2.4release はまず、チェックアウトした commit が本当に origin/main 上にあるかを確かめ、feature ブランチの commit が main として公開されるのを防ぐ。--expect はリリースの時点で計画を計算し直し、承認時に見たバージョンと違えば何も公開せずに止まる。次のリリースはこの tag から数え直すので、承認後にマージされた commit は次のバージョンに回る。workflow の全体は aronrepo の README にある。
エージェントに渡すのはドキュメントではなくデータ
ルールを README に書くだけでは、エージェントはそれを読んで覚えておく必要がある。aronrepo は一つのポリシーを三つの出口から提供する。
aronrepo policy --jsonは、リポジトリのモード、リリースパス、各種類のリリースレベルと説明を出力する。aronrepo agents --writeはポリシーのブロックをAGENTS.mdに書き込み、コマンドはリポジトリのパッケージマネージャーに合わせて生成される。ブロックが古くなるとaronrepo agentsとaronrepo doctorが失敗するので、種類の表を手で写す人はいない。aronrepo checkは commit-msg hook、PR の各 commit、PR のタイトルに同じ検査を行う。ヘッダーが不合格なら、修正案を表示する。
README には、coding agent にそのまま貼り付けられる導入用のプロンプトもある。リポジトリを調べ、どちらのモードを使うかオーナーに尋ね、semantic-release と commitlint を外し、hook と CI を加え、最後に doctor、explain、release --dry-run を実行して次のバージョンを報告する、という流れだ。導入作業そのものには Build、CI、Chore(Agent) のようなリリースしない種類を使う。
semantic-release、release-please、changesets との比較
JavaScript プロジェクトでよく使われるリリースツールには、ほかに二つのやり方がある。release-please も Conventional Commits を読むが、直接リリースはせず、Release PR を維持して、それがマージされたときに tag と GitHub Release を作る。changesets は commit メッセージをまったく見ない。開発者が変更ごとに changeset ファイルを添え、patch、minor、major のどれを出すかを書く。
| 項目 | aronrepo | semantic-release | release-please | changesets |
|---|---|---|---|---|
| バージョンの根拠 | 固定された commit の種類 | commit メッセージ(デフォルトは Angular 規約、preset で変更可) | Conventional Commits のメッセージ | 別に書く changeset ファイル |
| minor と major を決めるもの | explicit:オーナーが書く Bump、auto:commit の種類 | commit の種類と BREAKING CHANGE | commit の種類と !、Release-As でバージョンを指定可 | 各 changeset が宣言するレベル |
| リリースのタイミング | 既定はリリースブランチへの push で出る。手動トリガーでメンテナーが承認した commit を出すこともできる | リリースブランチへの push で出る | Release PR のマージ時 | changeset version と publish の実行時。通常は Version Packages PR を経由 |
| バージョン番号の保存先 | git tag のみ、package.json には書き戻さない | git tag。書き戻しには @semantic-release/git が別途必要で、公式は非推奨 | Release PR が package.json と manifest に書き込む | changeset version が package.json に書き込む |
| Release notes | GitHub Release の本文 | GitHub Release の本文。CHANGELOG.md には別のプラグインが必要 | CHANGELOG.md と GitHub Release | パッケージごとの CHANGELOG.md |
| commit の検査 | check を内蔵:hook、PR の各 commit、PR のタイトル | なし、commitlint を別途導入 | なし | commit は見ない。changeset status で changeset の不足を検査できる |
| 公開ファイルに触れないリリース種類の commit | マージ前に拒否し、リリースしない | メッセージどおりにリリース | 単一パッケージならリリース。monorepo では変更パスでパッケージに振り分ける | 該当しない。リリースするかは changeset が決める |
| monorepo | 対応、全パッケージが一つのバージョンを共有 | コアは一度に一パッケージ、monorepo はコミュニティのプラグイン頼み | manifest 設定でパッケージごとに独立したバージョン、連動も可 | 主な設計対象。パッケージごとに独立したバージョンで、fixed、linked で束ねられる |
| npm への公開 | 内蔵。まずステージング用 dist-tag で公開し、すべてそろってから切り替える | 内蔵(@semantic-release/npm) | 担当しない。ワークフローに公開ステップを別に書く | changeset publish を内蔵、npm にまだないバージョンだけを公開 |
| プレリリース | alpha、beta、rc、canary ブランチ | プレリリースブランチと channel | prerelease 設定 | pre enter、pre exit モードと snapshot |
| 中断後の再実行 | 足りない公開、tag、Release を補う | tag は公開前に push され、公開に失敗すると手作業で復旧 | 公開は担当しない | publish を再実行すると公開済みのバージョンはスキップ |
| リリース前のプレビュー | explain(--json は commit と release notes を含む)、release --dry-run | --dry-run | Release PR そのもの | changeset status |
| エージェント向けのルール | policy --json、AGENTS.md のブロックを生成 | なし | なし | なし |
| 対象範囲 | JavaScript、npm への公開のみ | 多言語、プラグイン頼み | 多言語、言語ごとに対応する strategy | JavaScript パッケージマネージャーの workspace |
エージェントが commit を書く状況に置くと、四つの違いは「誰が、いつリリースのレベルを決めるか」に集約される。semantic-release ではその場の commit メッセージが決め、マージすれば出る。release-please もメッセージが決めるが、Release PR があるので、リリース前にバージョン番号と changelog をもう一度人が見られる。changesets はレベルを changeset ファイルに書くので、エージェントが changeset を書くならレベルを選ぶのもエージェントで、歯止めは PR のレビューになる。aronrepo は explicit モードで minor と major をエージェントの手から取り上げ、リリースすべきでない commit をマージ前に拒否する。
パッケージごとに独立したバージョンが必要なら、changesets のほうが合っている。多言語に対応したい、あるいは GitHub の画面上で PR をマージしてリリースを承認したいなら release-please が向く。npm 以外の公開先や特定のプラグインが必要なら、エコシステムがいちばん充実しているのは semantic-release だ。
インストール規模
機能を一つのパッケージにまとめると、依存も減る。以下の数字は、それぞれを新しいディレクトリで npm install --ignore-scripts した結果だ。パッケージ数は npm が報告する added の数、サイズは node_modules の du による。semantic-release 単体には commit の検査が含まれないので、aronrepo と範囲がそろうのは「semantic-release と commitlint」の組み合わせになる。release-please と changesets は commit を検査しないので、それぞれの CLI 単体を計測した。
| 項目 | aronrepo | semantic-release | release-please | changesets |
|---|---|---|---|---|
| 計測したパッケージ | aronrepo(計測日の最新版) | semantic-release 25.0.9 | release-please 17.11.2 | @changesets/cli 3.0.3 |
| 必要な Node.js | 22.18 以上 | ^22.14 または 24.10 以上 | 22 以上 | ^22.11、^24 または 26 以上 |
| 直接依存 | 4 | 28 | 31 | 21 |
| インストール後のパッケージ総数 | 7 | 301(commitlint を加えると 345) | 162 | 40 |
node_modules のサイズ | 2.7 MB | 79 MB(commitlint を加えると 105 MB) | 93 MB | 3.7 MB |
| 本体パッケージの展開サイズ | 366 kB | 128 kB | 929 kB | 89 kB |
インストールされたパッケージ数
aronrepo は 7 パッケージ、changesets は 40、release-please は 162 をインストールする。aronrepo と範囲が近い semantic-release と commitlint の組み合わせは 345 パッケージ。
- aronrepo7
- changesets 3(@changesets/cli)40
- release-please 17162
- semantic-release 25(commit 検査なし)301
- semantic-release 25 + commitlint345
パッケージ数の表を表示
| 構成 | インストールされたパッケージ数 |
|---|---|
| aronrepo | 7 |
| changesets 3(@changesets/cli) | 40 |
| release-please 17 | 162 |
| semantic-release 25(commit 検査なし) | 301 |
| semantic-release 25 + commitlint | 345 |
2026 年 11 月 7 日、新しいディレクトリで npm install --ignore-scripts を実行し、npm が報告する added の数を採った。commitlint の構成には @commitlint/cli と @commitlint/config-conventional を含む。
計測方法node_modules のサイズ
aronrepo の node_modules は約 2.7 MB、changesets は約 3.7 MB。release-please は約 93 MB、semantic-release と commitlint の組み合わせは約 105 MB。
- aronrepo2.7
- changesets 3(@changesets/cli)3.7
- release-please 1793
- semantic-release 25(commit 検査なし)79
- semantic-release 25 + commitlint105
インストールサイズの表を表示
| 構成 | MB(du で計測) |
|---|---|
| aronrepo | 2.7 |
| changesets 3(@changesets/cli) | 3.7 |
| release-please 17 | 93 |
| semantic-release 25(commit 検査なし) | 79 |
| semantic-release 25 + commitlint | 105 |
上のグラフと同じインストールで、node_modules を du で計測した。ファイルシステムのブロックサイズによって値は多少変わる。
計測方法範囲がそろう semantic-release と commitlint の組み合わせと比べると、パッケージ数は 345 から 7 に、サイズは約 105 MB から約 2.7 MB に減る。実は aronrepo の本体パッケージは semantic-release より大きい(展開後で約 366 kB と 128 kB)。commit の検査と CLI を含んでいるためだ。差のほぼすべては依存ツリーから来ている。aronrepo の直接依存は semver、js-yaml、picomatch、tinyglobby の四つだけだ。
changesets も同じく軽量だが、それは commit を解析せず、GitHub Release も作らないからで、その部分は別の GitHub Action に任されている。release-please の CLI はインストール規模が semantic-release に近いものの、多くのプロジェクトは公式の GitHub Action から実行するので、プロジェクトの依存には入らない。
向いている条件と代償
aronrepo の範囲は意図的に狭い。ESM 専用で、Node.js 22.18 以上が必要だ。一つのリポジトリで公開するパッケージはすべて同じバージョンを共有する。パックにはリポジトリのパッケージマネージャーを使い、公開は常に npm を通す。commit の種類を独自に定義したい、パッケージごとに別々のバージョンを付けたい、npm 以外のレジストリのフローを使いたい、といった要望は設計の範囲外だ。
すでに独自の堅牢なリリースパイプラインを持つプロジェクトも、全部を置き換える必要はない。CLI の裏にある関数は aronrepo/node から、commit の規約、バージョン、release notes の補助関数は aronrepo から export されている。バージョン、tag、notes の決定だけを aronrepo に任せ、パック、検証、アップロードは既存のスクリプトに残すこともできる。
私が aronrepo で目指したのは一つのことだ。バージョンの判断を「commit を書いた人が正しく判断できたか」から「ルールがマージ前に止められるか」へ移すこと。エージェントはこれからも種類を選び間違える。違いは、間違えたときに check が拒否して代わりの書き方を示し、minor と major には必ずオーナーが明示的に書くことが求められる点にある。
