👋 ごあいさつ

こんにちは。日々 Claude Code にお世話になっている開発者の一人です。

Claude Code のカスタムスキル機構を使って、自分の開発フローに合わせた「スラッシュコマンド」を作って運用しています。本記事ではその第一弾として、コミットメッセージ作成の苦痛を消すスキル /commit を、設計思想ごと全文公開します。

「LLM にコミットを任せたいけど、暴走されたら怖い」と感じている人にこそ届けたい内容です。少しでもピンと来たら、ぜひ最後まで読んでみてください。

📖 はじめに

対象読者：Claude Code をすでに日常的に使っていて、コミットメッセージ作成を効率化したい人
ゴール：自分の環境で /commit を実行できるようになる
流れ：(1) 3分で導入 → (2) 設計の解説 → (3) スキル全文公開 → (4) もっと例を見る → (5) カスタマイズ

「スキルの中身を見たい人」は GitHub の commit/SKILL.md に直接飛んで良い。

👀 まずは見てほしい

百聞は一見に如かず。/commit を実行した瞬間に何が起きるか、最初に見せる。

🔒 大前提：/commit は「あなたが git add した変更」だけを対象にコミットメッセージを生成します。
unstaged / untracked のファイルには 一切触れません。LLM が勝手に拾ったり、勝手に add したり、勝手に reset したりしないよう、スキル仕様で明示的に禁じてあります。

Before：いつものコミット作業

🧑‍💻 ターミナルでの操作（自分で考えながら）

$ git status
On branch feature/user-auth
Changes to be committed:
  modified:   src/api/user.ts
  modified:   README.md
  new file:   src/api/user.test.ts

$ git diff --cached
# ... 100行のdiffを眺める

🧠 ここから先は頭の中の苦痛タイム

「これって feat？ fix？ docs と test も混ざってる... 一緒にコミット？分ける？」
「日本語でなんて書こう...」
「あ、.env もステージングしちゃってた、危ない」

🧑‍💻 3分後、妥協してターミナルに戻る

$ git commit -m "feat: ユーザー認証APIを追加してREADMEとテストも更新"

→ feat と test と docs が混ざった、粒度の粗いコミットが履歴に残る。

After：`/commit` と打つだけ

🧑‍💻 あなたの入力（Claude Code のプロンプト）

/commit

🤖 Claude Code の応答（チャット上に表示される）

ステージング済みの変更：
- src/api/user.ts（modified）
- src/api/user.test.ts（new file）
- README.md（modified）

複数のスコープが混在しています。分割案：

コミット1: feat: ユーザー認証 API を追加
  - src/api/user.ts

コミット2: test: ユーザー認証 API のテストを追加
  - src/api/user.test.ts

コミット3: docs: README にセットアップ手順を追記
  - README.md

🖱️ 続いてボタンが3つ表示される（クリックで選ぶ）

[ 提案通り分割 ]   [ 1コミットに統合 ]   [ キャンセル ]

提案通り分割 を押す。

✅ 結果（ターミナルで確認）

$ git log --oneline -3
a1b2c3d docs: README にセットアップ手順を追記
e4f5g6h test: ユーザー認証 API のテストを追加
i7j8k9l feat: ユーザー認証 API を追加

きれいに3つのアトミックなコミットが、Conventional Commits 準拠の日本語で並んでいる。

ここがこのスキルの 一番の価値 だと思っている。

💡 このスキルの本当の価値は「分割提案」にある

単に staged な変更からコミットメッセージを生成するだけなら、Claude Code に普通に頼めばやってくれる。/commit の独自性は diff の中身とファイルパスを見て「これは feat」「これは test」「これは docs」と意味で分類し、複数コミットに分けることを提案する ところにある。

機能追加と無関係な README 修正が同じコミットに混ざる、というありがちな事故が起きにくくなる。「アトミックコミットがベストプラクティスなのは分かっているけど、毎回分けるのは面倒でサボる」 — そんな状況を、ボタン1回押すだけに置き換えてくれる。

✨ このスキルがすごい8つの理由

1. コミット対象は「あなたが `git add` したもの」だけ

/commit は ステージング済み（git diff --cached で見える範囲）の変更のみ をコミットメッセージ生成の対象にする。unstaged や untracked のファイルは、たとえ目の前にあっても 一切触らない・聞かない・拾わない。

