novel-jp/learn-gw-branch

/learn-gw-branch — ブランチ戦略（06-01、必修）

Trunk-based development の概念と、ブランチ命名規則を学び、実際にブランチを作成する演習です。

所要時間: 約 30 分 前提: /learn-setup（00-01）完了済み、/learn-ac-evaluate（05-01）完了済み スキル対応: Git Workflow（チーム開発フロー）

---

Step 1: 導入

「Git Workflow — チーム開発のフローを回す力を学びます。

AI 時代でも Git は開発の基盤です。
むしろ AI がコードを高速に生成するからこそ、変更管理の重要性が増しています。

このセクションでは以下を学びます:
- Trunk-based development の考え方
- ブランチ命名規則の意味
- ProjSight タスクとブランチの紐づけ」

---

Step 2: 演習タスクの作成と学習環境の確認

演習追跡タスクの作成

この演習全体の進捗を ProjSight で追跡するためのタスクを作成し、作業を開始する。 （Step 4 ではブランチ命名を練習するための別のタスクを作成します。ここで作るのは演習そのものの追跡用です。）

1. list_deliverables(projectId) で紐づけ先の成果物を確認する
   • 00-01 で作成した「学習カリキュラム」成果物に紐づける
   • 成果物が見つからない場合は upsert_deliverable(title: '学習カリキュラム') で作成する
2. upsert_task で演習タスクを作成する（タイトル例: 「06-01 ブランチ戦略の演習」）
3. start_work(taskId) で作業を開始する

タスク ID は AI が保持しますが、念のためメモしておくと安心です。演習の最後に complete_work で完了にします。

学習リポジトリの確認

受講者の learn-projsight リポジトリ（00-01 で作成済み）で作業する。 AI が learn-workspace/learn-projsight ディレクトリに移動して作業を開始する。

リポジトリが見つからない場合:

# learn-workspace 配下に作成
mkdir -p learn-workspace/learn-projsight && cd learn-workspace/learn-projsight && git init

---

Step 3: ブランチ戦略の説明

以下の内容を受講者に説明する:

Trunk-based Development

「Trunk-based development とは:
- main ブランチが常にリリース可能な状態を保つ
- 短命なブランチ（short-lived branches）で作業する
- ブランチの寿命は数時間〜数日。長くても 1 週間以内
- main への直接 push は禁止。必ず PR 経由でマージ

ProjSight では DR-0089 でこの戦略を採用しています。
理由は『AI エージェントが並行作業しやすく、コンフリクトを最小化できる』ため。
チーム規模が小さいうちは特に、シンプルな main + 短命ブランチが最も効率的です。」

ブランチ命名規則

| パターン | 例 | 説明 | | ---------------------- | ------------------- | --------------------------------- | | task/<number>-<slug> | task/42-add-login | ProjSight のタスク番号 + 短い説明 |

slug とは: 英語の短い説明をハイフン区切りにしたもの（例: add-login-page, fix-null-check）。日本語のタスク名は英訳して短縮します。

| 日本語タスク名 | slug 例 | | --------------------------- | --------------------- | | 「ログイン画面のバグ修正」 | fix-login-bug | | 「README に学習メモを追加」 | add-learning-notes | | 「ユーザー一覧 API の実装」 | implement-user-list |

task/ に統一する理由: タスクの種別（機能追加・バグ修正・リファクタ等）はブランチ名ではなくコミットメッセージのプレフィックス（feat:, fix: 等）で区別します。ブランチ名はタスクとの紐づけに専念させることで、命名ルールをシンプルに保てます。

「命名規則があると:
- ブランチを見ただけで『何のタスクか』が分かる
- ProjSight のタスク番号で検索できる
- AI エージェントが自動的に正しいブランチ名を生成できる」

---

Step 4: ブランチ作成の実践

ブランチ命名を練習するために、新しい演習用タスクを作成してブランチを作ります。 （Step 2 の演習追跡タスクとは別のタスクです。）

1. 演習用タスクの作成

upsert_task で演習用タスクを作成する:

• タイトル例: 「README に学習メモを追加」
• Step 2 と同じ成果物に紐づける

作成されたタスクの番号を使って、次のステップでブランチを作成する。

2. ブランチの作成

作成したタスクの番号と slug を使ってブランチを作成する。

git checkout -b task/<タスク番号>-<slug>

3. 変更を加える

README.md に ## 学習メモ セクションを追加してください。 内容は自由ですが、例えば今日学んだことを 1〜2 行書いてみましょう。

4. コミット

変更をコミットする。git add ではファイル名を明示するのがベストプラクティスです。

git add README.md
git commit -m "docs: README に学習メモセクションを追加"

コミットメッセージの規則

コミットメッセージにプレフィックスをつけると、変更履歴の自動生成やレビュー時の素早い分類に役立ちます。

| プレフィックス | 用途 | | -------------- | ---------------- | | feat: | 新機能 | | fix: | バグ修正 | | refactor: | リファクタリング | | docs: | ドキュメント | | test: | テスト |

---

Step 5: 振り返り

「ブランチ戦略のポイント:

- main は常にリリース可能 — 壊れたコードを main に入れない
- 短命ブランチ — 長く生きるブランチはコンフリクトの温床
- 命名規則 — task/<number>-<slug> でタスクとの紐づけが一目瞭然
- コミットメッセージ — プレフィックスで変更の種類を明示

この演習では PR は扱いません。次の /learn-gw-pr で、ブランチから PR を作成し ProjSight に紐づける全フローを体験します。」

ブランチについて: 作成したブランチは次の /learn-gw-pr で PR 作成に使います。main に戻らず、このブランチのまま残しておいてください。

Step 2 で作成した演習追跡タスクを complete_work(taskId) で完了にする。 Step 4 で作成した演習用タスクは次の /learn-gw-pr で PR に紐づけるため、完了にせず in_progress のまま残す。