swarm-implement

name	swarm-implement
description	実装・検証層の Maker/Checker 分離ループ。トリガー: 「実装して」「修正して」「このレポートを実装に落として」 「秘書レポートの Priority Queue を消化して」など、vdaas/vald または kpango/dotfiles でのコード変更タスク全般。 境界条件: アーキテクチャレベルの意思決定が未確定なら先に人間へ /swarm-architect の招集を要請する。 マージ・デプロイ・破壊的変更は本 skill では行わず swarm-release-gate へ引き継ぐ。 並列実装 (2 タスク以上同時) は worktree 隔離必須。1 タスクの修正ループは最大 5 試行（3 試行目・Permanent エラー・失敗シグネチャ 2 回連続一致のいずれか早い方で Fixer へ切替）で、超過時は @fix_plan.md に状況を 書き出して停止し人間へ報告する。
allowed-tools	["Read","Edit","Write","Bash","Grep","Glob","Agent","Skill","TaskCreate","TaskUpdate","TaskList"]
user-invocable	true
disable-model-invocation	false

swarm-implement — Maker/Checker 分離実装ループ

設計根拠は SWARM.md §2・§3・§8 の Deep Research 結果を参照。要点: (1) Maker (Sonnet) と Checker (Opus) は 同一ベンダー系列であり verifier 独立性には理論的限界がある → 決定論的ツール（lint/test）を第一権威とし Checker は補助 heuristic として扱う。(2) Checker は Maker と討論しない — 仕様＋diff のみを見て単発判定する。 (3) 5 試行のうち回復の大半は 3 試行目までに集中するというデータがある → 3 試行目で仮説そのものを疑う。 (4) ループは Plan（PLAN フェーズ）→ Action（Maker）→ Observe（実挙動の観察）→ Verify（Checker・並行レビュー・ 決定論的検証）のサイクルであり、静的検証だけでなく実際に動かして観察する Observe を独立ステップとして持つ。

前提（開始前に必ず実施）

1. プロジェクトルートの AGENTS.md と @fix_plan.md を読む — 同一エラーへの同一対処の繰り返しを防ぐ。 同一根本原因の学びが 2 回目に登場していたら、それが機械化チェック（hook/lint/test）に昇格済みか確認する （SWARM.md §5）。未昇格なら、実装より先にその機械化を行う。

2. タスクが 2 件以上並列なら、タスクごとに worktree を割り当てる:

   ~/.claude/skills/swarm-implement/scripts/worktree-alloc.sh <task-slug>   # 出力 = worktree パス
   

3. タスクごとに一意な task-id（例: vald-fix-agent-ngt-20260713）を決める。

複雑度ガード（実行方式の決定、旧 dig 統合）

Maker を起動する前に、まずタスクをこの表で分類する。trivial なタスクに Maker/Checker のフル分離を 起動しない（オーバーヘッドがメリットを上回る。swarm-loop の Quick モードは基本的にここが trivial/simple）:

複雑度	判定基準	実行方式	TDAD
trivial	1 ファイル・15 行以下・新規ロジックなし（設定変更・定数・リネーム等）	オーケストレーター（呼び出し元）が直接編集し、Stop/PostToolUse hook の検証のみで完了	不要
simple	30 行以下・1 関数変更・既存パターン踏襲	Maker(sonnet) 単体 + 軽量 Checker（1 回判定、並行レビューは省略可）	任意
standard	複数ファイル or 新規ロジック導入	フル Maker/Checker 分離（本セクション以下の手順どおり）	必須
complex	複数システム or 新規抽象化 or アルゴリズム設計	フル Maker/Checker 分離＋着手前に実装計画のみ書かせて承認を得る（下記 complex 計画レビュー）	必須

complex の計画承認は、Fable スポット計画レビュー（SWARM.md §1 スポット判断層・トリガー 3）を第一候補と する: budget-guard.sh --fable <task-id> --mission=<slug> が許可すれば swarm-architect スポット診断 モードで実装計画をレビューさせる。FABLE_BUDGET_EXCEEDED の場合は従来どおり人間（Interactive）または Checker(opus)（Mission）の承認にフォールバックする。

standard/complex では以下の TDAD Iron Law を適用する: 本番コードを書く前に失敗するテストを書く。 テストなしに本番コードを書いたら削除して最初からやり直す。例外なし。RED → Verify RED → GREEN → Verify GREEN → REFACTOR → Coverage 80%+ の順を踏む（下記 Step 0 の Test Maker が RED を担当）。 タスク記述は task-template.md（本ディレクトリ）を参照する。RED/GREEN/REFACTOR 各段階での git checkpoint コマンド例・言語別カバレッジ計測コマンド・共通 Output Schema を定義済み。

