「Issue、デカすぎてコンテキスト溢れた...」

Claude Codeでgit worktreeを使った並列開発。「ブランチ分けて同時に実装すれば速い」という話はよく聞きます。実際、小さなIssueなら1つのworktreeで十分。でも、10ファイル以上に変更が及ぶ大きなIssueに出くわしたとき、「どう分割するか」「どう合流させるか」が急に難しくなる。

タスクの分解は手作業。worktreeの準備も手作業。マージしたらコンフリクト。型が通らない。テストが落ちる。並列にした分だけ統合コストが増えて、結局トータルで遅くなる...そんな経験、ありませんか？

私たちも何度もこの壁にぶつかりました。worktree並列開発の速度を活かすには、「分解」と「統合」の両方を設計しないといけない。そこで作ったのが、dev-decompose（自動タスク分解）とdev-integrate（自動統合パイプライン）です。

この記事で学べること

手動タスク分解の3つの限界と、自動化が必要な理由
dev-decomposeのファイル境界分析による自動タスク分解の仕組み
contract branchパターンで並列ワーカーの整合性を担保する設計
dev-integrateの自動マージ・型チェック・統合テストパイプライン
flow.jsonによる並列パイプラインの進捗追跡
Agent Teamsとworktree並列開発の使い分け

前提知識

Claude Codeの基本操作を理解している
git worktreeの概念を知っている
Skillsの基本概念と状態管理パターンを把握している

手動タスク分解の3つの限界

並列開発の「分解」を手作業で行うと、3つの問題が発生します。

1. ファイル重複による確定コンフリクト

「タスクAでauth.tsを修正して、タスクBでもauth.tsに手を入れて...」

2つのworktreeで同じファイルを触った瞬間、マージコンフリクトが確定します。人間が目視で「このファイルはこっち担当、あのファイルはあっち担当」と分けるのは、ファイル数が5を超えたあたりから怪しくなる。10ファイルの依存関係を正確に頭の中で管理できる人がいたら、それはもうIDEです。

2. 共有型の不在による型エラー地獄

タスクAがUserDTOという型を定義して、タスクBが同じUserDTOを別の形で定義する。マージした瞬間、TypeScriptコンパイラが怒涛の赤線を吐く。

並列に作業するなら、「共通の型定義を先に決めておく」のが鉄則です。教科書にはそう書いてある。でも教科書どおりにできる人は、そもそも締め切りに追われていない。

3. 統合テストの後回し

分解に集中するあまり、統合のことを考えていない。全タスクが完了してからマージしたら、テストが12件落ちている。どのタスクの変更が原因なのか、もう追えない。

「マージしてから直す」ではなく、「直せる順番でマージする」。この発想の転換が必要でした。

dev-decompose: ファイル境界分析による自動タスク分解

dev-decomposeは、大きなIssueをファイル境界で自動的にサブタスクに分割するスキルです。

核心のルール: 1ファイル = 1タスク

原則は単純です。各ソースファイルは、必ず1つのサブタスクにだけ所属する。

Good: ファイルの所属が明確
├── task1: src/models/user.ts, src/models/user.test.ts
├── task2: src/routes/auth.ts, src/routes/auth.test.ts
└── contract: src/types/auth.ts (共有型)

Bad: 同じファイルが複数タスクに登場
├── task1: src/models/user.ts, src/routes/auth.ts  ← 重複！
└── task2: src/routes/auth.ts, src/middleware/jwt.ts ← コンフリクト確定

ファイル重複がゼロなら、テキストレベルのマージコンフリクトはゼロ。gitの仕組み上、異なるファイルへの変更は衝突しない。証明終わり。

依存グラフの構築

dev-decomposeはまず、変更対象ファイルのimport/require関係を解析して依存グラフを構築します。

