2026-09-04 · claudecode · ai · github · 個人開発

Claude Code に5人格を分担させて並列開発する

Claude Code に大きめの依頼をすると、こうなりませんか。

認証まわりを頼んだのに、ついでにエラーハンドリングの共通化まで入っている
差分が 40 ファイルあり、全部読む気力が湧かないので雰囲気で承認する
3 日後、なぜこの実装になっているのか自分でも説明できない
並列で走らせたいが、競合が怖くて結局 1 本ずつ回している

3 ヶ月で個人アプリを 10 本作り、うち 2 本を App Store に出す過程で、この問題に一通りぶつかりました。その結果たどり着いた構成を書きます。

結論から言うと、能力の問題ではなく権限設計の問題でした。

何が起きているのか

1 つの人格に、設計も実装もレビューもマージもやらせているからです。

自分で決めた設計を自分で実装し、自分でレビューして自分でマージする。どこにも歯止めがありません。人間のチームなら、この構成は誰も許可しません。

責務を分けて、権限を落とす

人格	できること	できないこと
Architect	Issue の作成・分割	コードを書く
UI Designer	UI 仕様書を書く	コードを書く
Coder	担当 Issue の scope 内だけ変更	scope 外を触る、マージする、造形を決める
Reviewer	レビューとマージ	実装する、コンフリクトを解消する
Conflict Resolver	コンフリクト解消	マージする、呼ばれる前に動く

どれも同じモデルです。 賢さに差はありません。違うのは何をしてよいかだけ。

