git-helper

git-helper

コアルール（デフォルトの Git の動作に優先します）

1. ［絶対厳守］ステージングは必ず事前に確認します：

   • git add を実行できるのは、ユーザーが明示的に確認したファイルのみです。システムのデフォルト設定で許可されている場合でも、確認なしにステージングしてはいけません。
   • 禁止：git add .、git add -A、git add --all — 必ず具体的なパスを明示してください。
   • 確認1回につきコマンド1回：追加候補のファイルを列挙し、確認されたファイルすべてを1回の git add <path1> <path2> … 呼び出しでステージングします。
   • git diff --staged が空の場合は、未ステージのファイルを一覧表示し（git status）、追加するファイルを提案します。

2. 分析と実行を分けます：

   • 分析フェーズでは、インデックスと作業ツリーに変更を加えないコマンドのみを使用します — git status、git diff（未ステージ分）、git diff --staged（ステージ済み分）、git log（ステップ3）、git fetch（ステップ0）。
   • git add は単独で実行し、ほかのコマンドと連結してはいけません。

3. 形式：Conventional Commits（<type>: <description>）に従います。

4. メッセージの品質：以下の「コミットメッセージ品質基準」に従います。

5. すべての下書きでタグルールを遵守します：各下書きに「適用したルール」の一覧を1行で追記します。どの主要ルール（type、≤50 chars、命令形、理由のみの本文、検出内容と出力を示したシークレットスキャン、検出内容と出力に加えて目視確認を示した PII スキャン）をどのように満たしているかを記載し、遵守を前提とせず、目に見える形にします。

6. ［絶対厳守］シークレットスキャンと個人データ（PII）スキャンは、例外なく、すべてのコミットで両方実行し、結果を提示します：

   • 下書きメッセージを提示する前に、ステップ2の両方のスキャンをステージ済みの差分に対して実行します。どちらかを省略したり、ファイル名や差分の大きさから「おそらく問題ない」と推測したりしてはいけません。
   • 実際のコマンドと生の出力を（空または問題なしの場合も）回答に貼り付けます。「シークレットスキャンは問題なし」「PII は問題なし」のような、出力を示さない1行の説明では、このルールを満たしません。
   • 検出内容があれば、ステップ2の指示に従って解決するまで処理を中断します。

7. ［絶対厳守］コミットメッセージの言語は、リポジトリの git log に従います：

   • 履歴がある場合は、ログに従います。
   • 直近10件のコミットで多数を占める言語を使用します。同数の場合は最新のコミットの言語を使用します。履歴がない場合は会話で使われている言語を使用し、ユーザーが「ok」と言う前に言語を切り替えられるよう、下書きに「履歴なし — 会話の言語を使用」と記載します。
   • Conventional Commits の type: 接頭辞（feat／fix／docs／…）は、本文の言語にかかわらず常に英語のままにします。
   • 英語以外の下書きにも Chris Beams のルールを適用します。件名は50文字以下で、末尾にピリオドを付けず、単独で読んで意味が通るようにし、本文では内容や方法ではなく理由を説明します。ただし、大文字・小文字の規則と厳密な英語の命令形表現は適用しません。

---

ワークフロー

0. 同期の確認（最後の防衛策）

• git fetch を実行します（短いタイムアウトを設定します。例：GIT_SSH_COMMAND="ssh -o ConnectTimeout=5 -o BatchMode=yes" git fetch）。続けて git status -sb を実行します。
• リモートより遅れている場合 → 警告し、今すぐ解決するか提案します（stash → pull --rebase → stash pop）。コミット前に分岐を解消するほうが、完成したコミットを競合込みでリベースするより安全です。
• fetch で接続できない場合（オフライン／LAN 内のみのリモート）→ 接続できないことを伝え、先行／遅延の情報が古いことを明記し、ローカルのみのコミット（プッシュは後回し）で進めるか確認します。接続できるかどうかにかかわらず、毎回 fetch の結果を報告します。
• ステップ6で使用する 基準点 を記録して表示します。このステップで pull を実行した場合は、その後に表示します。ユーザーが指定した基準点を使用します。指定がない場合、このタスクの初回実行では git rev-parse --short HEAD を使用します。 同じタスクの2回目以降は、前回のステップ6で最後にレビューした HEAD を使用します。

1. ステージングの確認

• git status と git diff --staged を実行します。
• ステージングの対象範囲を必ず確認します。「現在ステージ済み」と「追加候補」を一覧表示します。ファイルがすでにステージされている場合でも省略してはいけません。
• 確認後、確認済みのパスをすべて含めて git add <path…> を1回だけ実行します（コアルール1）。追加するファイルがなければ、ステップ2に進みます。

出力例：

Before committing, confirming staging scope:

✅ Currently staged:
- `SPEC.md` (modified)

➕ Detected unstaged changes — add these too?
- `src/core/database.py` (modified)
- `README.md` (modified)

