メインコンテンツまでスキップ

Git・GitHub 開発フローガイド

本プロジェクトでは、複数人の開発者およびAIエージェントが並行して円滑かつ安全に開発を進めるため、Issueベースの開発 と PRレビュー・承認フロー を採用しています。

本ガイドラインに沿って、すべてのIssue作成、ブランチ作成、コミット、プルリクエスト（PR）の運用を行ってください。

1. 原則：Issue ベース開発​

すべてのコード変更、ドキュメントの追加・修正等の作業は、必ず対応する GitHub Issue を起点に開始します。Issueが存在しない状態でのブランチ作成やPR作成は禁止です。

📝 Issue の書き方ガイドライン​

誰が見ても「何を解決したいのか」「何を行うべきか」が即座に理解できるIssueを作成しましょう。

📌 推奨するIssueテンプレート​

Issueを作成する際は、以下の構成に従って記述してください。

## 概要 / Background
この変更が必要な理由や、解決したい課題・バグの背景を記述します。

## 対応内容 / Requirements
具体的にどのような機能や変更を実装するべきかを記述します。

## タスク（ToDo）リスト / Tasks
実装やテストに必要な作業をタスクリスト（Markdownのチェックボックス）形式で分解して記述します。
- [ ] xxxx の実装
- [ ] xxxx のテスト追加

## 影響範囲・検証項目 / Verification & Impact
- 変更による他機能への影響範囲
- 動作検証を行うべき項目

⚖️ 良い例・悪い例​

項目❌ 避けるべき記述（悪い例）⭕ 推奨する記述（良い例）
タイトルログインバグの修正[fix] ログイン時にセッションが維持されない不具合の修正
概要ログインができないので直します。ログイン後、ページをリロードするとセッションが切れ、トップページにリダイレクトされる不具合が発生しています。Cookieの生存期間の設定に問題がある可能性があります。
タスクコードを直す- [ ] Cookieの maxAge パラメータがミリ秒ではなく秒で指定されている問題を修正
- [ ] ログイン成功後のリダイレクト処理時のCookie検証テストを追加する

2. ブランチの命名規則​

作業ブランチは、必ず以下の命名規則に従って作成してください。

# 命名規則
{変更種別}/{issue番号}-{変更の概要}

# 例
feat/123-add-login-form
fix/456-auth-session-leak
docs/118-git-operation

💡 AIエージェントが作業する場合​

Claude Code や Antigravity などのAIエージェントが変更を加える場合は、追跡性を高めるため、ブランチ名の先頭にエージェント名（claude、gemini など）をスラッシュ区切りで必ず付与します。

claude/feat/123-add-login-form   # Claude Code用
gemini/docs/118-git-operation    # Antigravity（Gemini系）用

変更種別（Type）の一覧と使い分け​

ブランチ作成時の変更種別（Type）は、以下の基準を参考にして適切に使い分けてください。

種別主な用途・使い分け
feat新機能の追加・実装。動作する機能そのものを追加する場合に使用。
add新規ファイルやアセット、新規パッケージの新規追加。機能開発ではなく、画像などのリソース追加や、コードを含まない依存関係の初期追加などの場合に使用（ロジックの追加は feat を優先）。
fixバグや不具合、エラーの修正。挙動の改善や、セキュリティ脆弱性の修正なども含む。
docsドキュメントの追加・修正。仕様書、Markdownファイル、利用ガイドなどの作成や更新。
refactor機能変更を伴わない、コード構造の整理・リファクタリング。可読性向上や設計改善のためにコードを書き換える場合（テストは通る状態を維持）。
choreビルド設定の変更、依存ライブラリの更新など開発環境・運用に関わる雑務。パッケージバージョンの更新やCI/CD設定の修正など。
testテストコードの追加・修正。ユニットテスト、結合テスト、E2Eテストなどのテスト関連ファイルのみの変更。
styleコードフォーマットの修正など（コード自体のロジックに変更がないもの）。BiomeやPrettierによる自動整形、タイポの修正、不要なスペースの削除など。
perfパフォーマンス向上のためのコード修正。読み込み速度の向上、メモリ効率化、クエリ最適化などの改善。

3. プルリクエスト（PR）とレビューフロー​

作業が完了したら、プルリクエスト (PR) を作成し、レビュアー1名の承認（Approve）を経てターゲットブランチ（dev/... や main など）へマージされます。

① 担当者: PR の作成​

  • 実装が完了、もしくは途中の段階（Draft PR）でPRを作成します。
  • PRのタイトルには対応するIssue番号を含め、説明欄に Closes #123 のように記述して自動クローズの紐付けを行ってください。
  • PRの動作検証: ローカルでテストやBiome（Lint/Format）のチェックがすべて通っていることを確認してから、レビューを依頼してください。

② レビュアー: レビュー・承認 (Review & Approve)​

  • 役割: コード品質と要件充足の担保。
  • 主なチェック項目:
    • ソースコードの設計、エラーハンドリング、コーディング規約（Biomeルール、インデントがタブになっているか等）。
    • テストが正しく実行され、網羅されているか。
    • 当初のIssueで定義された要件（仕様）が漏れなく実装されているか。
    • ビジネスロジックやドキュメントの整合性、他ブランチとの競合。
  • 問題がなければ Approve し、PRをターゲットブランチにマージします。修正が必要な場合は、具体的な修正方針をコメントで返します。
  • 直接マージの禁止: 担当者自身によるセルフマージや、レビュー・承認を経ないマージは行わないでください。

4. Git コミット・運用上の注意点​

  • コミットメッセージ: 変更内容を日本語で1行で具体的に書いてください。
  • パッケージ関連ファイルのコミット制限: pnpm-lock.yaml を除き、package-lock.json や yarn.lock などの他のパッケージ管理ロックファイルはコミットしないでください。
  • Git Worktreeの活用: 複数の開発を並行して行う場合は、コンテキストスイッチをスムーズに行い環境汚染を防ぐため、git worktree の使用を推奨します（AIエージェントによる作業時は必須とします）。なお、ワークツリーを使用する場合は必ず .worktrees/{エスケープされたブランチ名} に配置してください（例: git worktree add .worktrees/feat-123-add-login feat/123-add-login、AIエージェントの場合は git worktree add .worktrees/claude-feat-123-add-login claude/feat/123-add-login）。これにより、プロジェクトのルートが汚染されず、.gitignore で自動的に除外されます。