ループ（1 試行 = 以下の 1 周、最大 5 試行・3 試行目でソフトチェックポイント）

各試行の頭で予算を消費する:

~/.claude/skills/swarm-implement/scripts/budget-guard.sh <task-id> 5
# exit 1 (BUDGET_EXCEEDED) なら即停止 → @fix_plan.md に軌跡を書き出して人間へ報告

0. Test Maker（standard/complex は必須、simple は任意、trivial はスキップ） — Code Maker より先に 独立スポーンしてテストケースだけを table-driven（golang-testing / rust-testing / python-testing skill 準拠）で先行記述させる（実装させない・TDAD の RED を担当）。これにより秘書レポートの仕様の曖昧さを 実装前に顕在化させる（MAST (i)(ii) 対策）。テストで機械判定不能なタスク（定型的な設定変更・ドキュメント 更新等）は複雑度に関わらずスキップしてよい。
1. Maker (model: sonnet) — Agent で独立スポーン。入力は秘書レポートの該当項目＋仕様（＋ Test Maker が いれば先行テスト）のみ。
   • vald: 既存 make ターゲット経由でのみビルド・生成（Vald Law 遵守。hooks が強制）。
   • dotfiles: .hadolint.yaml の ignored ルールを尊重。インストールは make ターゲット経由。
   • 出力: 変更 diff の要約・自己評価と自信度（high/medium/low）・実行した検証コマンドの生の標準出力。 「テストが通りました」等の prose のみの申告は evidence として無効（fail-plausible 対策。SWARM.md §6）。
   • 禁止: テストが失敗するからといってアサーション・許容誤差・スキップ指定を弱める/削除することでグリーン化 すること。それは failure を隠蔽しただけで解決していない（データの完全性。SWARM.md §6）。テスト自体の修正が 必要な場合は「なぜテストの期待値が誤っていたか」を Checker に説明できる根拠を添える。
   • standard/complex タスクでは新規コードのカバレッジ 80%+ を目安にする（TDAD の REFACTOR 完了条件）。
2. Checker (model: opus) — Maker とは独立コンテキストで Agent スポーン。入力は「仕様＋ git diff」 のみ（Maker の自己評価・自信度・言い分は渡さない）。
   • プロンプトは反証指向:「この diff が仕様を満たさないケース・壊すケースを探せ。不確かなら不合格とせよ」。
   • 討論させない: Checker の判定は 1 回で確定させる。不合格なら理由を返し、Maker への再指示は次試行として ループを回す（Checker コンテキスト内で Maker と往復させない — debate はバイアスを増幅させる、SWARM.md §2）。
   • 判定は必ず MAST 3 分類のどれに当たるかを添えさせる: system design issue / inter-agent misalignment / task verification failure。分類が (i)(ii) なら swarm-secretary の仕様構造化や swarm-architect 招集の 要否を CHECKPOINT に伝える（Checker を強化するだけでは直らないカテゴリのため）。
   • 合格判定は Checker のみが出せる。Maker の「完了しました」は判定材料にしない。
   • 判定行の強制: Checker・並行レビューへのプロンプトには「最終行に VERDICT: PASS|FAIL（レビュアーは REVIEW: APPROVE|REQUEST_CHANGES）を必ず明示せよ」を含める。判定行を含まない報告は判定として無効 （prose のみの合否は評価対象にしない — SWARM.md §6）であり、SendMessage で当該エージェントに判定行を 再要求する（完了済みエージェントも resume されトランスクリプト文脈を保ったまま回答できる。再スポーン しない）。プロンプト強制のみでは省略が再発することが 2 ミッションで実証済み（2026-07 vald e2e-benchmark-integration・2026-07-21 fable-spot-routing）。
   • 並行レビュー: グローバル CLAUDE.md の方針に従い、Checker と並行して独立スポーンする（Checker の代替 ではなく追加のレンズ）:
     • 非自明な変更全般 → code-reviewer サブエージェント（品質・保守性・言語別の落とし穴）。
     • vald 配下の変更 → vald-reviewer サブエージェント（Vald Law・config 同期・K8s リソース規約）。
     • domain タグが認証・シークレット処理・ネットワーク境界（gateway 等）に触れる → security-audit サブエージェント。Checker とは独立に「不合格」を出せる（cross-family ではないが視点の異なる heuristic として、intra-family verifier の限界を補完する。SWARM.md §2）。