1. 各ファイルのimport文を解析
2. 変更対象ファイル同士の参照関係を特定
3. 双方向依存（A→B かつ B→A）→ 「密結合」→ 同一タスクに同居
4. 一方向依存（A→B のみ）→ 「疎結合」→ contract経由で分離可能

密結合のファイルは無理に分けない。分けるとcontractが肥大化して、並列化の旨味がなくなります（分割したのに会議が増えた、みたいな話です）。逆に疎結合のファイルは積極的に分離して、並列実行のメリットを最大化する。

テストファイルの同居ルール

テストファイルは必ず実装ファイルと同じタスクに入ります。

task1:
  - src/services/order.ts        ← 実装
  - src/services/order.test.ts   ← テスト（必ずセット）

テストと実装を別タスクに分けるのは、見た目の並列度は上がりますが、「テストを書く人が実装の文脈を持っていない」状態になります（答えを知らない人が採点しているようなもの）。タスク数が増えただけで品質は下がる。6並列で全テスト赤より、2並列で全テスト緑。分割数は正義じゃない。

フォールバック: 分解しない勇気

dev-decomposeには分解をやめる判断も組み込まれています。

条件	判断
変更ファイルが4未満	worktree分割のオーバーヘッドが利益を上回る
全ファイルが密結合	分離不可能、single modeにフォールバック
サブタスクが1つ	分割する意味がない
単一コンポーネント内の変更	自然な分割境界がない

{
  "status": "single_fallback",
  "subtask_count": 1,
  "reason": "All files are tightly coupled"
}

「並列化ありき」ではなく、分解して速くなるときだけ分解する。包丁を買ったら何でも切りたくなるように、worktreeを覚えると何でも分割したくなる。その衝動にブレーキをかけるのもdev-decomposeの仕事です。

contract branch: 共通型定義で並列ワーカーの整合性を担保する

並列で作業するワーカーが、同じ型定義を参照していないと、マージ後に型エラーの嵐になります。この問題を解決するのがcontract branchパターンです。

仕組み

main ─── feature/issue-42-contract  ← dev-decomposeが共有型をコミット
             ├── feature/issue-42-task1  ← contractから分岐
             ├── feature/issue-42-task2  ← contractから分岐
             ├── feature/issue-42-task3  ← contractから分岐
             └── feature/issue-42-merge  ← 統合先

dev-decomposeが変更に必要な共有の型定義・インターフェースを特定
feature/issue-42-contractブランチを作成し、型定義だけをコミット
各タスクのworktreeは、このcontractブランチから分岐

全タスクが同じ型定義を出発点にしているので、UserDTOの定義が食い違う問題が構造的に起きない。

contractに含めるもの / 含めないもの

含める	含めない
型定義・インターフェース	実装ロジック
enum宣言	テストコード
API境界の関数シグネチャ	設定ファイル
共有の定数	ビジネスルール

contractはあくまで「約束」です。実装は各タスクの責任。約束を先に決めておくから、並列に実装しても噛み合う。「実装じゃなくインターフェースに依存せよ」——SOLID原則、20年経っても現役です。

contractが不要なケース

全ファイルが1つのタスクに収まる場合（single_fallback）や、タスク間で共有する型がない場合は、contract branchを作りません。不要な抽象化はオーバーヘッドです。

git-prepare: worktree自動作成と環境同期

各タスクのworktreeはgit-prepareスキルが自動作成します。git-prepareの.envハードリンクやブランチ命名規則についてはSKILL.mdの書き方と設計パターンでも触れています。

# dev-decomposeが内部で呼び出す
$SKILLS_DIR/git-prepare/scripts/git-prepare.sh 42 \
  --suffix task1 \
  --base feature/issue-42-contract \
  --env-mode hardlink

--suffix task1でworktreeの命名を自動化し、--baseでcontract branchからの分岐を指定。--env-mode hardlinkで.envファイルをハードリンクで共有し、環境変数の手動コピーも不要にしています。worktreeを作って.envをコピーし忘れ、「API繋がらないんだけど」とSlackに書く——チーム全員が一度は踏む地雷です。

