現場１週間未満エンジニアがgit-workflowについてドキュメントを作ってみたよー

はじめに

• 現場に入ってgitの運用について苦労したのでよりよい運用方法を考えてドキュメントを作ってみました
• そのままプロジェクトのgit運用のドキュメントととして使用することできるかも！？
• 現場でgitの運用についてドキュメントがない方や、ドキュメントはあるけど分かりにくいという方には是非使って頂きたい。使って後悔はさせません
• 未経験者がつまずくポイントもピックアップしてわかりやすく記載しましたので、未経験者の教育にも役立つかも（教育コストダウン）

Git ワークフロー・ブランチ戦略

⚠️ 重要な注意事項

絶対にやってはいけないこと:

git push origin main  # 🚫 絶対禁止！本番環境に直接プッシュしてはいけません

mainブランチは本番環境と直結しています。直接プッシュすると本番サイトが予期せず更新され、バグやサービス停止の原因となります。必ずプルリクエスト（PR）を通してレビューを受けてからマージしてください。

Git とは？（完全初心者向け）

Git（ギット）は「バージョン管理システム」です。プロジェクトのファイルの変更履歴を記録し、複数人で安全に開発作業を行うためのツールです。

Git の基本概念

• リポジトリ（Repository）: プロジェクト全体とその履歴を保存する場所
• コミット（Commit）: ファイルの変更を記録すること
• ブランチ（Branch）: 開発の流れを分岐させること（並行作業を可能にする）
• マージ（Merge）: 分岐した開発を統合すること
• プルリクエスト（PR）: 変更をメインの開発ラインに取り込んでもらうための依頼

ブランチ戦略

ブランチ構成