3. 決定論的検証（最終権威）:
   • vald: make test/pkg 等の既存ターゲット、dotfiles: JSON/hadolint/zsh -n。
   • hook の結果と Checker 判定が食い違う場合は hook を優先する。Checker が「合格」でも hook が失敗を 報告したら不合格として扱い、Checker には矛盾点を再提示して再判定させる。再判定でも矛盾が解消しない 場合は Fable スポット診断（SWARM.md §1 トリガー 4。起動前に budget-guard.sh --fable 必須）で 「なぜ食い違うか」の原因のみを診断させ、その診断書を添えて Checker に最終再判定させる — スポット診断は 裁定・判定の上書きをしない（hook 第一権威は不変）。
4. Observe（実行面のあるタスクのみ）: 静的な lint/test は既知の回帰は防ぐが新規の失敗モードは検知しない （SWARM.md §8）。プロダクトコードのように実際に動かせる変更では、verify skill で変更後の挙動を 実際に動かして観察してから完了処理へ進む。テスト・ドキュメントのみの変更で駆動できる実行面がない場合は スキップしてよい。
5. 不合格時のエラー分類（リトライ前に判定、旧 dig の Circuit Breaker 由来の原則）:
   • Transient（ネットワーク・レート制限・タイムアウト）→ 通常の次試行として扱ってよい。
   • Permanent（存在しないシンボル・型不一致・構文エラー・同一失敗シグネチャの繰り返し）→ 単純な リトライで直る見込みが薄いため、試行回数に関わらず即座に Fixer を起動する（下記）。
   • 失敗シグネチャ（エラー種別＋失敗箇所）を試行間で比較し、2 回連続で一致したら（3 試行目を待たず） 即 Fixer に切り替える（無進捗の早期検知）。
6. 判定集約: Checker・並行レビュー（該当する場合）合格 かつ 決定論的検証パス かつ（該当する場合） Observe で異常なし → 完了処理へ。いずれか不合格 → 上記分類に従い次試行または Fixer へ。

Fixer 呼び出し（ソフトチェックポイント）

トリガー: 3 試行消費、または Permanent エラー、または 失敗シグネチャの 2 回連続一致のいずれか （早い方を優先する。3 試行を待たずに無進捗を検知したら即座に切り替える）。同じ Maker コンテキストで試行を 継続すると、失敗履歴の蓄積で思考が固定化する（「理解負債」）。これを断ち切るため、新規の debugger サブエージェント（Agent tool, subagent_type: "debugger", model: "sonnet" を明示）を Fixer として 起動する（debugger の frontmatter は model: inherit のため、明示を怠ると Fable セッションでは暗黙に Fable を消費しスポット判断層の回数制限を迂回してしまう — SWARM.md §1 ルーティング規則）:

• Fixer への入力は「現在のコード（diff ではなく最終状態）＋直近のエラー出力」のみ。過去の試行履歴・Maker の 弁明・これまでの対処一覧は渡さない（クリーンな Fixer コンテキストで根本原因を再特定させるため）。
• Fixer には強制内省テンプレートで根本原因を出力させる: What failed? / Root assumption that was wrong? / Specific fix (not "try harder")? / Repeating the same mistake as a prior attempt?
• Fixer の結論（根本原因の再診断）を新しい仮説として次の Maker 入力に反映する。
• Fixer 失敗後の Fable 最終診断（SWARM.md §1 トリガー 1）: Fixer 自身も根本原因を特定できない （診断が「不明」または検証可能な仮説の域を出ない）場合、ESCALATE / BUDGET_EXCEEDED として人間へ報告する 直前に Fable スポット診断を 1 回だけ挟んでよい:
  1. budget-guard.sh --fable <task-id> --mission=<slug> を通す（exit 1 なら即 ESCALATE、Fable は使わない）。
  2. swarm-architect スポット診断モードを起動（prompt に [fable-spot:<task-id>] を含める — hook が grant を task 束縛で照合する）。入力は「現在のコード＋直近のエラー生出力＋仕様」のみ （Fixer と同じクリーンコンテキスト原則）。
  3. 診断書の「実装介入の要否」が「必要」の場合（このルートは高難易度ゲートを常に満たす）、次試行の Maker を model: 'fable' で起動してよい（Fable Maker）。同一スポット消費の継続であり mission 枠は追加消費 しない: budget-guard.sh --fable-maker <task-id> で継続 grant を発行し（base spot の消費実績を機械的に 検証、無ければ FABLE_MAKER_NO_BASE で拒否・継続も 1 回のみ）、起動 prompt に [fable-spot:<task-id>-maker] を含める。Fable Maker の成果物にも判定集約（Checker(opus)・ 並行レビュー・決定論的検証）を例外なく適用する — Fable の自己申告では完了させない。
  4. スポット診断でも解けなければ従来どおり ESCALATE（診断書を @fix_plan.md の軌跡に添付し、人間の /swarm-architect フル設計モード招集の判断材料にする）。