dev-integrate: マージ・型チェック・統合テストの自動パイプライン

全タスクが完了したら、dev-integrateが依存関係に基づいた順序でマージします。

パイプラインの流れ

Step 1: flow.json確認 → 全タスク completed?
Step 2: ドリフト検出 → 予定 vs 実際の変更ファイル比較
Step 3: マージ順序決定 → トポロジカルソート（依存なしから先にマージ）
Step 4: マージworktree作成
Step 5: 順次マージ → conflict検出 → auto-resolve or abort
Step 6: 型チェック → tsc --noEmit / mypy / go vet
Step 7: 統合テスト → dev-validate
Step 8: flow.json更新

トポロジカルソートによるマージ順序

flow.json:
  task1: depends_on: []         # 認証モジュール
  task2: depends_on: [task1]    # ユーザーAPI（認証が必要）
  task3: depends_on: []         # ログユーティリティ

計算されたマージ順序: task1 → task3 → task2

理由:
  - task1とtask3は依存なし（先にマージ）
  - task2はtask1に依存（task1の後でマージ）

「直せる順番でマージする」 がここで実現されています。依存のないタスクから先にマージすることで、もしコンフリクトが起きても影響範囲が小さい。task2でコンフリクトが起きても、task1とtask3のマージは既に成功しているので、やり直しの範囲が限定されます。

自動解決可能なコンフリクト

lock系ファイルは自動解決します。

ファイルパターン	戦略	理由
`package-lock.json`	`--theirs`で受け入れ	`npm install`で再生成
`yarn.lock`	`--theirs`で受け入れ	`yarn install`で再生成
`pnpm-lock.yaml`	`--theirs`で受け入れ	`pnpm install`で再生成
`*.sum`（Go）	`--theirs`で受け入れ	`go mod tidy`で再計算

lock fileのコンフリクト解消に時間を使うのは完全に無駄です。数千行のdiffを真剣に読んだ5分後、npm install一発で全部上書きされる。それはもう写経です。

コードファイルのコンフリクト: 止まる勇気

コードファイルでコンフリクトが起きた場合、dev-integrateはマージを中断してユーザーに報告します。

{
  "integration": {
    "status": "failed",
    "failed_at_task": "task2",
    "error": "unresolvable merge conflict",
    "conflict_files": ["src/auth/handler.ts"]
  }
}

自動解決を試みて壊れたコードをコミットするより、「ここで詰まりました」と正直に報告するほうが、結果的に速い。コンフリクト解消をAIに丸投げすると、直したはずの箇所から新しいバグが生えてくる。

型チェックと統合テスト

マージが完了したら、プロジェクトの型チェックと統合テストが自動で走ります。

# プロジェクトタイプを自動検出
if [ -f "tsconfig.json" ]; then npx tsc --noEmit
elif [ -f "pyproject.toml" ]; then mypy .
elif [ -f "go.mod" ]; then go vet ./...
elif [ -f "Cargo.toml" ]; then cargo check
fi

# その後、dev-validateで統合テスト
Skill: dev-validate --worktree $MERGE_WORKTREE

型チェックで引っかかるのは、たいてい「contractでstringにしたのに実装側がstring | nullを返してる」みたいな微妙なズレです。contractの詰めが甘かった証。TypeScriptコンパイラは忖度しないので、いい先生になってくれます。

flow.json: 並列パイプラインの進捗追跡

並列開発のオーケストレーション全体を追跡するのがflow.jsonです。

