commit-helper

commit-helper skill の概要

commit-helper ができること

commit-helper は、作業ツリーの変更内容をもとに、Conventional Commits 形式の Git コミットメッセージとコミット手順に落とし込むのを支援する skill です。毎回 type、scope、subject、body、footer のルールを手で思い出さなくても、より速く一貫したコミットを作りたい開発者に向いています。

commit-helper を導入すべき人

次に当てはまるなら、この commit-helper skill は有力な選択肢です。

• ふだんから Git を使っている
• changelog、リリースツール、チームレビューに向けて履歴をきれいに保ちたい
• コミット前に、agent に diff を見せてメッセージ案を作ってほしい
• 完全なリリースシステムではなく、type や scope の軽いガイドが欲しい

実際に解決したい仕事

多くのユーザーに必要なのは、コミット規約の講義ではありません。必要なのは「このファイルを変更した」から「信頼できるコミットメッセージを出してほしい」までを確実につなぐ方法です。commit-helper は、その実務的な一歩に絞っており、標準フォーマットに加えて、例、推奨 scope、検証スクリプトを組み合わせて使えるようにしています。

汎用プロンプトよりこの skill が役立つ理由

普通のプロンプトでもそれなりのメッセージは作れますが、commit-helper for Git Workflows には繰り返し使える構造があります。

• コミット関連の依頼で明示的に起動する設計
• Conventional Commits の定義済みフォーマット
• type 選択のガイダンスを内蔵
• references/scopes.md の scope 候補
• references/examples.md のサンプル
• scripts/validate_commit.py の検証スクリプト

この組み合わせにより、diff を見たときに feat、fix、refactor、chore のどれにすべきか迷いやすい場面でも、当て推量を減らせます。

導入前に知っておきたい制約

commit-helper は意図的に守備範囲を絞っています。得意なのはコミットメッセージの生成と整形であり、プロジェクト固有の contribution ルール、PR テンプレート、リリースポリシーの代わりにはなりません。また、曖昧な依頼文だけから意図を正確に推測するのも得意ではないため、出力品質は diff と、あなたが与える文脈に大きく左右されます。

commit-helper skill の使い方

commit-helper のインストール前提

リポジトリの SKILL.md には skill 単体の install コマンドは出ていないため、実際の導入経路は skill collection リポジトリ経由になります。

npx skills add https://github.com/zhaono1/agent-playbook --skill commit-helper

環境によって別の skills loader を使っている場合も、同じリポジトリ内の skills/commit-helper から導入します。

実際に commit-helper を呼び出す方法

実運用での commit-helper usage はシンプルです。変更をコミットしたい、またはコミットメッセージ案を作ってほしいと agent に頼みます。典型的なトリガーは次のとおりです。

• “commit my changes”
• “write a commit message for this diff”
• “format this as a conventional commit”
• “review git diff and suggest the best commit type and scope”

この skill は、コミットに関する依頼を検知して起動し、変更内容を確認したうえで、承認用のメッセージを準備する想定です。

commit-helper がうまく機能するために必要な入力

最低限役立つ入力は、実際の Git diff か、リポジトリの状態にアクセスできることです。さらに次の情報があると結果が良くなります。

• 何を変えたか
• なぜ変えたか
• ユーザーに見える挙動が変わるか
• bug fix、feature、refactor、docs 変更、インフラ作業のどれか
• issue 番号や breaking change の注記

こうした文脈がない場合でも skill はメッセージを整形できますが、選ばれる type、scope、body は汎用的すぎるものになりがちです。

あいまいな依頼を強いプロンプトに変える

弱い例:

• “commit this”

より良い例:

• “Review git diff and draft a Conventional Commit. This fixes a timeout in the user API by adding a 30-second query timeout and better error handling. Scope should reflect backend API work. Include a body explaining why the timeout mattered.”

これが有効な理由:

• type を fix 寄りに絞り込みやすい
• api のような scope を示唆できる
• body が単なるファイル要約ではなく、理由のある説明になる

おすすめの commit-helper ワークフロー

