[Claude Code] worktree + ISSUE.mdを使ったブレない並列開発手法
はじめに
ブランチを切り替えるたびにstashする、という作業を面倒に感じたことはないでしょうか。
Git worktreeを使うとその手間が減ります。
Claude Codeと組み合わせると並列作業がしやすくなります。
この記事では、worktreeとISSUE.mdを使ったワークフローを整理します。
Git worktreeとは
Git worktreeは、同じリポジトリから複数のブランチを同時に開ける機能です。
各worktreeは独立したファイル状態を持ちながら、同じGit履歴を共有します。
Claude Codeとworktreeの組み合わせ
公式ドキュメントでは、Claude Codeとworktreeの組み合わせを以下のように説明しています。
複数のタスクを同時に作業する必要があり、Claude Codeインスタンス間で完全なコード分離が必要な場合に使用します。
各worktreeは独自の独立したファイル状態を持っているため、並列のClaude Codeセッションに最適です。1つのworktreeで行われた変更は他に影響せず、Claudeインスタンスが互いに干渉するのを防ぎます。
つまり、worktree Aで Issue #123、worktree Bで Issue #456 というように、複数のIssueを並列で進められます。
ISSUE.mdとは
ISSUE.mdは、worktree作成時に対象Issueの情報をまとめたファイルです。
ISSUE.mdには、Issueのタイトルと本文、関連コメント、関連Issue/PRへのリンク、設計メモなどを含めます。
Claude Codeを起動したときに「このworktreeで何をすべきか」が明確になります。
なぜこのワークフローが有効か
自動化しやすい
worktree作成とISSUE.md生成をスクリプト化できます。
Issue番号を渡すだけで作業環境が整います。
方向性が明確
ISSUE.mdを読めば「何をすべきか」がわかります。
Claude Codeに「ISSUE.mdを読んで、計画を立てて」と指示するだけで作業を開始できます。
並列作業が可能
複数のworktreeで複数のClaude Codeインスタンスを動かせます。
1つのIssueの作業中に別のIssueも進められます。
干渉がない
各worktreeは独立したファイル状態を持つため、あるworktreeでの変更が別のworktreeに影響しません。
worktreeの基本操作
新しいworktreeを作成
# 新しいブランチでworktreeを作成
git worktree add ../project-feature-a -b feature-a
# 既存のブランチでworktreeを作成
git worktree add ../project-bugfix bugfix-123
worktreeでClaude Codeを実行
# worktreeに移動
cd ../project-feature-a
# Claude Codeを起動
claude
worktreeの管理
# 全worktreeを一覧表示
git worktree list
# 作業完了後にworktreeを削除
git worktree remove ../project-feature-a
ISSUE.mdの生成
ghコマンドを使ってIssue情報を取得し、ISSUE.mdを生成します。
#!/bin/bash
# start-issue.sh
ISSUE_NUMBER=$1
WORKTREE_DIR="../issue-${ISSUE_NUMBER}"
# worktree作成
git worktree add "$WORKTREE_DIR" -b "issue-${ISSUE_NUMBER}"
# ISSUE.md生成
cd "$WORKTREE_DIR"
{
echo "# Issue #${ISSUE_NUMBER}"
echo ""
gh issue view "$ISSUE_NUMBER"
echo ""
echo "## Comments"
gh issue view "$ISSUE_NUMBER" --comments
} > ISSUE.md
# Claude Codeを起動（新しいターミナルで）
echo "worktree created: $WORKTREE_DIR"
echo "Run: cd $WORKTREE_DIR && claude"
使用例です。
./start-issue.sh 123
Claude Codeでの作業開始
worktreeに移動してClaude Codeを起動したら、以下のように指示します。
ISSUE.mdを読んで、このIssueに対応するための計画を立てて。
実装はまだしないで。
計画を確認し、問題なければ実装を許可します。
注意点
worktreeは独立したファイル状態を持つため、node_modulesなどは各worktreeで個別にインストールが必要です。
実践的なワークフロー
- Issue選択：取り組むIssueを決める
- worktree作成：
start-issue.shでworktreeとISSUE.mdを生成 - 環境セットアップ：依存関係のインストール
- Claude Code起動：worktreeでclaude起動
- 計画確認：ISSUE.mdを読ませて計画を立てさせる
- 実装：計画に問題なければ実装
- PR作成：Claude CodeにPR作成を依頼
- クリーンアップ：マージ後にworktreeを削除
まとめ
- Git worktreeは同じリポジトリから複数の作業ディレクトリを作成できる機能
- ISSUE.mdはIssue情報をまとめたファイルで、作業の方向性を明確にする
- worktree + ISSUE.mdで自動化しやすく、並列作業が可能になる
-
ghコマンドでISSUE.md生成をスクリプト化できる - 各worktreeで依存関係のインストールが必要なことに注意
Discussion