{
  "version": "1.0.0",
  "issue": 42,
  "status": "implementing",
  "subtasks": [
    {
      "id": "task1",
      "scope": "認証モジュール",
      "files": ["src/models/user.ts", "src/models/user.test.ts"],
      "status": "completed",
      "actual_files_changed": ["src/models/user.ts", "src/models/user.test.ts"],
      "checklist": [
        { "item": "Userスキーマ定義", "done": true },
        { "item": "マイグレーション追加", "done": true }
      ]
    },
    {
      "id": "task2",
      "scope": "認証エンドポイント",
      "files": ["src/routes/auth.ts", "src/routes/auth.test.ts"],
      "depends_on": ["task1"],
      "status": "in_progress",
      "checklist": [
        { "item": "POST /auth/login 実装", "done": true },
        { "item": "JWT検証ミドルウェア", "done": false }
      ]
    }
  ],
  "contract": {
    "branch": "feature/issue-42-contract",
    "files": ["src/types/auth.ts"]
  },
  "integration": {
    "status": "pending"
  }
}

なぜファイルベースなのか

flow.jsonがファイルで永続化されている理由は2つあります。

1. auto-compact耐性: Claude Codeのコンテキストウィンドウが圧縮されても、ファイルは消えない。cat flow.jsonで今どこまで進んだか、いつでも確認できる（翌朝の自分が感謝するやつ）。

2. 単一ライター原則: flow.jsonへの書き込みはdev-flow（オーケストレータ）だけが行い、各サブエージェントは自分のworktree内のkickoff.jsonだけを更新する。排他制御が不要なシンプルな設計です。

書き込み権限:
  flow.json           ← dev-flow, dev-decompose, dev-integrateのみ
  kickoff.json (各WT) ← 各サブエージェント（自分のworktreeのみ）

読み取り:
  flow.json           ← 全サブエージェント（参照のみ）
  kickoff.json        ← dev-flow（集約のため）

この設計は、前回の状態管理記事で解説したkickoff.jsonの延長線上にあります。状態をファイルに永続化する、JSON Schemaで構造を保証する、人間がいつでもcatで読める。同じ原則を並列開発に拡張しただけです。

ステータスの遷移

analyzing → decomposing → implementing → integrating → pr → iterating → completed

各フェーズの完了条件が明確なので、途中で中断しても「次は何をすればいいか」がflow.jsonを見ればわかります。

Agent Teams との使い分け指針

Claude Codeには、worktree並列開発のほかにAgent Teams（SendMessage/TeamCreate/TaskListを使った複数エージェント協調）もあります。どちらを使うべきか、判断基準をまとめます。

観点	worktree並列（dev-decompose）	Agent Teams
得意パターン	ファイル分割可能な実装タスク	リアルタイム協調が必要な調査タスク
コンフリクト	ファイル境界で構造的に回避	同じファイルを触る可能性あり
コスト	worktree数 x dev-kickoff	エージェント数 x ターン数
状態共有	flow.json（ファイルベース）	SendMessage（リアルタイム）
適用例	認証+API+UIの3モジュール実装	バグ調査、コード監査、インシデント対応
フィードバック	統合時にまとめて検出	調査中にリアルタイムで方向転換

経験則: 「分けて、それぞれ作って、最後に合わせる」ならworktree並列。「みんなで同じものを見ながら、発見を即座に共有する」ならAgent Teams。

具体例を挙げると、私たちはコード監査やバグ調査のように「調査中に発見を即座に共有したい」タスクにはAgent Teamsを使い、機能実装にはworktree並列を使っています。目的に応じた使い分けが大事です。

全体フロー: dev-flow --parallel

ここまでの仕組みを束ねるのがdev-flow --parallelです。

/dev-flow 42 --parallel

Step 1: dev-issue-analyze（要件分析）
    ↓
Step 2: dev-decompose（自動タスク分解）
    ├── contract branch作成・型定義コミット
    ├── worktree x N 自動作成
    └── flow.json生成
    ↓
Step 3: 分解結果チェック
    └── subtask_count == 1 → single modeにフォールバック
    ↓