「ユーザが意図的に git add した範囲こそが、いまコミットしたい単位」という前提を絶対に守る。LLM に Git を任せる怖さの大半は 「勝手にスコープを広げられる」 ことから来るが、それを構造的に封じている。

2. 思考停止でも履歴がきれいになる

Conventional Commits の prefix（feat / fix / docs / refactor ...）を毎回正しく選ぶの、地味に脳のリソースを食う。/commit は diff を読んで自動で判定してくれる。

3. アトミックコミットの「面倒くささ」を消す

これがこのスキルで個人的に一番気に入っているところ。

ステージング済みの変更が複数のスコープに渡る場合、/commit は diff の中身とファイルパスを見て、コミットを分けるべきか判定 し、分割案を提案してくれる。たとえばこんな具合に：

コミット1: feat: ユーザー認証 API を追加
  - src/auth/api.ts
コミット2: test: ユーザー認証 API のテストを追加
  - src/auth/api.test.ts
コミット3: docs: README にセットアップ手順を追記
  - README.md
コミット4: chore: 依存パッケージを更新
  - package.json
  - package-lock.json

「アトミックコミット（1コミット1変更）がベストプラクティス」なのは皆知っているけど、毎回 git add -p で慎重に分けて、git commit を4回打って... というのは面倒でサボりがち。

/commit はそこを ボタン1回押すだけ に置き換えてくれる。アトミックコミットの習慣を維持するコストが大きく下がる、というのが地味だけど効く改善点。

4. 典型的なクレデンシャルファイルを自動で除外

.env *.pem credentials.json id_rsa ... よくある危険ファイル名を パターンマッチで自動除外し、「これらを除外しました」とチャットに明示する。git add . でうっかり全部ステージングしてしまった日にセーフティネットとして効く。

⚠️ 免責：これはファイル名パターンによる除外なので、以下はカバーされない：

ソースコード内にハードコードされた API キーやパスワード

リストに無い独自の命名（例：prod-secrets.txt）

暗号化されていない秘密情報を含むビジネスデータファイル

あくまで「典型的なミスを減らす」仕組み。最終確認はコミットメッセージ表示時に自分の目で行うのが安全。除外したいパターンが他にあれば、SKILL.md の Step 4 のリストに追記すればすぐ拡張できる。

5. `Co-Authored-By: Claude` を付けない

Claude Code はデフォルトでコミットフッターに Co-Authored-By: Claude を付けようとするが、これが嫌な人は多いはず。/commit は 1行コミット固定。本文もフッターも一切付かない。

6. LLM の暴走をスキル側で封じている

理由1で挙げた「ステージング外に手を出さない」に加え、/commit は 絶対ルール として：

失敗時に勝手にロールバックしない（git reset を自動実行しない）
--amend を使わない（既存コミットを書き換えない）
--no-verify を使わない（pre-commit フックを必ず通す）

LLM に Git を任せる怖さを、プロンプトではなく 仕様書のレベルで 潰してある。

7. コミット後に PR 説明文まで生成

コミットが終わると、そのまま GitHub の PR 説明欄にコピペできる Markdown が出てくる：

## 概要
ユーザー認証 API を新規実装し、テストと README を追加した。

## 変更内容
- `src/api/user.ts` — JWT ベースの認証エンドポイントを追加
- `src/api/user.test.ts` — 正常系・異常系のテストケースを追加
- `README.md` — セットアップ手順を追記

コミット → PR 作成の二度手間がゼロ。

8. わずか170行の Markdown 1ファイル

実装はファイル1枚。読めるし、改造できるし、好みに合わせて自分のスキルに育てられる。「魔法」じゃなく「設計された仕様書」 を Claude Code に読ませているだけ。

⚡ 3分で導入する

/commit スキルは GitHub で公開しています。SKILL.md 1ファイルを所定のパスに配置するだけで使えるようになります。

🔗 このスキルのディレクトリ: shochin666/skills/commit

1. 配置先のディレクトリを作る

mkdir -p ~/.claude/skills/commit

2. GitHub から `SKILL.md` を取得して配置

リポジトリの commit/SKILL.md を開く。ファイルビュー右上にある2つのアイコンボタンのどちらかを使う：