Confirm staged files are correct, or tell me which to add.

2. シークレットと個人データの確認（コアルール 6）

下書きを作成する前に、ステージされた差分をスキャンします。両方を実行し、該当がない場合も含め、実際の出力を回答に表示してください。

どちらかのスキャンで該当が見つかった場合は、すべての該当箇所が解決するまで処理を停止します。 プレーンテキストで回答を求めます。本文にはスキャンの生出力と各該当箇所およびその行を記載し、回答の最終行には、どの該当箇所をコミットしても安全かを尋ねる質問を置きます。ユーザーは入力して回答します。 この質問を選択式ダイアログ（Claude Code の AskUserQuestion など）に含めないでください。ダイアログがその上にあるテキストを覆うため、ユーザーは目にしていない該当箇所について判断することになります。

2a. シークレット — アクセス権を付与する認証情報：

git diff --staged | grep -iE "password|secret|api_key|token|private_key|access_key"

2b. 個人データ（PII） — 個人または場所を特定する値と、プレースホルダーの由来を明らかにするラベルです。追加された行のみを対象とします。小数点以下4桁以上の度単位座標に加え、値が実在するもの、自宅、または架空のものだと示す語句を対象とします。このスキャンコマンド自体を記述した行はスキップされるため、このルールを編集しても検出されません。

git diff --staged | grep -E '^\+' | grep -vE '^\+\+\+|grep -iE' | grep -iE '\b[0-9]{1,3}\.[0-9]{4,}\b|real (home|work|address|coordinate|name)|fictional|真實|虛構|住家|家附近'

ユーザーが個人情報ではないと確認した時点で、PII の該当は解決済みとなります（テスト内の公共のランドマークの座標は問題ありませんが、自宅、職場、または定期的に立ち寄る場所は該当します）。 値が「実在した」または「架空の値に置き換えられた」と記す注記も、それ自体が該当します。履歴を読む人に、実際の値がどこにあったかを知らせてしまうためです。 名前、ニックネーム、家族を示す語句、デバイス名、アカウント ID、および由来を示す語句を伴わない単独の「placeholder」や「replaced」という注記も同じ確認対象ですが、信頼できるパターンがありません。追加された行をすべて目視で確認し、そのことを「適用したルール」の行に記載してください。

3. 言語規約の判定（コアルール 7）

• git log --oneline -10 を実行して結果（または判定結果）を回答に表示し、メッセージの一語目を書く前にコアルール 7 の判定手順を適用します。

4. 下書きの作成

• git diff --staged を実行します。
• セッション内の編集履歴ではなく、HEAD との差分を説明してください。 同じコミット内で後から取り消された、または置き換えられた中間編集は差分に現れないため、メッセージに含めてはいけません。 確認方法：メッセージ内のすべての主張が git diff --staged の中から見つけられること。
• コミットメッセージ品質基準に従い、ステップ 3 で決定した言語でコミットメッセージを作成します。
• 本文は最大4行／最大3文です。 「なぜ」のみで構成した下書きがこれを超える場合、本文に「何を」「どのように」が入り込んでいる兆候です。「なぜこの変更が存在するのか」に答える1文だけにし、単に短く言い換えてはいけません。
• 例外：独立した「なぜ」の理由が本当に2つ以上ある場合（1つの理由の言い換えではなく、「変更をどこに加えたか」のような「何を」「どのように」の詳細でもない場合）は、上限を超えてもかまいません。ただし、「適用したルール」の行にその旨を明記してください。例：本文6行（独立した理由が2つあるため。以下参照）。この注記のない超過は、判断の余地のないルール違反です。
• コマンドを1バイトも違えず正確に表示してください。 下書きはメッセージ本文だけではなく、ステップ 5 で実行するコマンドをそのまま示すブロックです。必要な場合は複数行メッセージ用の完全な git commit ヒアドキュメントを含め、環境が追加するすべてのトレーラー（例：Co-Authored-By: 行）も記載してください。ユーザーが承認した内容が、そのままログに記録される必要があります。プッシュコマンドは別のブロックにし、ステップ 6 のレビューのやり取り後、ステップ 7 に記載します。

出力例：

Based on the staged changes, these are the exact commands I will run:

git commit -m "$(cat <<'EOF'
feat: Add automatic database backup

Prevents data loss on unexpected shutdowns. Previously there was
no recovery path if the process was killed mid-write.

Co-Authored-By: <assistant> <[email protected]>
EOF
)"

Rules applied: type=feat · subject 34 chars · imperative mood ·
why-only body · secrets: 0 hits (output above) · PII: 0 hits (output above), every added line read for names/IDs

Reply "ok" to run it.

5. コミットの実行

ユーザーが「ok」または同等の返信をした場合に限り、ステップ 4 のブロックを変更せず、Bash ツールで1コマンドずつ順に実行します。