Step 4: dev-kickoff x N（並列実装）
    ├── Batch 1: [task1, task3] ── 独立タスクを並列
    └── Batch 2: [task2] ── task1完了後に実行
    ↓
Step 5: 結果集約（kickoff.json → flow.json）
    ↓
Step 6: dev-integrate（統合）
    ├── トポロジカルソートでマージ
    ├── 型チェック
    └── 統合テスト
    ↓
Step 7: git-pr（PR作成）
    ↓
Step 8: pr-iterate（セルフレビューループ）

小さなIssue（変更ファイル4未満）なら従来どおりdev-kickoff 1本。大きなIssueのときだけ並列モードに入る。使い分けは自動判定なので、開発者は--parallelフラグを付けるだけです。

まとめ

worktree並列開発のボトルネックは「分解」と「統合」でした。dev-decomposeはファイル境界分析でコンフリクトを構造的にゼロにするタスク分解を行い、contract branchで並列ワーカーの型整合性を担保する。dev-integrateは依存順序に基づいた自動マージと型チェック・テスト実行で、統合の手間を最小化する。

並列開発は「速く作る」技術ではなく、「速く作って、ちゃんと合わせる」技術です。分解が雑なら統合で死ぬ。統合を考えない分解は、ただの分裂。dev-decomposeとdev-integrateは、この両面を1つのパイプラインに統合しました。

まずは/dev-flow 42 --parallelで試してみてください。「このIssue、並列にしたら速くなるかな？」という判断すら、dev-decomposeが自動でやってくれます。合わなければsingle modeに戻るだけ。最悪でも「分割しませんでした」と報告されて終わり。判断を委ねるのに失うものがない——それが、このスキルの一番の設計意図かもしれません。

なお、dev-flowを最大限に活用するにはsettings.jsonのhooksやCLAUDE.mdの参照分離でClaude Codeの基盤環境を整えておくことをおすすめします。また、個々のSkillを連携させるオーケストレーション設計の基本も参考になります。

この記事で学べること

手動タスク分解の3つの限界と、自動化が必要な理由
dev-decomposeのファイル境界分析による自動タスク分解の仕組み
contract branchパターンで並列ワーカーの整合性を担保する設計
dev-integrateの自動マージ・型チェック・統合テストパイプライン
flow.jsonによる並列パイプラインの進捗追跡
Agent Teamsとworktree並列開発の使い分け

前提知識

Claude Codeの基本操作を理解している
git worktreeの概念を知っている
Skillsの基本概念と状態管理パターンを把握している

手動タスク分解の3つの限界

並列開発の「分解」を手作業で行うと、3つの問題が発生します。

1. ファイル重複による確定コンフリクト

「タスクAでauth.tsを修正して、タスクBでもauth.tsに手を入れて...」

2. 共有型の不在による型エラー地獄

タスクAがUserDTOという型を定義して、タスクBが同じUserDTOを別の形で定義する。マージした瞬間、TypeScriptコンパイラが怒涛の赤線を吐く。

3. 統合テストの後回し

「マージしてから直す」ではなく、「直せる順番でマージする」。この発想の転換が必要でした。

dev-decompose: ファイル境界分析による自動タスク分解

dev-decomposeは、大きなIssueをファイル境界で自動的にサブタスクに分割するスキルです。

核心のルール: 1ファイル = 1タスク

原則は単純です。各ソースファイルは、必ず1つのサブタスクにだけ所属する。

Good: ファイルの所属が明確
├── task1: src/models/user.ts, src/models/user.test.ts
├── task2: src/routes/auth.ts, src/routes/auth.test.ts
└── contract: src/types/auth.ts (共有型)

Bad: 同じファイルが複数タスクに登場
├── task1: src/models/user.ts, src/routes/auth.ts  ← 重複！
└── task2: src/routes/auth.ts, src/middleware/jwt.ts ← コンフリクト確定

ファイル重複がゼロなら、テキストレベルのマージコンフリクトはゼロ。gitの仕組み上、異なるファイルへの変更は衝突しない。証明終わり。