• main: 本番環境（ユーザーが実際に使うサイト）
• develop: ステージング環境（本番前のテスト環境）
• feature/*: 機能開発ブランチ（個人の作業スペース）

mainとdevelopはマージするとAmplifyに自動でデプロイされます。

PR（プルリクエスト）ルール

基本ルール

• PRの粒度は細かくする:基本１機能修正1PRを作成。あまりに大きすぎるPRは分割を依頼する可能性あり
• 優先度が高いPR: PR提出時にSlackやチャットでその旨を連絡する
• レビュー待ちPRが5件になった場合: レビューされる人が、レビュー時間を設けてもらうように連絡を入れる
• すべてのPRは人間のレビュー必須: 自動PRも含めて必ず誰かがレビューしてから本番リリース

PR作成時の必須項目

PR概要テンプレート

## 概要
<!-- 何を変更したのか簡潔に説明 -->
例：ユーザー登録機能を追加

## 変更点の詳細
<!-- 具体的にどのファイルを変更したか、どんなコードを追加したか -->
例：
- components/Auth/SignUp.tsx を新規作成
- ユーザー登録フォームのバリデーション機能を実装
- Firebase Authenticationとの連携を追加

## 動作確認方法
<!-- レビュアーがテストできるよう、手順を具体的に記載 -->
例：
1. ログイン画面で「新規登録」ボタンをクリック
2. メールアドレスとパスワードを入力
3. 「登録」ボタンをクリック
4. 確認メールが送信されることを確認

## レビュー時の注意点
<!-- 特に見てほしいポイント、心配な箇所があれば記載 -->
例：
- バリデーションロジックが適切か確認してください
- セキュリティ面で問題がないか確認してください

## チェックリスト
- [ ] ローカルテスト完了
- [ ] ステージング環境での動作確認完了
- [ ] スクリーンショット添付（該当する場合）
- [ ] テストコード追加・更新（該当する場合）
- [ ] ドキュメント更新（該当する場合）

開発フローの詳細解説

1. ブランチ作成

# まず最新のmainブランチを取得
git switch main
git pull origin main　(ローカルがmainブランチであれば`git pull`でOK)

# 新しいfeatureブランチを作成（your-feature-nameは作業内容に応じて変更）
git switch -c feature/your-feature-name

ブランチ名の例:

• feature/user-login （ユーザーログイン機能）
• feature/course-search （コース検索機能）
• feature/bug-fix-header （ヘッダーのバグ修正）

2. 機能開発

feature/* ブランチで作業を開始します。

# 現在のブランチを確認
git branch
# * feature/your-feature-name と表示されていればOK

# ファイルを編集・作成後、変更を確認（作業終了時）
git status

# 変更をステージングに追加
git add .
# または特定のファイルのみ
git add src/components/NewComponent.tsx

# コミット（変更を記録）
git commit -m "ユーザーログイン機能を追加"

3. ローカルテストの実行

ステージング環境に送る前に、必ずローカルでテストを実行してください。

# ビルドテスト（エラーがないかチェック）
npm run build:student

# 自動テストの実行
npm run test

# コードフォーマットの修正
npm run prettier

各コマンドの説明:

• build:student: プロジェクトがエラーなくビルドできるかチェック
• test: 書かれたテストが全て通るかチェック
• prettier: コードの見た目を整える（インデントやスペースなど）

4. ステージング環境での確認

ローカルテストが全て通ったら、ステージング環境にデプロイして確認します。

# 最新のdevelopブランチを取得
git switch develop
git pull origin develop

# 自分のfeatureブランチをdevelopにマージ
git merge feature/your-feature-name

# ステージング環境にデプロイ
git push origin develop

マージとは:
自分が作った変更を、他のブランチ（この場合はdevelop）に統合することです。

5. 動作確認

ステージング環境のURLにアクセスして、自分が実装した機能が正しく動作するか確認します。

• ステージング環境で開発者自身が動作確認
• 正常動作のスクリーンショットを撮影（推奨）
• できれば異なるブラウザでもテスト（Chrome、Safari、Firefoxなど）

6. プルリクエスト作成

動作確認が完了したら、本番環境への反映依頼（プルリクエスト）を作成します。

# 念のため自分のfeatureブランチに切り替え
git switch feature/your-feature-name

# 最新の変更をリモートにプッシュ
git push origin feature/your-feature-name

その後、GitHubの画面で：

1. feature/your-feature-name → main に向けてPR作成
2. 上記のPR概要テンプレートを使って詳細を記入
3. レビュアーを指定してレビュー依頼
4. プロジェクトのslackチャンネルでレビュアーにメンション（@neme）をつけて送信

7. レビュー対応

レビューで指摘事項がある場合の対応：

# featureブランチで修正作業
git switch feature/your-feature-name

# ファイルを修正後
git add .
git commit -m "レビュー指摘事項を修正"

# 再度developブランチで動作確認
git switch develop
git pull origin develop
git merge feature/your-feature-name
git push origin develop

動作確認完了後、PRページで「レビュー再依頼」を送ります。

8. 本番リリース

レビューが承認（LGTM: Looks Good To Me）されたら：

1. レビュアーが main ブランチにマージ
2. 本番環境に自動デプロイ
3. ユーザーが少ない時間帯でのリリースを推奨（深夜や早朝）

ブランチ命名規則

feature ブランチ

feature/機能名
feature/課題番号-機能名

良い例:

• feature/user-authentication （ユーザー認証機能）
• feature/123-course-search （課題番号123のコース検索機能）
• feature/ai-chat-integration （AI チャット統合）

悪い例:

• feature/fix （何を修正するか不明）
• feature/update （何を更新するか不明）
• feature/テスト （日本語は避ける）

その他のブランチ

hotfix/緊急修正内容    # 本番の緊急修正
bugfix/バグ修正内容   # 通常のバグ修正
chore/作業内容        # リファクタリング、設定変更など
docs/ドキュメント内容  # ドキュメント追加・更新

ClaudeCode による自動PR

本リポジトリでは、ClaudeCode を用いた自動コードレビュー（Auto PR）を試験導入しています。

自動PRの目的と範囲

• 目的: 定型作業や小規模な改善の自動化
  • ドキュメント整備
  • コメント・型の改善
  • 小さなリファクタリング
  • 軽微な依存関係の更新
• 作成者: Bot/自動化アカウントからPRが作成されます
• 人間のレビュー必須: すべての自動PRは人間のレビュー・承認が必須
• 品質基準: 通常のPRと同じ品質基準を適用

自動PRのレビューガイドライン

チェックポイント:

1. 影響範囲: 機能的挙動に影響しないか
2. 品質向上: 命名・可読性・一貫性が向上しているか
3. テスト影響: ビルドやテストに問題がないか
4. セキュリティ: セキュリティやパフォーマンスに問題がないか
5. 説明: 変更理由がPR本文で十分説明されているか

対応方針:

• 大きすぎる変更は分割を依頼
• 問題があればクローズやマージ拒否も可
• 必要に応じて追加修正を依頼

レビューガイドライン

レビュアーのチェックポイント

1. 機能要件: 仕様通りに実装されているか
2. コード品質:
   • 読みやすいコードか
   • 将来修正しやすいか
   • 他の部分で再利用できるか
3. セキュリティ:
   • 個人情報の扱いは適切か
   • SQLインジェクションなどの脆弱性はないか
4. パフォーマンス:
   • 動作が重くなっていないか
   • 無駄な処理はないか
5. テスト:
   • 重要な機能にテストが書かれているか
   • エッジケースも考慮されているか
6. ドキュメント:
   • READMEやコメントが更新されているか

レビューのマナー

良いレビューの例:

• 「この関数名は getUserData の方が分かりやすいかもしれません」
• 「セキュリティの観点から、パスワードのバリデーションを追加してください」
• 「素晴らしい実装です！一点確認ですが...」

避けるべきレビュー:

• 「ダメです」（理由を説明しない）
• 「なんでこう書いたの？」（攻撃的な言い方）
• 人格攻撃や感情的なコメント

緊急時の対応

hotfix フロー

本番で緊急のバグが見つかった場合：

# mainブランチから緊急修正ブランチを作成
git switch main
git pull origin main
git switch -c hotfix/critical-bug-fix

# 修正作業
# ... ファイル修正 ...

git add .
git commit -m "hotfix: 緊急バグを修正"
git push origin hotfix/critical-bug-fix

# PRを作成してレビュー（通常より迅速に）
# マージ後、developブランチにも同じ修正を反映
git switch develop
git pull origin develop
git merge hotfix/critical-bug-fix
git push origin develop

ロールバック

# 特定のコミットの変更を打ち消す（推奨）
git revert <commit-hash>

# 緊急時のみ使用（危険：履歴が書き換わる）
git reset --hard <commit-hash>

よくあるGitコマンド

基本操作

# 現在の状況を確認
git status

# 変更履歴を確認
git log --oneline

# ブランチ一覧を確認
git branch

# 現在のブランチを確認
git branch --show-current

# リモートの最新情報を取得（ローカルは変更しない）
git fetch

# 指定したブランチの最新を取得してマージ
git pull origin main

ブランチ操作

# 新しいブランチを作成して切り替え
git switch -c feature/new-feature

# 既存のブランチに切り替え
git switch main

# ブランチを削除（マージ済みの場合）
git branch -d feature/completed-feature

# ブランチを強制削除
git branch -D feature/abandoned-feature

取り消し・修正

# 最後のコミットメッセージを修正
git commit --amend -m "新しいコミットメッセージ"

# ファイルの変更を取り消し（危険：変更が失われます）
git checkout HEAD -- filename.txt

# 最新のコミットを取り消し（コミットは削除、変更は残る）
git reset --soft HEAD~1

# ステージングを取り消し
git reset filename.txt

# コミットをの結合
git rebase -i HEAD~2

トラブルシューティング

よくあるエラーと解決方法

1. git push でエラーが出る

# エラー例: "Updates were rejected because the remote contains work..."
# 解決方法: 最新の変更を取得してから再度プッシュ
git pull origin develop
git push origin develop

2. マージコンフリクトが発生

# コンフリクトしたファイルを手動で修正後
git add .
git commit -m "conflict: マージコンフリクトを解決"

3. 間違ったブランチにコミットしてしまった

# コミットを別のブランチに移動
git switch correct-branch
git cherry-pick <commit-hash>

git switch wrong-branch
git reset --hard HEAD~1  # 最後のコミットを削除

4. 作業中のファイルを一時的に保存したい

# 作業を一時保存
git stash

# 他の作業...

# 保存した作業を復元
git stash pop

# 一時保存した作業のリストを確認
git stash list

まとめ

このワークフローを守ることで：

1. 安全な開発: 本番環境を壊すリスクを最小限に
2. 品質向上: レビューを通して全体のコード品質を向上
3. チーム協調: 全員が同じルールで効率的に開発
4. 履歴管理: 変更の理由と経緯を明確に記録

初心者の方へ:
最初は複雑に感じるかもしれませんが、このフローに従えば安全確実に開発作業ができます。分からないことがあれば、遠慮なくチームメンバーに質問してください。

上級者の方へ:
詳細な説明が多くて恐縮ですが、チーム全体のスキル底上げとミス防止のためです。新しいメンバーへの指導にもご活用ください。

最後に

• web業界ではどこの企業も使っているgit/GitHubですが、初心者には難しく概念の理解がなかなかできないと思います。僕もその一人でした...　　

• そこで、今回は自分が業務の中で困っていることを解決するために、課題を明確に抽出しボトルネックになっていることを１つずつ潰すことで自分の頭の中を整理することができ、あらためてgit/GigHubについて理解が深まりました

• これからも業務をやっているうえで苦労したことについてまとめて初心者のみんなに価値提供できればと考えております。みんなで楽しくエンジニアlifeを送りましょう！！