セマンティックバージョニングの自動化とは、つまり「次のリリースをどれだけ上げるか」を 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:カードが動かすのは patch だけで、minor と major はオーナーが鍵を開けるまで動かない。右は auto:commit の種類が歯車を通じて、どの桁が進むかを直接決める。

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) は、リリースしない種類に書き直すよう求められる。

小包、ブラウザーウィンドウ、試験管のアイコンを描いた白いカードの列が、金網を張った木枠を通る。小包のカードは木箱に入り、ブラウザーと試験管のカードは金属のレールに沿って横の白い紙箱に並ぶ。
リリースに進むのは、公開パッケージの内容を変えた commit だけだ。サイトやテストの変更も普通にマージされるが、バージョンは上がらない。

すべての判断に理由がある

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.4

release はまず、チェックアウトした 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 のどれを出すかを書く。

項目aronreposemantic-releaserelease-pleasechangesets
バージョンの根拠固定された commit の種類commit メッセージ(デフォルトは Angular 規約、preset で変更可)Conventional Commits のメッセージ別に書く changeset ファイル
minor と major を決めるものexplicit:オーナーが書く Bump、auto:commit の種類commit の種類と BREAKING CHANGEcommit の種類と !、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 notesGitHub 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 ブランチプレリリースブランチと channelprerelease 設定pre enter、pre exit モードと snapshot
中断後の再実行足りない公開、tag、Release を補うtag は公開前に push され、公開に失敗すると手作業で復旧公開は担当しないpublish を再実行すると公開済みのバージョンはスキップ
リリース前のプレビューexplain(--json は commit と release notes を含む)、release --dry-run--dry-runRelease PR そのものchangeset status
エージェント向けのルールpolicy --json、AGENTS.md のブロックを生成なしなしなし
対象範囲JavaScript、npm への公開のみ多言語、プラグイン頼み多言語、言語ごとに対応する strategyJavaScript パッケージマネージャーの 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 単体を計測した。

項目aronreposemantic-releaserelease-pleasechangesets
計測したパッケージaronrepo(計測日の最新版)semantic-release 25.0.9release-please 17.11.2@changesets/cli 3.0.3
必要な Node.js22.18 以上^22.14 または 24.10 以上22 以上^22.11、^24 または 26 以上
直接依存4283121
インストール後のパッケージ総数7301(commitlint を加えると 345)16240
node_modules のサイズ2.7 MB79 MB(commitlint を加えると 105 MB)93 MB3.7 MB
本体パッケージの展開サイズ366 kB128 kB929 kB89 kB

インストールされたパッケージ数

npm install --ignore-scripts · added · 2026-11-07

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
パッケージ数の表を表示
インストールされたパッケージ数 · インストールされたパッケージ数
構成インストールされたパッケージ数
aronrepo7
changesets 3(@changesets/cli)40
release-please 17162
semantic-release 25(commit 検査なし)301
semantic-release 25 + commitlint345

2026 年 11 月 7 日、新しいディレクトリで npm install --ignore-scripts を実行し、npm が報告する added の数を採った。commitlint の構成には @commitlint/cli と @commitlint/config-conventional を含む。

計測方法

node_modules のサイズ

npm install --ignore-scripts · du node_modules · 2026-11-07

aronrepo の node_modules は約 2.7 MB、changesets は約 3.7 MB。release-please は約 93 MB、semantic-release と commitlint の組み合わせは約 105 MB。

MB(du で計測)
  • aronrepo2.7
  • changesets 3(@changesets/cli)3.7
  • release-please 1793
  • semantic-release 25(commit 検査なし)79
  • semantic-release 25 + commitlint105
インストールサイズの表を表示
node_modules のサイズ · MB(du で計測)
構成MB(du で計測)
aronrepo2.7
changesets 3(@changesets/cli)3.7
release-please 1793
semantic-release 25(commit 検査なし)79
semantic-release 25 + commitlint105

上のグラフと同じインストールで、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 には必ずオーナーが明示的に書くことが求められる点にある。