commit-work

commit-workスキルの概要

commit-workスキルは、散らかった working tree をレビューしやすい Git コミットへ整理することに特化したワークフローです。特に、つい雑になりがちな「変更内容の確認」「無関係な編集の切り分け」「必要な hunk だけのステージング」「何を変え、なぜ変えたかが伝わる明確な Conventional Commit メッセージ作成」を支援したい開発者に向いています。

commit-workが想定している役割

commit-workは汎用的な Git チュートリアルではありません。役割は、日常的な開発作業でエージェントがより安全で整理されたコミットを作れるようにすることです。中心にあるのは、次の4つの成果です。

• 意図した変更だけを含める
• 無関係な作業を別コミットに分ける
• コミット前に、ステージ済み diff を正確に確認する
• 実用的な Conventional Commit メッセージを書く

そのため、1つのブランチに複数種類の編集が混在しているとき、ファイルの一部だけ変更しているとき、フォーマット変更のノイズが多いとき、テスト更新が含まれているとき、あるいはまだコミットメッセージに自信がないときに特に有効です。

commit-workスキルを導入すると相性がいい人

commit-work skillが最も合うのは、すでに Git を使っているものの、コミット品質をもっと安定させたい人です。特に次のようなケースで役立ちます。

• 大規模または変化の速いリポジトリで作業する開発者
• Conventional Commits を必須にしているチーム
• つい「大きな1コミット」にまとめがちな人で、より適切なコミット境界を作りたい人
• AI支援コーディングでコード生成が速く、そのぶんコミット前の丁寧な確認が必要なワークフロー

一方で、主に必要なのがブランチ戦略、マージコンフリクト解消、リリース自動化であれば、このスキルの守備範囲は狭すぎます。

commit-workが単なる「コミットを書いて」プロンプトより優れている理由

一般的なプロンプトは、すぐコミットメッセージ作成に飛びがちです。commit-workは、その前段にある重要な工程を補います。つまり、確認し、境界を決め、patch staging し、ステージ済み diff を見直してから、メッセージを書く流れです。重要なのは、コミットで起きる大きな失敗の多くは文面ではなく、ステージングの誤りだからです。

差別化ポイントは、派手な自動化ではなくワークフローの規律にあります。

commit-work導入前に最も重要な判断ポイント

多くの人にとって、導入判断はシンプルです。「これで本当に悪いコミットが減るのか」。次のような痛みがあるなら、答えは yes です。

• 無関係な変更がひとまとめになってしまう
• デバッグコードや secrets がうっかり混ざる
• コミットメッセージが曖昧になりやすい
• どのタイミングで複数コミットに分けるべきか迷う

逆に、常に変更がごく小さく、最初からきれいに分離されているリポジトリなら、このスキルの価値は下がります。

commit-workスキルの使い方

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

AIクライアントが GitHub-hosted skills をサポートしているなら、softaworks/agent-toolkit から commit-work をインストールできます。よくあるインストール例は次のとおりです。

npx skills add softaworks/agent-toolkit --skill commit-work

実行環境がスキルの直接インストールに対応していない場合は、次のソースファイルを読み、そこに書かれたワークフローを手動でなぞってください。

• skills/commit-work/SKILL.md
• skills/commit-work/README.md
• skills/commit-work/references/commit-message-template.md

commit-workスキルを使う前に先に読むべきファイル

素早く評価したいなら、読む順番は次が最適です。

1. SKILL.md — 実際の運用チェックリスト
2. references/commit-message-template.md — 期待されるメッセージ形式
3. README.md — より広い位置づけとトリガー例

この順に読むと、リポジトリ全体を眺めるより早く、実際の使い方がつかめます。

commit-workに渡すと効果が高い入力情報

commit-work usageが最も力を発揮するのは、最初にいくつか意思決定を渡したときです。

• 1コミットにしたいのか、複数コミットにしたいのか
• Conventional Commits が必須かどうか
• subject の最大文字数や必須 scope など、チーム固有のルール
• エージェントに stage と commit まで許可するのか、commands/messages の提案だけにするのか

分割方針を指定しない場合、このスキルは無関係な変更があるとき、複数の小さめなコミットへ分ける方向に妥当に寄せます。