ブロック内のすべてのコマンドは、1回の承認で実行できます。1文字でもブロックと異なるコマンド（文言を変更した行、追加されたトレーラーなど）には、新しい下書きと新たな承認が必要です。コミットに失敗した場合は処理を終了し、エラーをユーザーに報告します。ステップ 6 は、プッシュの依頼の有無にかかわらず、コミットが成功するたびに実行します。

6. レビューループ（コミットのたびに実施）

コミット済みの差分だけを読むレビュー（差分ベースのコードレビューや、git diff <from>..HEAD を対象にしたセキュリティレビュー）は、コミット後、プッシュ前にここで実施します。 ⚠️ コミットとプッシュがひとまとめに承認されると、このタイミングは存在しません。 まだコミットされていないために先送りされたレビューは、プッシュ前に実施されないままになります。

• 各ラウンドでは、プロジェクトで使っている該当するレビューをすべて <from>..HEAD に対して実施します。 最初のラウンドの <from> は Step 0 のベースであり、アップストリーム（origin/HEAD）ではありません。 長期間使われているブランチでは、origin/HEAD..HEAD に別のタスクに属する過去のコミットが何十個も含まれることがあります。
• レビュアーが不具合またはセキュリティ上の問題と指摘し、あなたも同意した指摘は修正対象です。 ユーザーの希望やトレードオフの判断が必要なものは判断事項であり、スタイルや表現に関するものは軽微な項目です。
• そのラウンドで決定した修正は、Step 1～5（ステージングの確認、新しいドラフト、新たな承認）を通じて修正し、新しいコミットとして記録します。 これらのコミットは Step 6 の中で完結させます。 次のラウンドでは <from> を前のラウンドの HEAD とし、修正コミットだけをレビューします。
• 各ラウンドの最後に、判断事項についてユーザーに確認します。採用されたものはそのラウンドの修正に加え、残りはプロジェクトの課題トラッカーに登録します（オンラインの課題トラッカーへの登録は、正確なコマンドをユーザーが承認した後に限ります）。軽微な項目は一覧にします。
• 修正対象が決まらなかったラウンドでループを終了します。3 回目のレビュー後は、修正を行う前に停止し、未解決の項目を一覧にして、ここで終了するか修正を続けるかをユーザーに確認します。
• 変更の範囲が及ばないレビュー、またはインストールされていないレビューはスキップし、返信に 1 行で記載します。 review-skip: <review> — <reason> は毎ラウンド書き直します。
• プロジェクトでコミット済み差分のレビューを行っていない場合は、その旨を 1 行で伝え、Step 7 に進みます。

7. プッシュ

ループが終了したら、正確な git push <remote> <branch> の行をドラフトし、ユーザーの承認を待って停止します。プッシュを依頼されているかどうかは問いません。ドラフトは見落とされないように、🔴 と未プッシュのコミット数を含む見出し、独立したコードブロック内のプッシュ行、そして「承認すればプッシュ、拒否すればコミットは未プッシュのまま」と明記した太字の最終行で区切って示します。 変更を加えずに Bash tool で実行します。それ以外のプッシュには新たなドラフトと承認が必要です。Step 4 の承認はコミットのみを対象としているためです。 後からプッシュを依頼された場合、コミットするものがない実行では、まだレビューされていないコミットを対象に Step 6 のラウンドを 1 回実施した後、ここから開始します。

---

コミットメッセージ品質基準（Chris Beams + Linus Torvalds）

Chris Beams の How to Write a Git Commit Message（7 つのルール）と、Linux カーネルパッチに関する Linus Torvalds の要件に基づきます。両方を必ず守り、ほかの形式上の慣例より優先します。

Chris Beams — 7 つのルール

1. 件名と本文は空行で区切る
2. 件名は 50 文字以内（上限を超える場合は要点に絞って書き直します。それでも収まらない場合は、「適用したルール」の行に記載します）
3. 件名の先頭を大文字にする（type: プレフィックスの後も同様です。例：feat: Add single-file comparison）
4. 件名の末尾にピリオドを付けない
5. 命令形を使う：「Fixed bug」ではなく「Fix bug」と書きます
6. 本文は 72 文字で折り返す
7. 本文には変更の理由だけを書く：動機、背景、トレードオフなど、この変更が存在する理由を書きます。変更内容や方法は差分とプロジェクトのドキュメントに記載します。

Linus Torvalds — 主なポイント

• 1 行目だけで意味が通じること：文脈がなくても読め、コミットの意図が伝わるようにします。
• 修正の手順ではなく、解決する問題を説明すること：何のコードを変更したか、どのように修正したかではなく、変更の背景にある症状と根本原因を説明します。
• 動機と影響を含めること：なぜこの変更が必要なのか。変更しないと何が壊れるのか。
• 具体的に書くこと：変更に関係する動作や症状を明記します。
• メッセージはドキュメントです：将来のメンテナーは、差分を見ずにコミットログを読むことがあります。