依存グラフの構築

dev-decomposeはまず、変更対象ファイルのimport/require関係を解析して依存グラフを構築します。

1. 各ファイルのimport文を解析
2. 変更対象ファイル同士の参照関係を特定
3. 双方向依存（A→B かつ B→A）→ 「密結合」→ 同一タスクに同居
4. 一方向依存（A→B のみ）→ 「疎結合」→ contract経由で分離可能

テストファイルの同居ルール

テストファイルは必ず実装ファイルと同じタスクに入ります。

task1:
  - src/services/order.ts        ← 実装
  - src/services/order.test.ts   ← テスト（必ずセット）

フォールバック: 分解しない勇気

dev-decomposeには分解をやめる判断も組み込まれています。

条件	判断
変更ファイルが4未満	worktree分割のオーバーヘッドが利益を上回る
全ファイルが密結合	分離不可能、single modeにフォールバック
サブタスクが1つ	分割する意味がない
単一コンポーネント内の変更	自然な分割境界がない

{
  "status": "single_fallback",
  "subtask_count": 1,
  "reason": "All files are tightly coupled"
}

contract branch: 共通型定義で並列ワーカーの整合性を担保する

仕組み

main ─── feature/issue-42-contract  ← dev-decomposeが共有型をコミット
             ├── feature/issue-42-task1  ← contractから分岐
             ├── feature/issue-42-task2  ← contractから分岐
             ├── feature/issue-42-task3  ← contractから分岐
             └── feature/issue-42-merge  ← 統合先

dev-decomposeが変更に必要な共有の型定義・インターフェースを特定
feature/issue-42-contractブランチを作成し、型定義だけをコミット
各タスクのworktreeは、このcontractブランチから分岐

全タスクが同じ型定義を出発点にしているので、UserDTOの定義が食い違う問題が構造的に起きない。

contractに含めるもの / 含めないもの

含める	含めない
型定義・インターフェース	実装ロジック
enum宣言	テストコード
API境界の関数シグネチャ	設定ファイル
共有の定数	ビジネスルール

contractが不要なケース

git-prepare: worktree自動作成と環境同期

# dev-decomposeが内部で呼び出す
$SKILLS_DIR/git-prepare/scripts/git-prepare.sh 42 \
  --suffix task1 \
  --base feature/issue-42-contract \
  --env-mode hardlink

dev-integrate: マージ・型チェック・統合テストの自動パイプライン

全タスクが完了したら、dev-integrateが依存関係に基づいた順序でマージします。

パイプラインの流れ

Step 1: flow.json確認 → 全タスク completed?
Step 2: ドリフト検出 → 予定 vs 実際の変更ファイル比較
Step 3: マージ順序決定 → トポロジカルソート（依存なしから先にマージ）
Step 4: マージworktree作成
Step 5: 順次マージ → conflict検出 → auto-resolve or abort
Step 6: 型チェック → tsc --noEmit / mypy / go vet
Step 7: 統合テスト → dev-validate
Step 8: flow.json更新

トポロジカルソートによるマージ順序

flow.json:
  task1: depends_on: []         # 認証モジュール
  task2: depends_on: [task1]    # ユーザーAPI（認証が必要）
  task3: depends_on: []         # ログユーティリティ

計算されたマージ順序: task1 → task3 → task2

理由:
  - task1とtask3は依存なし（先にマージ）
  - task2はtask1に依存（task1の後でマージ）

自動解決可能なコンフリクト

lock系ファイルは自動解決します。

ファイルパターン	戦略	理由
`package-lock.json`	`--theirs`で受け入れ	`npm install`で再生成
`yarn.lock`	`--theirs`で受け入れ	`yarn install`で再生成
`pnpm-lock.yaml`	`--theirs`で受け入れ	`pnpm install`で再生成
`*.sum`（Go）	`--theirs`で受け入れ	`go mod tidy`で再計算