commit-workが実際にたどるワークフロー

このスキルのワークフローはシンプルで堅実です。

1. git status と git diff で working tree を確認する
2. コミット境界を決める
3. 次の論理単位のコミットに必要な変更だけを stage する。理想は git add -p
4. git diff --cached でステージ済み変更を確認する
5. 何が変わったか、なぜ変えたかを要約する
6. Conventional Commit メッセージを書く
7. 関連する checks を実行する
8. tree が clean になるまで繰り返す

これが、commit-work for Git Workflowsが有用な理由です。コミット内容そのものだけでなく、コミットの衛生状態まで改善できます。

曖昧な依頼を強いcommit-workプロンプトに変える方法

弱いプロンプト:

• “Commit my changes.”

強いプロンプト:

• “Use commit-work. Inspect the current diff, split unrelated changes into separate commits, use Conventional Commits with scope api, and show me the proposed commit boundaries before committing.”

さらに強いプロンプト:

• “Use commit-work on the current branch. I expect at least two commits if tests and production code changed separately. Use Conventional Commits, keep subjects under 72 chars, and flag any debug code, secrets, or formatting-only churn before staging.”

違いは、後者が最終アクションだけでなく、判断基準までスキルに渡していることです。

1コミットにするべき場面と複数コミットに分けるべき場面

diff が単一の目的に沿っており、レビュアーも1つの変更として理解すべきなら、1コミットを依頼します。次のようなパターンが見えたら、複数コミットを依頼するべきです。

• リファクタリングと挙動変更が混在している
• テスト更新と本番コードの編集が混ざっている
• 依存関係の更新とコード変更が一緒になっている
• フォーマット変更のノイズとロジック変更が混在している
• フロントエンドとバックエンドの変更が独立してレビューできる

これは commit-work guide の中でも特に価値の高いポイントです。

commit-work運用でpatch stagingが中核になる理由

このスキルが patch staging を強く推すのは、複数の意図が1ファイルに混ざる状況が珍しくないからです。git add -p を使えば、エージェントでもユーザーでも、次のコミットに属する hunk だけを stage できます。これはメッセージの洗練より重要です。範囲設定を誤ったコミットは、メッセージが完璧でも良いコミットにはなりません。

スキル内で触れられている復旧用 commands も有用です。

• git restore --staged -p
• git restore --staged <path>

commit-workがコミットメッセージをどう扱うか

このリポジトリには、シンプルなメッセージテンプレートが含まれています。

• Conventional Commits 形式の header
• 何を変えたかを短く説明する body
• なぜ変えたかを短く説明する body

構造として良い結果は、次の形になります。

<type>(<scope>): <summary>

その後に続く body では、実装の細かな話ではなく、挙動と意図を説明します。また、breaking change は ! または BREAKING CHANGE: footer で扱うことにも触れています。

commit-workでコミット確定前に走らせるべきチェック

実際にコミットする前に、ステージ済み diff を確認し、少なくとも次を sanity-check してください。

• secrets や tokens
• 意図しない debug logging
• 無関係な formatting churn
• 変更に対して必要なテスト不足、または relevant checks の失敗

ここは導入時の重要ポイントです。commit-work installが本当に効いてくるのは、最後の一歩を少しだけ丁寧にして、ミスを拾えるようにした場合だけです。

エージェントと組み合わせるときの実践的なcommit-work運用

実務では、次の流れが使いやすいです。

1. まずエージェントに確認と境界案の提示を依頼する
2. 分割案を承認するか、必要なら修正する
3. 各コミットごとにコミットメッセージ案を作らせる
4. ステージ済みコミットごとに git diff --cached を確認する
5. そのまま commit させるか、最終 commands を自分でコピーして実行する

この human-in-the-loop のやり方なら、時間を節約しつつ、出力品質を高く保ちやすくなります。

commit-workスキルのFAQ

commit-workスキルは初心者にも向いていますか？

はい。ただし、staging や commit といった基本的な Git 概念をすでに理解している場合に向いています。commit-work skillは、再現しやすいチェックリストと適切な command 選択を提供しますが、Git 全体をゼロから教えるものではありません。