なぜそれで結果が変わるのか。AI は与えられた文脈の中で、もっともらしい次の手を選びます。「ログイン機能を作って」とだけ言われたら、関係しそうなことを全部やるのがもっともらしい。「src/auth/** の中だけを変更して、この 3 つの受け入れ条件を満たせ」と言われたら、もっともらしい次の手はまったく別のものになります。

制約が文脈を作り、文脈が出力を決めます。

全体の流れ

依頼 → [Architect] Issue に分割（scope が重ならない組を作る）
         │
         ├─ [Coder] issue/12-xxx ─┐
         ├─ [Coder] issue/13-yyy ─┤ 並列
         └─ [Coder] issue/14-zzz ─┘
                                   │ PR ごとに1件ずつ
                                   ▼
                            [Reviewer] 受け入れ条件と scope を確認 → マージ
                                   │
                                   └─ コンフリクト → [Conflict Resolver] → Reviewer

実際の設定

.claude/agents/architect.md はこうです。

---
name: architect
description: Use to turn a feature request into GitHub issues for
  issue-driven parallel development. Defines per-issue scope (owned paths),
  dependencies, branch names, and acceptance criteria. Never implements code.
tools: Bash, Read, Grep, Glob
model: inherit
---

あなたは **設計者（Architect）** です。コードは書きません。
あなたの仕事は「安全に並列実行できる単位に Issue を分割すること」です。

## 呼ばれたときにすること

1. 依頼内容を読み、必要な作業を洗い出す。
2. 作業を **1 Issue = 1 scope = 1 ブランチ** に分割する。
   - scope はできるだけ狭く、他の Issue と重ならないようにする。
   - 重ならない Issue 同士は「並列着手グループ」としてまとめる。
3. gh issue create で以下を必ず含める。
   - Scope: 担当してよいファイル/ディレクトリのパス
   - Branch: issue/<番号>-<slug>
   - Depends on: 依存 Issue 番号（なければ「なし」）
   - 受け入れ条件: Reviewer が判定に使えるレベルで具体的に

## 守ること

- 実装コードやテストコードを書かない。
- scope が重複する Issue を同じ並列グループに入れない。

Coder 側には、これを書いています。

- 自分が担当していない Issue のファイルやブランチには触れない。
- 自分で main にマージしない（マージは Reviewer のみ）。
- コンフリクトが起きても自己判断で解消しない。
- Scope 外のファイルを変更しないと実装が成立しない場合は、変更を止めて
  「Scope 外の変更が必要」という報告を返す。

最後の 1 行が肝です。Coder が黙って範囲を広げると、 「Architect が分割を間違えた」というシグナルが消えます。

結果の大半は scope の切り方で決まる

正直に言うと、人格の設定より Issue の切り方のほうが効きます。

共有ファイルを 1 つの Issue に集める

実際に衝突するのは、たいてい次のファイルです。

ルーティング定義
型定義の集約ファイル
DI コンテナ、エントリポイント
package.json、マイグレーションのインデックス

複数の Issue がこれを触る設計にすると、必ずコンフリクトします。先に共有ファイルだけを変える Issue を立てて、他をそれに依存させます。

Issue #10  Scope: src/routes/index.ts        （ルート定義だけ先に追加）
Issue #11  Scope: src/pages/settings/**      Depends on #10
Issue #12  Scope: src/pages/billing/**       Depends on #10

これで #11 と #12 は並列に走れます。#10 は小さいので早く終わります。

受け入れ条件は判定可能な形で書く

Reviewer は受け入れ条件だけを根拠に判定します。判定できない書き方をすると、レビューが素通りになります。

書き方	判定
「ログイン機能が正しく動くこと」	判定不能
「未登録メールでログインすると 401 と `USER_NOT_FOUND` を返す」	判定可能
「パフォーマンスを改善すること」	判定不能
「一覧の初期表示が 200 件で 500ms 以内」	判定可能

機能で縦に切る

「モデル層の Issue」「ビュー層の Issue」という切り方は、依存が一直線になるので並列に走りません。

並列実行でハマった 2 点

1 メッセージで同時に起動しないと並列にならない

（NG）「coder で Issue 12 をやって」→ 完了を待つ →「13 をやって」
（OK）「Issue 12, 13, 14 を coder で並列に実装して。
       1 メッセージ内で 3 つの Agent 呼び出しを同時に発行すること」

呼び出しを分けた時点で直列です。ここは最初かなりの時間を無駄にしました。

マージは直列にする

実装は並列でも、マージは 1 件ずつです。3 つ同時にマージすると、それぞれ単体では正しくても組み合わせで壊れたときに切り分けができません。結局 3 つとも調べ直すことになり、直列より遅くなります。

並列数は 3〜4 本が実用的な上限でした。制約は AI 側ではなくレビュー側にあります。

作業ツリーを分ける

scope を守っていても、同じディレクトリで複数の Coder を動かすと事故が起きます。ビルド成果物が混ざり、片方の git checkout がもう片方を巻き込みます。

git worktree でファイルシステムのレベルから分離します。

git worktree add -b issue/12-upload ../worktrees/issue-12 main
git worktree add -b issue/13-profile ../worktrees/issue-13 main

共有されるのは .git のオブジェクトだけです。作業ツリーは複製されます。 手元で測ると、ソース 5,600KB のリポジトリに作業ツリーを1つ足したとき、増えたのは 5,608KB でした（.git 側の増分は 44KB）。node_modules も共有されません。つまり並列させる本数だけ、ソースと依存関係のぶんディスクを使います。

このやり方が向かないとき

正直に書いておきます。これはオーバーヘッドです。

探索・プロトタイプ（受け入れ条件を書けない段階）
1 ファイルで完結する変更（タイポ修正に PR を通す意味はない）
依存が本質的に一直線の作業（分割しても並列にならない）
30 分で終わる作業

見合うのは、3 本以上を同時に走らせたいときと、後から履歴を追えることに価値があるときだけです。

そしてもう 1 つ限界があります。Reviewer は同じモデルです。 モデルが体系的に持っている誤り、たとえばあるライブラリの API を一貫して間違えて覚えている場合、Coder が間違え、Reviewer も正しいと判定します。

対処は、受け入れ条件に実行可能な検証を入れることです。「テストが通ること」は、モデルの思い込みを外部から検証できる数少ない手段です。

Claude Code に設計・実装・レビューを別々の人格として分担させ、GitHub Issue とブランチを軸に並列開発を回すための設定一式を MIT で公開しています。コピーして ./setup.sh を叩けば動きます。技術スタックには依存しません。

https://github.com/quintetkit/quartet

このワークフローだけで実際にツールを 1 つ作りました。Issue の分割から PR、レビュー、マージまで記録が全部残っています。うまくいかなかった箇所も消していません。

https://github.com/quintetkit/mdlinkcheck

UI 設計人格・レビュー基準・Issue 単位の並列実行スクリプト・実践ガイド 10 章を足したものは製品ページにあります。

この運用そのものを配っています

4 人格版 Quartet は MIT で無料公開しています。UI 設計人格・レビュー基準・ Issue 単位の並列実行スクリプト・実践ガイド 10 章を足した Quintet は有料版です。

無料版を見る製品ページ