実用的な commit-helper guide は次の流れです。

1. まず、今回のコミットに入れたいファイルだけを stage する。
2. メッセージ品質を stage 済みの意図に合わせたいなら、agent に git diff --cached を見せる。
3. commit-helper にメッセージ案を作らせる。
4. type、scope、subject の長さを確認する。
5. 必要なら最終 subject を検証する。
6. コミットコマンドを承認する。

この「先に stage する」流れが重要なのは、異なる意図の変更が混ざった diff だと、メッセージも曖昧になりやすいからです。

本格利用前に先に読むべきファイル

skill を短時間で見極めたいなら、次の順番で読むのが効率的です。

1. skills/commit-helper/SKILL.md
2. skills/commit-helper/README.md
3. skills/commit-helper/references/conventional-commits.md
4. skills/commit-helper/references/examples.md
5. skills/commit-helper/references/scopes.md
6. skills/commit-helper/scripts/validate_commit.py

この順に見ると、フォーマット、サンプル、使える scope、実際にどこまで厳密にチェックされるかが把握できます。

commit-helper が type と scope をどう選ぶか

この skill の価値は、1 行目を整形することだけではありません。変更内容を使いやすいコミット分類に落とし込む助けにもなります。

• feat: 新しいユーザー向け機能
• fix: バグ修正
• refactor: 挙動を変えない内部コード整理
• docs, test, ci, build, chore, perf, style: より限定的なケース

scope については、付属の reference に auth、api、components、database、docker、deps のような一般的なモジュール名が示されています。リポジトリ側で定着したローカルなモジュール名があるなら、汎用的な scope よりそちらを優先したほうが自然です。

コミット自動化の前に validator を使う

このリポジトリには、実際に使える validator が含まれています。

python scripts/validate_commit.py "feat(api): add user endpoint"

このスクリプトは、subject の形式、許可された type、任意の scope、subject の長さ、末尾ピリオドの有無、そして命令形かどうかの簡易チェックを行います。commit-helper install 後に、より大きな agent ワークフローへ組み込む前提で信頼性を見たい場合に有用です。

出力品質に影響する制約

リポジトリ実装に基づく制約として、特に次の点は重要です。

• validator は type(scope): プレフィックス以降の subject を 50 文字までに制限している
• 対応 type はスクリプト内で固定されている
• reference には revert があるが、提示されている validator のパターンでは受け付けない
• 命令形の wording が前提になっている
• プロジェクト固有の scope は、与えない限り skill 側では判断できない

つまり、Conventional Commits としては妥当に見えるバリエーションでも、この skill のローカルな検証ルールでは弾かれる場合があります。

commit-helper が向くケースと向かないケース

向いているケース:

• 1 つの目的に絞ったコミット
• Conventional Commits を使っているリポジトリ
• 軽い自動化を入れつつ、読みやすい履歴を保ちたいチーム
• リポジトリと git diff にアクセスできる agent

向かないケース:

• 無関係な変更が大量に混ざった大きなコミット
• Conventional Commits から外れた独自コミット規約を使うチーム
• コミットメッセージの詳細を後で PR の merge UI 側で決める squash-only ワークフロー
• この skill 単体で semantic versioning の自動判断まで期待するユーザー

commit-helper skill の FAQ

commit-helper は初心者にも向いていますか？

はい。commit-helper は type の一覧、scope の例、サンプルメッセージがあるので、初心者にも使いやすい設計です。ただし注意点として、初心者であっても「何を変えたか」「なぜ変えたか」は説明する必要があります。そこが曖昧だと、agent 側も推測に頼るしかありません。

commit-helper は整形だけですか？ それとも内容の判断もしますか？

両方です。この skill は、すでに書いた文章を整形するだけでなく、変更内容を見てメッセージ構成そのものを下書きできます。ただし、判断の質は diff の明確さとプロンプトの具体性に左右されます。

AI にコミットメッセージを頼むのと commit-helper の違いは何ですか？

