Claude Code をサブエージェントで分業させ、仕組みは台帳で育てる ― 架空サカスタのチケットサイトで学ぶ（番外 1）
はじめに
架空のサッカースタジアム「ペヌソニックスタジアム（通称ペヌスタ）」のチケット販売サイトを、遊び場として作っています。
紹介回の最後に「どう分担させ、どこで人が判断しているかは、番外編で書く予定です」と書きました。この記事がその番外編です。
ゴール裏年パス勢が、架空スタジアムのチケットサイトを作る理由 ― 架空サカスタのチケットサイトで学ぶ（0）
https://qiita.com/macchi23/items/5b9f5670c841f5c41be8
このリポジトリのコミットは 106 件あり、すべてに Claude の Co-Authored-By が付いています。
仕組みを入れた 10/3 から 10/27 までの 25 日間で 104 件です（どちらも 2026-10-27 時点）。
Claude Code で何か作るときは、いつもハーネス（役割ごとのサブエージェント、検証のスクリプト、運用のルール）を組んで、分業させる前提で始めます。
ただ、どんな役を置き、どのモデルを当てるかは、プロジェクトごとに考えています。
この記事では、ペヌスタ用に組んだ形を書きます。
この記事で書くこと:
- 誰に何を任せているか（委譲表とモデルの配分）
- 人が判断しているのはどこか
- 運用しながら仕組みを育てる「台帳」
- うまくいっていないこと
設定ファイルはリポジトリで公開しているので、そのまま読めます。
全体像: メインは分けて渡すだけ
Claude Code のメインのセッションは、作業を分解してサブエージェントに渡し、結果をまとめてユーザー（自分）と話す役に徹します。
メインが自分で手を動かしてよいのは、数行の自明な修正、ドキュメントの修正、git の操作だけです。
| 作業 | サブエージェント | モデル | 持たせている道具 |
|---|---|---|---|
| どこに何があるか探す | Explore | haiku | Read / Grep / Glob / Bash。リポジトリは変えない |
| 設計の比較、原因の究明、外部仕様の確認 | researcher | opus | Explore と同じ + Web（サブエージェントで Web を持つのはこの役だけ） |
| 実装とテスト | implementer | sonnet | 読み書き |
scripts/check.sh を回して結果を要約 |
verifier | haiku | Bash と Read だけ。直さない |
| 正しさのレビュー | code-reviewer | opus | Read / Grep / Glob / Bash。リポジトリは変えない |
| セキュリティのレビュー | security-reviewer | opus | Read / Grep / Glob / Bash。リポジトリは変えない |
1 つのステップは、だいたいこの順に流れます。
サブエージェントの定義は、Markdown 1 枚です。たとえば verifier はこれだけです。
---
name: verifier
description: scripts/check.sh を実行し、成否と失敗箇所の要約だけを返す。実装の後、レビューの前に使う。修正はしない。
tools: Bash, Read
model: haiku
effort: low
---
検証を担当する。`scripts/check.sh` を実行し、結果を要約して返す。ファイルは一切変更しない。失敗の修正もしない。
（以下、進め方と返す形式）
モデルは「下げる条件」と「上げる条件」で決める
既定は上の表のとおりで、呼び出すときに条件で変えます。
- implementer を haiku に下げる: 既存のパターンの踏襲 / 1〜2 ファイル / 設計判断なし / backend か文言・スタイルの修正、を全部満たすとき。Next.js の規約、トランザクション・同時実行、スキーマ変更、複数ファイルにまたがる変更は sonnet のまま
- implementer を opus に上げる: sonnet の実装が、同じ指摘でレビューから 2 回差し戻されたとき
- レビューを fable に上げる: 販売の整合性に関わる変更（二重販売の防止、仮押さえの期限、自由席の定員の同時実行制御、抽選、waiting room、決済の状態遷移）か、自分が明示したとき。今は fable がしばらく使えないので、opus の code-reviewer と security-reviewer を並列で走らせて代えている
全部をいちばん良いモデルにすると、使用量の上限にすぐ当たります。
なので、下げても結果が変わらないところ（探索、check、既存の形をなぞるだけの実装）を条件で下げて、浮いた分を外せないところ（設計とレビュー）に回しています。
ブリーフに書くことと、レビューに渡さないもの
サブエージェントは会話の文脈を持たないので、渡す依頼文（ブリーフ）にすべてを書きます。
- 目的 / 完了条件 / 対象ファイル / 既知の制約と除外済みの仮説 / 返してほしい形式
レビューには、仕様と diff の範囲だけを渡し、実装者の説明は渡しません。
実装者の「こう考えて作った」「確かめた」を先に読むと、レビューもその筋書きに乗ってしまいます。
実装者が前提にしたことは疑わなくなり、「確かめた」と書かれたことは自分で確かめなくなります。
仕様と diff だけを渡して、一から読ませています。
人が判断しているところ
任せているのは「手を動かすこと」で、次の 5 つは自分が決めています。
-
方針: 作業が 5 ステップ以上になるときは Plan Mode で始め、選択肢とトレードオフを出させてから選ぶ。
たとえば連載（2）の記事を書くとき、使われていない設定が見つかった。「経緯として書く」「一般論として書く」「先にコードを整理する」の 3 つから 1 つ選ぶ形で出てきたが、経緯として書くのとコードの整理を両方やると決めた - 外に出る操作と、壊れる操作: 実 AWS への書き込み（deploy・destroy、S3 への同期、Athena の DDL）と開発 DB の作り直しは、メインが確認を取ってから実行する。サブエージェントは実 AWS には synth と読み取りまで。コミットは自分が指示したときだけ
- 画面の確認とマージ: 大きめの作業はブランチで進め、自分がブラウザで確かめてから main にマージする
- 仕組みに足すもの: 後で書く台帳で「2 回起きたら提案」まで来たものを、足すかどうか決める
- 記事: 骨格は作らせるが、自分の言葉に書き直してから出す
いちばん人がやらないとまずいと思うのは、画面の確認です。
テストもレビューも通っているのに、実際に触ると「これは迷う」というところが出てきます。
使う人の目で見るのは、今のところ自分にしかできません。
最初から作り込まない: ハーネスの台帳
hooks（決まった操作で自動で走る処理）や skills（手順のまとまり）は、最初から作りません。
運用で困ったことを docs/harness-backlog.md という台帳に 1 行ずつ書き、同じことが 2 回起きたら仕組みに足すことを提案させます。足すかどうかは自分が決めます。
台帳には今 88 行あります（2026-10-27 時点）。
| 状態 | 件数 |
|---|---|
| 候補 | 67 |
| 採用 | 18 |
| 解消（仕組みではなくコードで直した） | 3 |
7 割強（65 行）が種別「定義修正」（エージェントの定義やブリーフの書き方の直し）です。
台帳から仕組みに戻った例
-
同じ依頼を 10 回書いたので、スキルにした: 「implementer → verifier → レビュー → 差し戻し → verifier → コミット」を、購入フローで 7 回、イベントログの出力で 3 回、毎回ブリーフに書いていた。これを
/stepというスキルにまとめた -
記事の手順も、2 回目でスキルにした: 記事の素材にする開発メモは、後の機能追加で直った話や古い件数が残っていることが多い。連載（2）と（3）で 2 回続けて「researcher にコードと照合させる」とブリーフに書いたので、素材集めから公開後の後片付けまでを
/articleというスキルにした。この記事も/article X-1で進めている - implementer の返却から、implementer の定義へ: 同時実行のテストを書くステップが 3 回続き、implementer が 3 回とも返却の「気づき」欄に「ブリーフにテストの書き方があれば探索が減る」と書いてきた。別の接続で行を握って待たされたかを測る、といった定石を implementer の定義に書いた
-
レビューの指摘から、check へ: macOS の bash 3.2 でしか起きない落とし穴（
$VARの直後に日本語を置くと変数名に取り込まれる、など）を、レビューが 2 ステップ続けて見つけた。定義に注意書きを足すのではなく、scripts/check.shに検査を足した
例外: 起きる前に入れたもの
リポジトリを public にしたあと、秘密情報の検査（gitleaks）を入れました。台帳のルールでは「起きてから」ですが、秘密情報は一度 push したら取り消せません。
これは自分の判断で、発生 0 回のまま採用しています。
Next.js 16: 学習済みの知識と違うものを書かせる
Next.js 16 は、モデルが学習した Next.js と規約が違います。
Next.js 自身がプロジェクトに AGENTS.md を書き出していて、「これはあなたの知っている Next.js ではない。書く前に node_modules/next/dist/docs/ の該当ガイドを読め」と書いてあります。
このルールを CLAUDE.md の必須ルールと implementer の定義に写しました。ほかにも次のような違いを、気づくたびに開発メモへ足しています。
- middleware は
proxy.tsに名前が変わった - キャッシュのガイドが 2 系統あり、このリポジトリの設定（Cache Components が無効）で読むべきなのは片方だけ
それでも、必読と書いたガイドを implementer が読まずに実装し、差し戻しで再指示しても読まなかったことがあります（台帳では候補のまま）。
新しいページを足すと型の生成（next typegen）を流すまで型検査が落ちる件は 2 回起きたので、check に組み込みました。
分けておいてよかった 2 つの例
最近の作業で、役を分けていたから見つかったものが 2 つあります。
記事の事実確認で、向きの逆転が見つかった
連載（2）の下書きで、「app と scheduler で PHP のパッチ版がずれた」話を、メインが逆向き（app が新しい方）に書いていました。
開発メモには 8.4.24 と 8.4.26 で起きたとだけあり、どちらがどちらか書いていなかったためです。
下書きを researcher に渡してリポジトリと突き合わせさせたら、当時のセッションログに残っていたレビューの結果から正しい向き（scheduler が新しい方）を見つけてきました。
check を通った検査が、すり抜けていた
gitleaks の最初の版は、Docker の中で動かす作りでした。implementer は自分で試して「止まる」ことを確かめ、check も通っていました。
ところが code-reviewer が実際に試すと、git commit -a と、git の worktree からのコミットで、秘密情報がそのまま通りました。
git がフックに渡す環境変数（一時インデックスを指す GIT_INDEX_FILE）がコンテナに届かず、worktree の本体もマウントの外で見えていなかったのが原因です。worktree ではコンテナ内の git が失敗しても、gitleaks は「漏れなし」で終わっていました。ホストで動かす作りに変えました。
check も、実装者の「確かめた」も嘘ではありませんでした。試した範囲では正しかっただけです。
「通った」は「正しい」ではなく、「試した範囲では大丈夫」という意味だと割り切って、範囲の外を試す役を別に置いておくのが大事だと思いました。
うまくいっていないこと
- 候補がたまる: 88 行のうち 67 行が候補のまま。却下は 0 件で、整理できていない
- 事故は起きた: implementer がテスト用の DB を指定し忘れて、開発 DB を作り直したことがある（合成データの生成器で作り直せたので実害は小さかった）。止める仕組みは、発生 1 回なのでまだ候補
- 報告せずに終わる: 長いコマンドをバックグラウンドに回した implementer が、結果を返さずに終わったことがある。定義には check をフォアグラウンドで回すよう書いてあったが、テストや生成のコマンドは対象外で、防げなかった。その場はブリーフに「すべてフォアグラウンド」と書いて通し、定義をどう直すかは候補のまま。同じ implementer は、結果を待つための監視ループもバックグラウンドで回していて、待ち先のファイルが消えたあとも 13 日間 3 秒おきに回り続けていた（セッションを閉じるときに気づいて止めた）
- 規則の理由が残っていない: 「レビューに実装者の説明を渡さない」のように、なぜそうするかが文書に書かれていない規則がある。この記事を書くために見直して気づいた
台帳と規則を、一度まとめて見直したいです。
似た候補はまとめ、もう起きないものは却下し、残す規則には理由を 1 行ずつ足す。
理由を書けないものは、外しても困らないものだと思っています。
まとめ
- メインは分解と統合だけ。作業は、道具とモデルを絞ったサブエージェントに渡す
- 人が決めるのは、方針、外に出る操作と壊れる操作、画面の確認とマージ、仕組みに足すもの、記事の言葉
- 仕組みは最初から作り込まず、台帳に書いて 2 回起きたら足す。ただし起きてからでは遅いものは先に入れる
設定はリポジトリの .claude/ と CLAUDE.md にあります。
シリーズの他の回:
- （0）ゴール裏年パス勢が、架空スタジアムのチケットサイトを作る理由
- （1）スタジアムの座席をどうテーブルにするか
- （2）コンテナの中の localhost は届かない
- （3）チケットの二重販売をどう防ぐか: 指定席はユニーク制約、自由席は行ロック
- （4）管理画面で座席の割当を変えるとき、購入とどう直列化するか
番外編:
この記事の骨格は Claude Code に作らせ、自分の言葉で書き直しています。記事中の数字（コミット数、台帳の件数など）は、手元のリポジトリで数えています。