コードファイルのコンフリクト: 止まる勇気

コードファイルでコンフリクトが起きた場合、dev-integrateはマージを中断してユーザーに報告します。

{
  "integration": {
    "status": "failed",
    "failed_at_task": "task2",
    "error": "unresolvable merge conflict",
    "conflict_files": ["src/auth/handler.ts"]
  }
}

型チェックと統合テスト

マージが完了したら、プロジェクトの型チェックと統合テストが自動で走ります。

# プロジェクトタイプを自動検出
if [ -f "tsconfig.json" ]; then npx tsc --noEmit
elif [ -f "pyproject.toml" ]; then mypy .
elif [ -f "go.mod" ]; then go vet ./...
elif [ -f "Cargo.toml" ]; then cargo check
fi

# その後、dev-validateで統合テスト
Skill: dev-validate --worktree $MERGE_WORKTREE

flow.json: 並列パイプラインの進捗追跡

並列開発のオーケストレーション全体を追跡するのがflow.jsonです。

{
  "version": "1.0.0",
  "issue": 42,
  "status": "implementing",
  "subtasks": [
    {
      "id": "task1",
      "scope": "認証モジュール",
      "files": ["src/models/user.ts", "src/models/user.test.ts"],
      "status": "completed",
      "actual_files_changed": ["src/models/user.ts", "src/models/user.test.ts"],
      "checklist": [
        { "item": "Userスキーマ定義", "done": true },
        { "item": "マイグレーション追加", "done": true }
      ]
    },
    {
      "id": "task2",
      "scope": "認証エンドポイント",
      "files": ["src/routes/auth.ts", "src/routes/auth.test.ts"],
      "depends_on": ["task1"],
      "status": "in_progress",
      "checklist": [
        { "item": "POST /auth/login 実装", "done": true },
        { "item": "JWT検証ミドルウェア", "done": false }
      ]
    }
  ],
  "contract": {
    "branch": "feature/issue-42-contract",
    "files": ["src/types/auth.ts"]
  },
  "integration": {
    "status": "pending"
  }
}

なぜファイルベースなのか

flow.jsonがファイルで永続化されている理由は2つあります。

書き込み権限:
  flow.json           ← dev-flow, dev-decompose, dev-integrateのみ
  kickoff.json (各WT) ← 各サブエージェント（自分のworktreeのみ）

読み取り:
  flow.json           ← 全サブエージェント（参照のみ）
  kickoff.json        ← dev-flow（集約のため）

ステータスの遷移

analyzing → decomposing → implementing → integrating → pr → iterating → completed

各フェーズの完了条件が明確なので、途中で中断しても「次は何をすればいいか」がflow.jsonを見ればわかります。

Agent Teams との使い分け指針

観点	worktree並列（dev-decompose）	Agent Teams
得意パターン	ファイル分割可能な実装タスク	リアルタイム協調が必要な調査タスク
コンフリクト	ファイル境界で構造的に回避	同じファイルを触る可能性あり
コスト	worktree数 x dev-kickoff	エージェント数 x ターン数
状態共有	flow.json（ファイルベース）	SendMessage（リアルタイム）
適用例	認証+API+UIの3モジュール実装	バグ調査、コード監査、インシデント対応
フィードバック	統合時にまとめて検出	調査中にリアルタイムで方向転換

経験則: 「分けて、それぞれ作って、最後に合わせる」ならworktree並列。「みんなで同じものを見ながら、発見を即座に共有する」ならAgent Teams。

全体フロー: dev-flow --parallel

ここまでの仕組みを束ねるのがdev-flow --parallelです。

/dev-flow 42 --parallel

Step 1: dev-issue-analyze（要件分析）
    ↓
Step 2: dev-decompose（自動タスク分解）
    ├── contract branch作成・型定義コミット
    ├── worktree x N 自動作成
    └── flow.json生成
    ↓
