課題: 仕様駆動・テスト駆動・パス厳守を毎回手作業で守れない
メインスレッドがコードを直接書くと、どこかが省略されやすい。
仕様書の参照が飛ぶ。 依頼内容から直接コードを起こすほうが速く、仕様に定義された境界条件やエラー処理が抜ける。結果として実装の解釈が揺れ、後のテストで「仕様に反している」と気づく。手戻りが発生する。
テストが後回しになる。 「実装を確認してからテストを書く」という順序が自然に生まれる。テスト駆動開発（TDD）の原則は知っていても、実装の進捗を確認したい心理が「次のステップ」としてテストを遅延させる。結果として境界条件や例外系のテストが不完全のまま本番に入る。
絶対パスの扱いが揺れる。 相対パスがコミットに紛れ込み、開発環境では動くが別環境では壊れる。メインスレッドは会話の流れの中で実装判断をする。その流れが「省略」のリスクを生む。個別の注意ではなく、構造的に省略を防ぐ仕組みが必要になった。
パターン定義: コード実装は必ず system-developer に委任
Synapse の CLAUDE.md には次のように定義している。
コード実装・テスト・バグ修正など開発系タスクは、メインスレッドで直接実装せず必ず
system-developerエージェント（グローバル定義）に委任する。仕様駆動・テスト駆動・パス厳守・自動品質チェックを強制するため。
Montage・Medallion にも同一の定義がある。
委任には3つのメカニズムが効く。
-
仕様書を起点に実装が始まる。
system-developerはspecs/配下の仕様書を参照してから実装に入る。ここが「仕様にどう書いてあるか」を確認するステップになり、解釈の揺れを防ぐ。メインスレッドが「依頼文から直接実装」するのに対して、委任は「仕様書を経由して実装」になる。 -
テストが先行する。
dev-testスキルと組み合わせることで TDD サイクルが自然に回る。仕様書から期待値を読み、テストケースを実装してから本体を書く。メインスレッドが省略しがちなテストファーストが委任によって強制される。 -
自動品質チェックが走る。 実装後に
dev-verifyスキルで動作確認・型チェック・ビルド確認が走る。「実装した」で完了にならず、「動くことを確認した」まで自律的に進む。
設計の核: 委任フロー と 例外判定基準
標準的な委任フロー
メインスレッドの指示は以下を含める：
Agent(
subagent_type="system-developer",
prompt="""
仕様書: specs/user-auth.md の「セッション検証」セクション
実装対象: src/middleware/auth.ts の validateSession() 関数
テスト: tests/unit/auth.test.ts のセッション検証ケース全て
パス扱い: すべて絶対パス（process.cwd() ベース）を使用
""",
)system-developer は内部で以下のステップを踏む：
- 仕様書を Read
- dev-test で期待値からテストケースを作成
- テストが green になるまで実装
- dev-verify で型・ビルド・動作確認
- 完了した diff をメインに返す
例外: 直接書いてよい判定基準
「必ず委任する」ルールには明示的な例外がある。判定軸は 「実装ロジックを含むか」 だ。
| パターン | ロジック | 判定 | 根拠 |
|---|---|---|---|
| 1行の定数値変更 | なし | 直接 | コミット前の型チェック、テスト実行で十分 |
| typo・コメント修正 | なし | 直接 | 構文チェック以上の確認不要 |
config/ の JSON/YAML 編集 | なし | 直接 | 設定ファイルはスキーマ検証で十分 |
ドキュメント（.md / CLAUDE.md） | なし | 直接 | ロジックではなく情報ドキュメント |
| ブログ記事本文 | なし | 直接 | 記事執筆はドキュメント扱い |
| if/for/function 追加 | あり | 委任 | 仕様確認・テスト・パス確認が必須 |
| API ルート追加 | あり | 委任 | 仕様書が起点、エラーハンドリングまで含む |
| データベース操作 | あり | 委任 | 機能テスト・統合テスト・マイグレーション検証必須 |
ロジックが含まれた瞬間、仕様との照合・テスト・パスの確認が必要になる。その段階で委任の価値が出る。
複雑なタスクは Opus に上書き
デフォルトの system-developer は Sonnet で動作する。設計判断が絡む複雑なタスクではモデルを上書きできる。
Agent(
subagent_type="system-developer",
model="opus",
prompt="実装方針の判断が必要。refs: specs/ 内の XXX を参照し、現在の YYY との互換性を判定した上で実装する",
)判定基準：
- Sonnet のまま: 仕様書が存在し、実装方針が決まっている。「どう実装するか」が明確
- Opus 上書き: 仕様書の複数の解釈が考えられる、既存コードとの互換性判断が必要、新しいパターンの導入判断が必要
Yakumo での適用例と定量的効果
Synapse での運用実績
Synapse（業務横断エージェント組織）では、2026年初頭から system-developer への全面委任を開始した。スコープ：エージェント実装、スキル実装、データパイプライン。
定性的には：
効果1: 仕様書が生きるようになった。 委任が起点になることで、仕様書の質が実装精度に直結するようになった。古い仕様書では精度が落ちる。この「精度の落ち」が自然な更新の動機になり、仕様書を書き続ける習慣が生まれた。結果として Synapse の specs/ は常に最新の状態に保たれている。
効果2: テストカバレッジが上がった。 dev-test スキルの TDD フロー経由では、テストなしで実装が通らない。結果として Synapse のテストカバレッジは に達した。
効果3: オンボーディングが楽になった。 新しいエンジニアが参加する際、「仕様書を読んで委任する」フローを学ぶだけで、品質を下げずに貢献できるようになった。### Montage での適用例
Montage（Remotion ベースの動画量産システム）では、コンポーネント実装と設定周りで委任を使い分けている。
- シーンコンポーネント実装: system-developer 委任（仕様書に Motion / Duration / Props が定義されているため）
- Remotion ライブラリ管理: 1行の upgrade は直接、アーキテクチャ変更は委任
落とし穴と学習
実運用での詰まりポイント。
落とし穴1: 委任のコンテキスト不足で精度が落ちる。
例：Montage の xxx コンポーネント実装を「カラーパレット対応してほしい」と短く依頼した際、system-developer はどの仕様書を参照すればよいかわからず、。改善後は「specs/design-tokens.md の Color System セクションと、config/montage/palette.json を参照」と明示したところ、で完了した。
学習: 委任の指示に「どの仕様書を見るか」「何のテストを通すか」「どのパスを使うか」を含めることで精度が跳ねあがる。短い指示は委任のオーバーヘッドを増やす。
落とし穴2: 全てを委任しようとして逆に遅くなる。
例：Medallion で Python パーサの xxx 定数値を 100 → 200 に変更するタスクを委任したところ、メインに返ってきたのは修正そのもの + テスト + 動作確認で 。直接修正なら 5 分だった。オーバーヘッドの価値がない案件だ。
学習: 1行の修正に委任のコンテキストを作ろうとすると、逆にコストになる。例外ルールを明示しておくことが「これは自分でやってよい」の判断を速くする。
トレードオフ: なぜ「全て委任」ではなく「ロジック有無で判定」か
3つの選択肢を検討した。
| オプション | 説明 | 利点 | 欠点 |
|---|---|---|---|
| A. 100% 委任 | すべてのコード変更を system-developer に委任 | 品質が最も均一化される | 1行修正のオーバーヘッドが大きい、スループットが落ちる |
| B. ロジック有無で判定（採択） | ロジックを含むなら委任、そうでなければ直接 | 品質と迅速性のバランス | 判定基準を毎回考える認知負荷、判断のぶれ |
| C. ケース・バイ・ケース | タスク難度で都度判断 | 最高の柔軟性 | 判断が属人化、品質のばらつきが最大、組織化不可能 |
現在の「ロジック有無で判定」を選んだ理由：
- 判定基準が客観的: ロジックを含むかは構文的に判定でき、解釈の余地がない
- 例外を明示できる: 「1行修正は直接」「設定ファイルは直接」と事前に定義できるため、運用時の判断が軽い
- スケーラブル: 新規エンジニアが参加する際、「ロジック含む = 委任」という単純ルールを学ぶだけで参加できる
- 品質と迅速性のバランス: 100% 委任より迅速で、C より品質が安定している
Synapse・Montage で1年運用した結果、このバランスが「実装品質を保ちながら スループットを維持できる」限界点だと判断している。
まとめ
メインスレッドが直接コードを書くと、仕様参照・テスト先行・パス厳守のどれかが省略されやすい。system-developer への委任は、この省略を構造的に防ぐ仕組みだ。
全プロジェクトで同一のルール（「ロジック有無で判定」）を CLAUDE.md に定義することで、実装品質の下限を上げることができた。ルールは単純だ：
- ロジックが含まれたら委任する — 仕様確認・テスト先行・パス厳守が構造的に入る
- そうでなければ直接書く — 1行修正のオーバーヘッドを避ける
- 例外を明示する — 判定の認知負荷を軽くする
- 複雑さで Opus に上書きできる — 難度に応じてモデルを柔軟に選べる
境界が明確なほど、判断は速く、運用は続く。
関連記事: