git-best-practices

Git のベストプラクティス

常に有効な原則

このスキルが読み込まれている間、すべての git 操作で次の指示に従ってください。

1. 操作前に確認する — ブランチを作成、マージ、または PR を開く前にブランチを確認し、リポジトリのデフォルトブランチと本番ブランチを特定します
2. Conventional Commits を使用する — すべてのコミットを type(scope): description 形式にします
3. 明示的にステージする — 意図した変更だけがコミットされるよう、ファイルを指定して追加します
4. 共有履歴を保護する — 強制プッシュには --force-with-lease を使用し、実行前にユーザーへ確認します

エージェントの Git ワークフロー

1. 状態を確認する — git status と git diff HEAD を実行します
2. ブランチを確認する — デフォルト／現在／（任意の）本番ブランチ名を特定します（「ブランチの確認」を参照）
3. 名前を指定してステージする — ファイルごとに git add path/to/file を実行し、git status で確認します
4. Conventional Commit を作成する — type(scope): description 形式にし、必要に応じて本文を追加します
5. 安全にプッシュする — デフォルトでは通常のプッシュを使用します。書き換えた履歴に限り、ユーザーの確認後に git push --force-with-lease origin {branch} を実行します

チェックポイントコミット

エージェントは、長時間のタスク中に WIP チェックポイントコミットを作成し、PR の前に整理できます。

• wip: をプレフィックスとして付けるか、標準の Conventional Commit 形式を使用します
• WIP の状態でも、変更を論理的なまとまりに分けます
• PR を開く前に /rewrite-history を実行し、明確な変更履歴を整えます

コミットの規律

• ファイル名を明示してステージします：git add src/auth.ts src/auth.test.ts
• コミット前に git status でステージ済みの内容を確認します
• シークレット、.env ファイル、認証情報、大容量のバイナリをコミットに含めないでください。ステージ済みのファイルに機密情報が含まれているように見える場合は、ユーザーに警告します
• 最終的な PR 準備済みの状態では、1 つのコミットにつき論理的な変更を 1 つにします

強制プッシュ

アップストリームの変更を上書きしないよう、--force-with-lease のみを使用します。

git push --force-with-lease origin feat/my-branch

ブランチにかかわらず、強制プッシュの前には必ずユーザーに確認してください。

スタックされたブランチのリベース

他のブランチがスタックされているブランチ（フェーズ分けされた NN-description の連鎖など）をリベースする場合は、git rebase --update-refs を使用して、スタックされたブランチが古いコミット上に取り残されず、書き換え後の履歴に追従するようにします。--update-refs が移動するのはローカルの参照のみです。移動したブランチがリモートにも存在する場合は、それぞれのブランチに対して個別に --force-with-lease でプッシュする必要があります（事前に確認してください）。また、別のワークツリーでチェックアウトされているブランチはスキップされます。競合解決と安全な作業手順については、git-rebase-sync スキルを使用してください。

Conventional Commits

形式：type(scope): description

件名のルール：

• 小文字で、命令形にし、末尾にピリオドを付けない
• 72 文字未満
• スコープは任意ですが、明確なサブシステムがある場合は付けるのが望ましいです

一般的なタイプ：

Type	用途
feat	新機能
fix	バグ修正
docs	ドキュメントのみ
refactor	動作を変更しない構造の変更
perf	パフォーマンスの改善
chore	メンテナンス、依存関係、ツール
test	テストの追加または更新
ci	CI/CD パイプラインの変更
build	ビルドシステムの変更
style	書式、空白（ロジックの変更なし）

コミット本文

本文は任意です。変更の意図が本当にわかりにくい場合にのみ追加してください。件名で「何を」を伝え、本文で「なぜ」を説明します。

次の場合は本文を追加します：

• 動機やトレードオフが自明でない
• 複数の変更があり、箇条書きが役立つ
• 外部のコンテキスト（リンク、課題の参照、根本原因）が必要

コミットメッセージの例については、git-examples.md を参照してください。

ブランチの確認

ブランチを作成する前、または PR を開く前に、リポジトリのブランチ構成を確認します。次のコマンドを実行し、結果を保存してください。

# Default branch (PR target for most repos)
gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'

# Current branch
git branch --show-current

# Production branch (if different from default)
git branch -r --list 'origin/main' 'origin/master' 'origin/production'

gh を使用できない場合、またはリポジトリにリモートがない場合は、git-examples.md の代替コマンドを参照してください。

確認したブランチ名を保存し、その後の作業全体で参照してください。以降のすべてのコマンドでは、実際のブランチ名を使用します。

ブランチの命名

まず、リポジトリのブランチ命名規則に従ってください。規則が文書化されていない場合は、次の形式を使用してください。

形式：type/description-TICKET-ID

例：

• feat/add-login-SEND-77
• fix/pool-party-stall-SEN-68
• chore/update-deps
• hotfix/auth-bypass

課題がある場合は、チケット ID を含めてください。チケットがない場合は省略してください。

ブランチフロー

まず、リポジトリのブランチフローポリシーに従ってください。ポリシーが文書化されていない場合は、一般的な基本ルールとして次のとおりです。

{production-branch} (production deploys)
 └── {default-branch} (staging/testnet deploys, PR target)
      ├── feat/add-feature-TICKET
      ├── fix/bug-description-TICKET
      └── hotfix/* (branches off production branch for hotfixes)

• フィーチャーブランチと修正ブランチはデフォルトブランチから作成します
• ホットフィックスブランチは本番ブランチから作成します
• リポジトリが単一ブランチのフローを採用していない限り、PR のマージ先はデフォルトブランチにします
• デフォルトブランチと本番ブランチが同じ場合は、すべての PR をそのブランチに直接マージします

マージ戦略

まず、リポジトリのマージポリシーに従ってください（多くの組織では必須です）。

ポリシーがない場合は、次のデフォルトが妥当です。

PR のマージ先	戦略	理由
フィーチャーブランチ → デフォルトブランチ	スカッシュマージ	履歴を整理し、フィーチャーごとにコミットを 1 つにします
デフォルトブランチ → 本番ブランチ	マージコミット	リリースの区切りを保持し、デプロイポイントを明確にします
ホットフィックスブランチ → 本番ブランチ	スカッシュマージ	本番環境に対する単一の一括修正です

PR ワークフロー

サイズ

恣意的な上限を設けるより、実用性を重視してサイズを決めてください。PR のサイズにかかわらず、各コミットで明確な変更内容を伝えます。PR は一貫した単位としてレビューできる必要があります。レビュー担当者が変更全体を把握しきれない場合は、分割を検討してください。

PR の作成

リポジトリ標準の PR ツール（gh pr create、GitLab CLI、またはウェブ UI）を使用し、次の要件を満たしてください。

• 70 文字未満の短いタイトル
• 1～3 個の箇条書きを含む概要セクション
• 箇条書きのチェックリスト形式のテスト計画

PR 作成前の履歴の書き換え

WIP の履歴が整理されていないブランチでは、/rewrite-history を使用して次の手順を実行してください。

1. ブランチをバックアップします
2. ベースブランチの先端にリセットします
3. 変更を、筋の通ったわかりやすい順序で再コミットします
4. バックアップとバイト単位で完全に一致することを確認します
5. 書き換えた履歴を強制プッシュする前に、ユーザーの確認を得ます
6. バックアップブランチへのリンクを添えて PR を作成します

書き換え後の各コミットでは、前のコミットを土台にしながら、筋の通ったアイデアを 1 つずつ導入します。機能の構築方法を読者に教えるチュートリアルのような流れにしてください。