📋 Copy raw file — クリックでクリップボードに全文がコピーされるので、ローカルの ~/.claude/skills/commit/SKILL.md に貼り付け
⬇️ Download raw file — クリックでそのまま SKILL.md がダウンロードされるので、~/.claude/skills/commit/ に移動

どちらも「Raw」ページを経由せず1クリックで完結する。ファイル1枚で済むので、ビルドもインストールも不要。

3. Claude Code を再起動

セッションを開き直すと、スラッシュコマンド一覧に /commit が出てくる。

使ってみる

コミットしたいファイルだけを git add した状態 で：

/commit

これだけ。/commit が生成するメッセージは その時点でステージング済みの変更のみ を対象にする（unstaged / untracked は完全に無視される）ので、まず git add で「今コミットしたい範囲」を自分で決めるのが使い方の鉄則。

📝 リポジトリには他のスキルも追加していく予定です。 Star や Issue で意見をもらえると励みになります。

🛠️ 設計：なぜこの仕様にしたのか

/commit の本質は「LLM にコミットメッセージを生成させる」ことではなく、「LLM が暴走しがちなポイントを設計で潰す」 ことにある。以下、こだわりを順に説明する。

こだわり1: ステージング済みの変更しか触らない

LLM は親切心で「ついでに untracked のファイルも git add しましょうか？」と聞いてくる。/commit は git diff --cached で見える範囲のみ をコミット対象とし、ユーザの意思で git add した範囲を絶対に超えない。

こだわり2: 複数 prefix が混在したら必ず分割を提案する

「あとで分けよう」と思って結局まとめてしまうコミット。/commit はこれを検出して分割案を出し、ユーザが「分割」「統合」「キャンセル」を選ぶだけにする。「分割するのが面倒」を技術で殲滅する。

こだわり3: 典型的なクレデンシャル名を自動除外（ただし最終確認は人間）

.env *.pem credentials.json id_rsa .aws/credentials などは コミット対象から自動除外 し、「除外しました」とチャットに明示する。黙って除外しないのが重要で、意図的なダミー値だった場合もユーザが気づける。

ただしこれはファイル名のパターンマッチによる安全装置であって、config.ts の中に書いたままの API キーや、リストに無い独自命名（prod-secrets.txt など）はすり抜ける。「除外できなかった可能性」を意識して、生成された PR フォーマット出力やコミット内容は最後に必ず目視確認する前提で運用するのが安全。

こだわり4: 失敗時に自動で `git reset` しない

pre-commit フックで失敗したり、複数コミット途中で止まったりしたとき、LLM はつい先回りで git reset したくなる。これが事故の元。/commit は 失敗時はそこで停止して git status を表示し、判断をユーザに渡す。

こだわり5: `Co-Authored-By: Claude` を付けない

/commit は 本文・フッター一切なしの 1行コミット に固定。1行ルールはチーム運用で多く採用される実用設計。

こだわり6: コミット後に PR 説明文フォーマットで出力

コミット → PR 作成までの「書き直し作業」を消す。生成される Markdown はそのまま GitHub の PR 説明欄にペーストできる。

📄 スキルの中身（要点）

スキル本体は GitHub に置いてあるので、全文は commit/SKILL.md を参照してください。ここでは記事中で何度も触れた「設計の核」だけ抜粋しておきます。

絶対ルール（SKILL.md より引用）

スキルの安全性はこの6行に集約されている：

Co-Authored-By: Claude などのフッターは絶対に付けない

git add . / git add -A は使わない — 必ず個別ファイル指定

--no-verify は使わない（フックが失敗したら原因を直す）

git commit --amend は使わない（常に新規コミット）

失敗時に git reset などで自動ロールバックしない — 状況を報告してユーザに判断を仰ぐ

ステージングされていない変更（unstaged / untracked）はコミット対象に含めない — ユーザに質問せず自動的に除外する。コミット対象は git diff --cached で確認できるステージング済み変更のみ

LLM を Git 操作に絡める怖さの大半は、この6行を仕様として固定しておくことで構造的に消える。

実行フローのサマリ