• それでも収束しない場合、Fixer の再診断結果を MAST 分類で振り分ける:
  • system design issue（仕様・アーキテクチャそのものの不備）→ 設計判断が絡むため /swarm-architect 招集を swarm-loop に要請する。
  • inter-agent misalignment / 誤スコープ（実は独立した複数タスクへの分解が必要だった）→ 下記 「ネストされた /swarm-loop への分解提案」を検討する。
  • 同じ対処を漫然と繰り返さない（budget-guard の残り試行を空費しない）。

ネストされた /swarm-loop への分解提案

• Fixer は上記の inter-agent misalignment / 誤スコープの場合に限り、ネストされた /swarm-loop （Interactive scale 限定、Mission scale 禁止）の起動を提案できる。Fixer 自身はネストを起動しない — 判断材料の提示のみ。実際に起動するかどうかは、Fixer を呼び出した側（この試行ループを回している swarm-implement 本体 — コードを書く Maker ではない）が決定する。
• ネスト起動の条件:

  1. 深さはちょうど 1 段まで。親の @fix_plan.md から現在の depth を読み取り +1 して渡す:

     parent_depth=$(sed -n 's/^- depth: //p' "$(git rev-parse --show-toplevel)/@fix_plan.md")
     ~/.claude/skills/swarm-loop/scripts/mission-init.sh <slug> "<goal>" interactive "" "$((${parent_depth:-0} + 1))"
     

     （親が depth 省略 = 0 ならネスト先は 1。孫ネスト（depth ≥ 2）は mission-init.sh 自体が REFUSE して exit 1 にする — ここでの interactive 固定・""(self-improve-targets 不使用) 指定を省略すると scale が既定の mission になってしまうため必須。）

  2. 予算はツリー全体で共有する: budget-guard.sh <task-id> <max> --mission=<root-slug> --mission-max=20 （root-slug は最上位ミッション＝depth 0 のミッションの slug）。

  3. ネスト先は必ず既存の隔離済み worktree 内（worktree-alloc.sh で確保済み）で起動する。

• ネスト先は人間不在のため Phase 5 GATE に到達できない。内部タスクが blocked(design)/blocked(spec)/ blocked(budget) のいずれかに至った時点で ESCALATE し、その結果を呼び出し元（swarm-implement 本体）へ 構造化して返す。「完了しました」という自己申告をそのまま呼び出し元が信用しない（SWARM.md §6 と同じ原則を ネスト境界にも適用）。
• ネスト先での /swarm-architect 招集は禁止（人間不在のため無意味）。blocked(design) に至った場合は そのままネスト全体を ESCALATE させ、最終的に親を経由して人間へエスカレーションする。

完了処理

1. AGENTS.md に軌跡を 1 行追記: 日付 | タスク | 試行回数 | 結果 | 学び。同一根本原因が過去に一度出現していた 場合は、この完了処理で学びを prose のまま残さず機械化チェックへ昇格させる（SWARM.md §5）。

2. worktree を使った場合は回収（ブランチは保持）:

   ~/.claude/skills/swarm-implement/scripts/worktree-release.sh <worktree-path>
   

3. マージが必要なら人間に /swarm-release-gate の招集を要請して終了（自分でマージしない）。

予算超過時のフォールバック（必須）

@fix_plan.md に以下を書いてから停止する: 残タスク・全試行のエラー要約（生ログ含む）・試した対処・次に試すべき仮説。 その後 Stop する（swarm-stop-verify.sh が 5 回失敗時はエスカレーションとして通す）。

Memory Protocol（Skill 自己メンテナンス、AGENTS.md とは別軸）

AGENTS.md/@fix_plan.md（前提節参照）はプロジェクト単位のミッション軌跡であり、個々のタスクの 学びを記録する。これとは別に、~/.claude/skill-memory/swarm-implement/MEMORY.md には本 skill 自体の 運用パターン（vald/dotfiles 横断で繰り返し観測される Fixer 発火条件の傾向、複雑度ガードの判定基準が 実際には合わなかった事例、Checker が頻繁に不合格とする観点の偏り等）を蓄積する。開始前に存在すれば読み、 判断材料にする。存在しなければ気にせず進めてよい。

完了処理（上記「完了処理」節）の一部として、今回のタスク固有の詳細ではなく本 skill の運用一般に 通用する知見が得られた場合のみ追記する。プロジェクト固有の学びは引き続き AGENTS.md へ、本 skill 自体の運用知見のみここへ、と役割を分ける。一般化可能な学びが無ければ何も書かずに終える。