commit-workではConventional Commitsが必須ですか？

ソース上では、デフォルトで Conventional Commits を前提に扱っています。チームが別の標準を使っているなら、スキル呼び出し時に明示してください。指定しなければ、Conventional Commit 形式の出力を想定してよいです。

commit-workは本当に作業を複数コミットに分けられますか？

はい。そこがこのスキルの主目的の1つです。境界を判断し、選択的に stage し、working tree が clean になるまでその流れを繰り返すよう、明示的に設計されています。

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

次のような場合は commit-work を使わないほうがよいです。

• コミットではなく、branching や rebasing の支援が欲しい
• 変更がごく小さく、すでにきれいに分離されている
• 実行環境の都合で、エージェントが diff の確認や選択的ステージングをできない
• チームのコミットプロセスが、スキルの守備範囲を超えるほど強くカスタマイズされている

こうしたケースでは、直接 Git commands を並べて実行したほうが速いことがあります。

commit-workはコミットメッセージだけ頼む場合と何が違いますか？

コミットメッセージだけを頼むプロンプトは、「ステージ済みの中身はすでに正しい」という前提に立っています。commit-work usageはもっと前から始まります。working tree を確認し、境界を決め、メッセージを書く前にステージ済み diff を見直します。

レビュー基準が厳しいチームでもcommit-workは有用ですか？

はい。特に、レビュアーが小さく論理的なコミット、読みやすい履歴、意図が伝わるメッセージを重視するチームで効果を発揮します。そうした環境ほど、このワークフローの規律が価値になります。

commit-workスキルを改善する方法

先に制約を渡すとcommit-workの精度が上がる

commit-workの結果を最も手早く改善する方法は、制約を早めに渡すことです。

• 望ましい commit scopes
• subject の文字数制限
• テストを別コミットにすべきか
• formatting-only edits を必ず分離すべきか
• エージェントに commit まで許可するか、提案だけにするか

これらがなくてもスキルは動きますが、境界判断がチームの流儀とずれる可能性は高まります。

ステージング前にコミット境界案を出させる

強いプロンプトの型は次のとおりです。

• “Use commit-work to inspect the diff and propose commit boundaries first. Do not stage yet.”

これにより、最大の品質問題を早い段階で拾えます。いったんステージングが始まると、人は不適切な分割を見直しにくくなります。

メッセージ品質が上がるリポジトリ文脈を渡す

エージェントが機能領域や変更意図を把握していると、commit body の質はかなり上がります。特に有用なのは次の情報です。

• ticket や issue の目的
• その変更が bug fix なのか、リスク低減なのか、機能追加のためなのか
• ユーザーに見える影響
• breaking behavior の有無

これにより、単にどのファイルが変わったかではなく、「なぜこの変更が存在するのか」を説明しやすくなります。

よくある失敗パターンを警戒する

commit-workでも崩れやすい典型例は次のとおりです。

• 関連して見えるが、実際には別々にレビューできる変更をまとめてしまう
• formatting noise をロジック変更に混ぜて stage してしまう
• Conventional Commit header は正しいが、body が弱い
• メッセージが良さそうに見えるせいで、ステージ済み diff の確認を省いてしまう

これらが見えたら、境界を決める段階からワークフローをやり直してください。

プロンプトを強化してcommit-workの出力を改善する

次のように言う代わりに:

• “Use commit-work and commit this.”

次のように依頼します。

• “Use commit-work. Inspect unstaged and staged diffs, isolate formatting-only edits into their own commit if present, use scope ui, and show the final staged diff and message for approval before commit.”

このプロンプトなら、安全性もレビュアーの見やすさも両方改善しやすくなります。

初稿を丸ごと受け入れず、1回目の提案から詰める

有効な follow-up request の例は次のとおりです。

• “Split commit 1 into refactor and behavior change.”
• “Rewrite the subject to be more specific about the user-visible effect.”
• “Remove implementation details from the body and focus on intent.”
• “Check whether test updates should be committed separately.”

これが commit-work for Git Workflows を改善するうえで最も効果の高い使い方です。最初の出力は完成品ではなく、提案として扱ってください。