違いは一貫性です。汎用の AI プロンプトでももっともらしいコミット行は作れますが、commit-helper skill には定義済みフォーマット、サンプル、scope ガイド、validator script があります。繰り返し使う前提では、その分だけ信頼しやすく、標準化もしやすくなります。

commit-helper はどんなリポジトリでも使えますか？

たいていは使えますが、scope をモジュールやドメインに素直に対応づけられるリポジトリほど相性が良いです。構造がゆるいリポジトリでは、独自の scope 語彙を定義しない限り、scope 選択が主観的になりやすくなります。

どんなときは commit-helper を使わないほうがよいですか？

1 つのコミットに無関係な変更が複数入っているときは、commit-helper for Git Workflows に頼りすぎないほうがよいです。先に作業を分割してください。そうしないと、形式だけ整ったメッセージになっても、コミット自体の質は低いままです。

breaking changes や issue 参照にも対応していますか？

reference では Conventional Commits スタイルの body と footer を扱っているため、issue リンクや breaking change の注記を含めることはできます。ただし、提示されている validator は subject 行の検証に最も重きを置いています。

チーム全体での強制運用にも十分ですか？

それだけでは不十分です。作者がよりよいコミットを書く支援にはなりますし、validator でローカルチェックもできますが、チーム全体で徹底するなら通常は Git hooks、CI チェック、あるいはリポジトリの contribution policy も併用する必要があります。

commit-helper skill を改善するには

diff だけでなく、commit-helper に「なぜ」を渡す

commit-helper の結果を一番大きく改善するのは、意図を渡すことです。diff から分かるのは「何が変わったか」であって、「なぜ変えたか」までは見えないことが多いです。ユーザー影響や根本原因を 1 文添えるだけでも、生成される body の実用性はかなり上がります。

変更が曖昧なら type の候補比較を頼む

変更が fix とも refactor とも取れるなら、agent に選択肢を比較させてください。

• “Draft the best commit, then explain why this is fix rather than refactor.”
  こう依頼すると分類根拠が明確になり、履歴のラベル誤りも減らせます。

プロジェクトで実際に使う scope を与える

同梱の scope 一覧は出発点にすぎません。commit-helper usage を改善したいなら、たとえば次のような自分たちの scope を agent に伝えるのが有効です。

• billing
• search
• notifications
• admin-ui

これにより、リポジトリにもっと適切なドメイン名があるのに、utils や services のような曖昧な scope が選ばれるのを防げます。

commit-helper を使う前にコミットを細かく分ける

この skill は、1 回の論理変更に対して最もよく機能します。agent が 1 つの diff の中に refactoring、依存関係更新、bug fix を同時に見ると、無難ではあるが役に立ちにくい chore を選んだり、広すぎる body を書いたりしがちです。

自動化するなら早めに validate する

commit-helper を script や agent action に組み込む予定なら、テスト段階で scripts/validate_commit.py を回しておくべきです。そうすると、reference に書かれている仕様と、実際に受け付けられるパターンのズレを、本番依存する前に発見できます。

validator と仕様のズレに注意する

実務上の改善ポイントとして大きいのは整合性です。reference には revert が出てきますが、提示されている validator pattern では受理されません。この skill を本格導入するなら、references/conventional-commits.md と scripts/validate_commit.py を見比べて、ローカル運用の前提を調整するか、script 側を修正してください。

修正プロンプトで最初の出力を磨く

最初の下書きが惜しいときは、やみくもに再生成するより、狙いを絞った追加入力のほうが効果的です。

• “Make the subject more specific.”
• “Use auth scope instead of api.”
• “Explain why the timeout fix matters.”
• “Shorten the subject to pass validation.”
• “Split this into two commit messages.”

こうした指示のほうが、全面的な書き直しを求めるより速く結果を改善できます。

使う頻度が高いなら repo 固有の例を追加する

長期的に見て commit-helper guide の質を一番高めるのは、自分たちのコードベースに即した例を増やすことです。特定ドメインの変更をチームで頻繁にコミットするなら、examples と scopes の reference を拡張することで、skill の精度は上がり、汎用的すぎる出力も減らせます。