WingStats Manager Docs

Appearance

AI別 Git Worktree 運用ガイド（VSCode 拡張向け） ​

このドキュメントは、Codex / GitHub Copilot Chat / Claude Code を それぞれ別 worktree に固定して安全に並行作業するための運用ルールです。

1. 目的 ​

  • AIごとの作業領域を分離し、誤編集を防ぐ
  • 作業履歴を追いやすくする
  • main への取り込みを定型化し、事故を減らす

2. 割り当てルール ​

以下のように「AI = worktree = ブランチ系統」を固定します。

  • Codex: broadcast-Overlay（例: codex/* ブランチ）
  • Copilot Chat: broadcast-Overlay-copilot-ut（例: copilot/* ブランチ）
  • Claude Code: broadcast-Overlay-claude（例: claude/* または docs/* ブランチ）

AI別の指示ファイル:

  • Codex: AGENTS.md
  • GitHub Copilot Chat: .github/copilot-instructions.md
  • Claude Code: CLAUDE.md

重要:

  • 1つのVSCodeウィンドウは1つのworktreeのみ開く
  • 1つのAIは自分のworktree以外で作業しない

3. VSCode 運用ルール ​

3.1 ウィンドウ運用 ​

  • 各AI専用に VSCode ウィンドウを分ける
  • ウィンドウタイトルにAI名を含める（例: [CODEX] broadcast-Overlay）
  • フォルダは必ず worktree のルートを直接開く

3.2 拡張利用ルール ​

  • Codex 拡張は Codex 専用ウィンドウだけで使う
  • Copilot Chat は Copilot 専用ウィンドウだけで使う
  • Claude Code は Claude 専用ウィンドウだけで使う

3.3 プロンプト固定文（毎回先頭） ​

各AIの最初の指示に以下を入れる:

このセッションでは現在のworktree配下のみ編集してください。他ディレクトリ参照・編集は禁止です。

4. Git ブランチルール ​

  • main で直接作業しない
  • AIごとにブランチプレフィックスを固定
    • Codex: codex/*
    • Copilot: copilot/*
    • Claude: claude/* / docs/*
  • コミットメッセージにAI識別子を含める（推奨）
    • 例: codex: fix parser edge case
  • 全AI共通で履歴改変を禁止
    • git rebase
    • git pull --rebase
    • git push --force / git push --force-with-lease
    • git reset --hard

4.1 新規 worktree 作成手順 ​

新しい worktree を追加するときは scripts/dev/add-worktree.ps1 を使う。 これは git worktree add を実行したあと、自動で .mcp.json を生成する。

powershell
# 既存ブランチをチェックアウト
pwsh ./scripts/dev/add-worktree.ps1 -Path ../broadcast-Overlay-foo -Branch feature/foo

# 新規ブランチを作成
pwsh ./scripts/dev/add-worktree.ps1 -Path ../broadcast-Overlay-bar -Branch claude/bar -NewBranch

.mcp.json が必要な理由:

  • spec-workflow MCP サーバが Claude Code セッション開始時に spawn される
  • 中身に worktree の絶対パスが入るため、git 管理外（.gitignore 済み）で worktree ごとに必須
  • ダッシュボード（http://localhost:5000）は別プロセスとして常時起動しておく前提。 各 worktree で Claude Code を起動すると、その MCP サーバが自動でダッシュボードに登録される

既存の worktree で .mcp.json が無い場合や再生成したい場合:

powershell
pwsh ./scripts/dev/setup-worktree-mcp.ps1          # 既存があれば skip
pwsh ./scripts/dev/setup-worktree-mcp.ps1 -Force   # 強制上書き

ダッシュボードの起動・停止は本ガイドの対象外（運用担当が別途管理）。

5. 日次フロー（推奨） ​

  1. 各worktreeで git fetch --all --prune
  2. 各AIは自分のブランチだけ更新
  3. PR or 統合ブランチに集約
  4. 統合担当が main へ取り込み
  5. typecheck / test 実行後に push

6. 取り込みフロー（このリポ向け） ​

定期取り込みは以下の順で実施:

  1. main の作業ツリーをクリーンにする
  2. scripts/dev/merge-worktrees.ps1 を実行
  3. 必要なら -Push を付けて反映

例:

powershell
# まず確認
./scripts/dev/merge-worktrees.ps1 -DryRun -AllowDirty

# 実行
./scripts/dev/merge-worktrees.ps1

# pushまで（フックをスキップする場合）
./scripts/dev/merge-worktrees.ps1 -Push -NoVerify

6.1 AI別の取り込み責務 ​

  • Codex (main worktree): 取り込み実行担当
    • scripts/dev/merge-worktrees.ps1 を実行して main へ統合
  • Copilot (copilot-ut worktree): 取り込み準備担当
    • git fetch --all --prune / git merge main / git push で最新化
  • Claude (docs worktree): 取り込み準備担当
    • git fetch --all --prune / git merge main / git push で最新化

補足:

  • 実際の「取り込み実行」は原則 main worktree のみで行う

7. 禁止事項 ​

  • 他worktreeのパスを直接編集する
  • AIに「親ディレクトリを再帰編集」させる
  • main へ直接コミット
  • detached HEAD worktree で開発継続

8. トラブル時ルール ​

  • 他worktreeへの誤編集を検知したら即停止
  • どのAIウィンドウで実行したか記録
  • 取り込み前に git status --short --branch を必ず確認

9. 最小チェックリスト ​

作業開始前:

  • [ ] 正しいworktreeを開いている
  • [ ] 正しいブランチにいる
  • [ ] AIに「このworktree配下のみ編集」を指示した

マージ前:

  • [ ] 変更は自worktree配下のみ
  • [ ] typecheck 実行済み
  • [ ] 必要なテストを実行済み

取り込み前:

  • [ ] main はクリーン
  • [ ] 取り込み対象ブランチを確認済み