Step	やること
1	`git status` / `git diff --cached` / `git log` で現状把握
2	diff から prefix（`feat` / `fix` / `docs` / ...）と論理的まとまりを判定
3	`AskUserQuestion` でユーザに確認（単一スコープなら1問、複数 prefix 混在なら分割案を提示）
4	クレデンシャル系・開発副産物ファイルを自動除外（除外したものはチャットに明示）
5	`git add <個別ファイル>` → `git commit -m "<prefix>: <日本語サマリ>"` を1行で実行
6	PR 説明文フォーマットの Markdown を出力

各 Step の詳細（フィルタ対象のファイルパターン一覧、PR フォーマットのテンプレ、エラー時の挙動など）は SKILL.md を読んでください。

💡 補足：description 値は GitHub の YAML パーサ対策でシングルクォートで囲んでいます。frontmatter 内に : を含む英文を書くなら同じ対応が必要。

📝 もっと例を見る

ケース1: 単一スコープ（一番多いパターン）

🧑‍💻 ターミナルで git add → Claude Code で /commit

$ git add src/api/user.ts

/commit

🤖 Claude Code の応答

ステージング済み: src/api/user.ts（modified）
スコープ判定: 単一（fix）

提案するコミットメッセージ:
fix: ユーザー取得 API の null 返却バグを修正

🖱️ 表示されるボタン

[ OK ]   [ メッセージ修正 ]   [ キャンセル ]

OK を押すと即コミット完了。所要時間5秒。

ケース2: クレデンシャルが混入

🧑‍💻 うっかり .env も git add してしまった

$ git add .env src/config.ts

/commit

🤖 Claude Code の応答（除外を明示してくれる）

以下は自動除外しました（コミットには含めません）:
- .env

ステージング済み（フィルタ後）: src/config.ts
スコープ判定: 単一（chore）

提案するコミットメッセージ:
chore: 設定ファイルの読み込みパスを変更

🖱️ 表示されるボタン

[ OK ]   [ メッセージ修正 ]   [ キャンセル ]

.env は黙って消えない。 明示してくれるので、意図したダミー追加だった場合は気づける。

ケース3: メッセージを微修正したい

🤖 Claude Code の応答

提案するコミットメッセージ:
refactor: ユーティリティ関数を別ファイルに切り出す

🖱️ 表示されるボタン

[ OK ]   [ メッセージ修正 ]   [ キャンセル ]

メッセージ修正 を選ぶと自由入力に切り替わり、自分で書いたメッセージでコミットできる。主導権は常にユーザ側。

ケース4: ステージング忘れ

🧑‍💻 何も git add せずに /commit を実行

/commit

🤖 Claude Code の応答

ステージング済みの変更がありません。
`git add` でコミット対象をステージングしてください。

untracked / unstaged を勝手に拾ったりしない。「LLM に Git を任せる怖さ」の元凶を最初から塞いでいる。

🎨 カスタマイズのヒント

スキルは Markdown 1ファイルなので、自分の運用に合わせて書き換えやすい。

やりたいこと	編集箇所
prefix を絞る（チームで3種だけ使う等）	Step 2 の prefix 表を編集
issue 番号 `(#123)` を強制	「絶対ルール」に一文追加
英語コミットにする	Step 5 の「日本語サマリ」を「英語サマリ」に変更
`Co-Authored-By` を付ける	「絶対ルール」の禁止行を削除
PR フォーマットを変える	Step 6 のテンプレを書き換え

「LLM のプロンプトエンジニアリング」ではなく「人間が読める仕様書」を書き換えるだけで、挙動が即座に変わる。これがスキル機構の強み。

🎯 まとめ

Before	After
diff を読んで頭で要約	`/commit` と打つだけ
prefix で迷う	自動判定
分割サボる	分割提案が出る
`.env` をうっかり混ぜる	自動除外 + 明示
`Co-Authored-By` がつく	1行コミット固定
PR 説明を書き直し	コピペできる Markdown が出る

毎日コミットするなら時間の節約効果はもちろん、 「履歴の粒度が安定する」「典型的な .env 取りこぼしリスクを下げる」 といった地味だが効く改善が積み重なる（クレデンシャル混入を完全に防げるわけではないので、最終確認は引き続き自分の目で行うのが前提）。

スキルは170行の Markdown 1枚。試すコストは小さいので、興味があれば一度入れて手応えを確かめてみてほしい。合わなければ削除するだけで元通り。

🔗 参考