Step 3: 分解結果チェック
    └── subtask_count == 1 → single modeにフォールバック
    ↓
Step 4: dev-kickoff x N（並列実装）
    ├── Batch 1: [task1, task3] ── 独立タスクを並列
    └── Batch 2: [task2] ── task1完了後に実行
    ↓
Step 5: 結果集約（kickoff.json → flow.json）
    ↓
Step 6: dev-integrate（統合）
    ├── トポロジカルソートでマージ
    ├── 型チェック
    └── 統合テスト
    ↓
Step 7: git-pr（PR作成）
    ↓
Step 8: pr-iterate（セルフレビューループ）

【Claude Code】worktree並列開発の自動タスク分解と統合 - dev-decomposeで「分けて、束ねる」を設計する

この記事で学べること

前提知識

手動タスク分解の3つの限界

1. ファイル重複による確定コンフリクト

2. 共有型の不在による型エラー地獄

3. 統合テストの後回し

dev-decompose: ファイル境界分析による自動タスク分解

核心のルール: 1ファイル = 1タスク

依存グラフの構築

テストファイルの同居ルール

フォールバック: 分解しない勇気

contract branch: 共通型定義で並列ワーカーの整合性を担保する

仕組み

contractに含めるもの / 含めないもの

contractが不要なケース

git-prepare: worktree自動作成と環境同期

dev-integrate: マージ・型チェック・統合テストの自動パイプライン

パイプラインの流れ

トポロジカルソートによるマージ順序

自動解決可能なコンフリクト

コードファイルのコンフリクト: 止まる勇気

型チェックと統合テスト

flow.json: 並列パイプラインの進捗追跡

なぜファイルベースなのか

ステータスの遷移

Agent Teams との使い分け指針

全体フロー: dev-flow --parallel

まとめ

あわせて読みたい

この技術が解決した業務課題

【自社導入事例】ブログ運用を完全自動化 - GitHubリポジトリから記事・サムネイル・SNS投稿まで

【AI採用管理】Gemini API × Next.jsで書類選考を自動化した受託開発事例

【AIシフト管理】AIが提案して店長が決める - 「全自動が不安」なサロンのためのシフト最適化

関連記事

この技術、実際の現場ではこう使われています

【Claude Code】worktree並列開発の自動タスク分解と統合 - dev-decomposeで「分けて、束ねる」を設計する

この記事で学べること

前提知識

手動タスク分解の3つの限界

1. ファイル重複による確定コンフリクト

2. 共有型の不在による型エラー地獄

3. 統合テストの後回し

dev-decompose: ファイル境界分析による自動タスク分解

核心のルール: 1ファイル = 1タスク

依存グラフの構築

テストファイルの同居ルール

フォールバック: 分解しない勇気

contract branch: 共通型定義で並列ワーカーの整合性を担保する

仕組み

contractに含めるもの / 含めないもの

contractが不要なケース

git-prepare: worktree自動作成と環境同期

dev-integrate: マージ・型チェック・統合テストの自動パイプライン

パイプラインの流れ

トポロジカルソートによるマージ順序

自動解決可能なコンフリクト

コードファイルのコンフリクト: 止まる勇気

型チェックと統合テスト

flow.json: 並列パイプラインの進捗追跡

なぜファイルベースなのか

ステータスの遷移

Agent Teams との使い分け指針

全体フロー: dev-flow --parallel

まとめ

あわせて読みたい

この技術が解決した業務課題

【自社導入事例】ブログ運用を完全自動化 - GitHubリポジトリから記事・サムネイル・SNS投稿まで

【AI採用管理】Gemini API × Next.jsで書類選考を自動化した受託開発事例

【AIシフト管理】AIが提案して店長が決める - 「全自動が不安」なサロンのためのシフト最適化

関連記事

この技術、実際の現場ではこう使われています