name: loop-design
version: "0.1.0"
description: やりたいことを1行で言うと、B 型 loop engineering の 7 要素 (context / feedback / verification gate / termination / error handling / state / cost guard) を埋めた loop spec をコピペ可能な形で生成する。生成した spec は現行 Claude Code の実行プリミティブ (Workflow ツール / /loop skill / ralph-loop plugin / claude -p) に落とせる骨格になる (旧 claude --goal は廃止)。10 件 failure mode (F1-F10) の対策フックも自動挿入。Hybrid モード: 1 行入力 → デフォルト埋めで一発出力 → 「ここを調整したい」場所だけ短く聞き直す。Use when ユーザーが「loop を作りたい / loop-design / 自走ループ書いて / Workflow 用の spec 作って / 7 要素埋めて / verification gate ありで」と言ったとき、または /loop-design を実行したとき。Loop engineering の理論背景は Cards/loop-engineering-autonomous-agents、失敗モード対策は Cards/loop-failure-modes-mechanism-2026 を参照。
Loop Design Skill — 7 要素を埋めた B 型 loop spec を生成する
何をするか
ユーザーが やりたいこと (1 行〜数行) を渡すと、現行 Claude Code の実行プリミティブに落とせる loop spec を生成する。実行先は Workflow ツール (推奨) / /loop skill / ralph-loop plugin / claude -p から、タスク特性で選ぶ。
⚠️ 旧版が前提にしていた claude --goal / --max-iterations は Claude Code 2.1.185 時点で存在しない。spec は「設計図」であり、上記プリミティブに転記して走らせる。
- B 型 (end-goal 駆動) のテンプレを基本にしつつ、A 型 (rigid な反復 =
ralph-loop) も実行プリミティブとして選択可
- 7 要素 + F1-F10 対策フック を構造として埋める
- デフォルト埋め先行、ユーザーが調整したい箇所のみ Hybrid で聞き直す
- 出力は markdown コードブロック 1 つ、コピペ即実行可能
1 行で
prompt engineering ではなく loop engineering を書く ための spec ジェネレータ。10 件 failure mode の地雷を踏まないように、verification gate と termination condition を機械判定可能な形に整える。
起動条件
/loop-design <やりたいこと> のスラッシュコマンド- ユーザーが自然文で「loop 書いて」「7 要素埋めて」「/goal 用の spec 作って」と言ったとき
- 既存 skill の改善案として「ここを自走化したい」と言ったとき
入力フォーマット
/loop-design "<やりたいこと 1 行>"
/loop-design "<やりたいこと>" --max-budget=5 --max-turns=30 --verifier=codex
/loop-design "<やりたいこと>" --interactive # 7 要素を 1 つずつ聞く
| オプション | default | 説明 |
|---|
| (positional) | (必須) | やりたいこと、自然文 1 行 (例: "テストが通るまで src/ を直す") |
--max-budget=<usd> | 5 | コストガード上限 ($USD) |
--max-turns=<n> | 30 | 最大ターン数 |
--verifier=<name> | (auto) | 別モデル verifier 指定。codex / gemini / none / (default: タスクから推定) |
| `--type=deterministic | non-deterministic` | auto |
--interactive | off | 7 要素を 1 つずつ聞き取り |
--no-fail-hooks | off | F1-F10 対策フックを挿入しない (シンプル版) |
出力フォーマット (テンプレート)
# Loop Spec: <slug>
## End Goal
<人間がドメイン知識で定義する到達点。機械的に判定可能な形>
## Termination Condition
- 完了: <Verification Gate を全部 pass>
- 失敗: <連続 N 回失敗 / cost > $X / 最大 M ターン>
## Verification Gates (決定的 ⊃ LLM、決定的を最後段)
### Stage 1 (LLM gate, 確率的)
- <judge model = Haiku 等、別モデル>
- <判定 prompt の骨子>
### Stage 2 (決定的 gate, 二値判定)
- <exit code / git status / regex / JSON schema>
## Feedback Loop
- 各サイクルで上記 gate を再実行
- 失敗時は stderr の最初の 50 行を context に戻す
## State Across Turns
- 進捗: .agent/progress.md (append-only)
- 試した修正: .agent/attempts.jsonl (同じ手を 2 回試さない、hash で dedup)
## Context Management
- auto-compact に任せ、PreCompact / SessionStart(source=compact) フックで CLAUDE.md と本 spec を再注入 (F1 対策)
- 動的タイムスタンプ・ツール順ランダム化を避ける (F10 対策)
## Error Handling
- ツール失敗 → 同じ引数で再試行禁止、代替経路を State に記録
- 壊れた状態を残さない (git stash / revert)
- F2 対策: test 結果は file 経由 (`npm test > test.log 2>&1 || true`)
- F3 対策: OAuth token は serialize 層に永続化
## Cost Guard
- 1 ループ最大 $<max-budget>、最大 <max-turns> ターン
- Tiering: heartbeat=Haiku 4.5 / main=Opus 4.8 / verifier=Haiku 4.5
- F6 対策: /cost を 5 ターン毎に check、超過で停止
## (Optional) Adversarial Verifier (non-deterministic 時)
- maker = Claude (現在のセッション)
- verifier = <別プロバイダ、e.g. Codex / Gemini>
- 別モデル投票で self-enhancement bias を回避 (F5 対策)
手順
Step 1: 入力解析
- positional 引数を やりたいこと として受け取る
- オプションを parse
- 何も無ければ
--interactive 扱いで「やりたいことは?」を 1 ターンだけ聞く
Step 2: タスク特性を推定 (3 軸)
| 軸 | 判定 | デフォルト推定 |
|---|
| A. 完了判定 | deterministic vs non-deterministic | テスト / コンパイル / git 系キーワード → deterministic、UI / 文章 / 仕様適合 → non-deterministic |
| B. mission-critical 度 | high / mid / low | 賃料査定 / 認証 / 金融 → high (autonomy slider 0.2)、社内ダッシュボード / PoC → low (slider 0.7) |
| C. 規模 | 1 file / 1 PR / repo 全体 | scope fence の粒度を決める (F8 対策) |
→ 不確実なら Hybrid 質問 (Step 4)。
Step 3: 7 要素 + F1-F10 対策を埋める
loop-engineering-autonomous-agents の 7 要素テンプレート + loop-failure-modes-mechanism-2026 の対策マトリクスを参照して埋める:
- End Goal = 入力をそのまま (測定可能な形に書き直し)
- Termination = max-budget / max-turns + 連続失敗回数 (default: 同一エラー hash 5 回 = F7 対策)
- Verification Gates = 推定タスク特性に応じて Stage 1/2 を組む (4 章 Pattern A-D, llm-as-judge-bias-patterns)
- Feedback = stderr 50 行を context 戻し
- State =
.agent/progress.md + .agent/attempts.jsonl
- Context Mgmt = auto-compact + PreCompact / SessionStart 再注入 (F1)
- Error Handling = git stash + 再試行禁止 (F2/F3)
- Cost Guard = max-budget + tiering (F6) + cost check 5 ターン毎
- (Non-deterministic 時) Adversarial Verifier =
--verifier 指定または auto 推定 (F5)
Step 4: Hybrid 質問 (default ON)
デフォルトで埋めた結果を一旦出力した後、以下を 1 ターンだけ聞く:
「以下のうち、調整したい箇所はありますか? (なければ 'OK' と回答してください)
- End Goal の表現
- Termination の閾値 (連続失敗回数 / max-turns)
- Verification Gate の Stage 2 (決定的 gate) の中身
- Cost guard の上限
- その他 (自由記述)」
ユーザーが調整指示を出したら反映、OK なら確定。
Step 5: 出力
最終 spec を コード block 1 つで出力。末尾に実行プリミティブの選択を併記 (template.md「実行プリミティブ」表に従う):
- Workflow ツール (推奨: 多段 / 決定的 / adversarial) — spec の End Goal/Gates/Termination を Workflow script に転記。budget=cost guard(F6)、pipeline=gates、parallel+agentType=adversarial(F5)
/loop (単一反復 / 定期) — /loop /<cmd> (self-paced) または /loop <interval> /<cmd> (定期)ralph-loop (A 型 rigid) — /ralph-loop "<task>" --max-iterations N --completion-promise "<完了文>"。旧 --goal の最近接代替claude -p — 1 ショット非対話
claude --goal は廃止済みのため出力しない。
フェーズ束縛ルール (phase → primitive、claude-code-loop-harness-orchestration-2026)
タスクが複数フェーズ (research/diagnose/fix/verify/develop 等) を持つとき、フェーズと7要素は直交する (フェーズ=何を / 7要素=どう制御)。各フェーズの落とし先は公式決定ルールで決める:
| フェーズの性質 | 落とす先 |
|---|
| 複数フェーズが文脈を共有 (plan→impl→test) / 反復改善が要る | メイン会話 |
| 自己完結・要約を返す・tool 制限したい | subagent (fresh isolated context) |
| 1会話で捌けない数 / 再実行可能に codify | Workflow (script が loop/state を保持) |
| 再利用可能な手順をメイン context で | skill |
⚠️ 「フェーズごとに subagent を用意」をデフォルトにしない。これは並列リサーチ fan-out には妥当だが、coding loop のベストとしては一次ソースの裏が無い (2026-06 deep research で refuted)。共有文脈の開発フェーズはメイン会話が公式の素直な答え。
⚠️ slash-command と skill は統合済み (.claude/commands/foo.md と .claude/skills/foo/SKILL.md は同義)。「subagent vs slash vs skill」でなく invocation control + execution context で選ぶ。
副作用フェーズ (/commit /deploy) は disable-model-invocation: true で人間ゲート化 (handoff ownership)。
Step 6: ログ
- 生成した spec を
.agent/loop-design-history/YYYY-MM-DD-<slug>.md に保存 (なければ作成)
- これで後から再利用 / 改善できる
デフォルト推定の対応表
タスクキーワード → タスクタイプ
| キーワード | type | verifier | mission-critical |
|---|
| テスト / test / pnpm test | deterministic | Haiku (Stage 1 で placeholder grep) | mid |
| コンパイル / tsc / build | deterministic | none (exit code のみ) | mid |
| migration / schema | deterministic | Codex (review) | high |
| UI / デザイン / Figma | non-deterministic | (人間 fallback 強推奨) | mid |
| ドキュメント / README | non-deterministic | Gemini (judge) | low |
| PR review / コードレビュー | hybrid | Codex (Pattern B) | mid |
| Inbox / ingest / PKM | deterministic | Haiku (Stage 1) | low |
| デプロイ / production / migration | deterministic | Codex + 人間 gate | high |
| バグ修正 / fix | deterministic | Haiku | mid |
Verifier 推定ロジック
--verifier 指定があればそれ- mission-critical = high → Codex 推奨 (Pattern B = Anthropic × OpenAI 別プロバイダ)
- 非 deterministic → Gemini or Codex 推奨
- それ以外 → Haiku (legibility tax 原則、llm-as-judge-bias-patterns)
F1-F10 対策フックの自動挿入
--no-fail-hooks が指定されない限り、以下を spec に自動挿入:
| Failure | 自動挿入する spec 行 |
|---|
| F1 Compaction 死スパイラル | "Context Management: auto-compact に任せ、PreCompact / SessionStart(source=compact) フックで CLAUDE.md と本 spec を再注入" (※ "PostCompact" は存在しないフック名) |
| F2 pipefail | "Error Handling: test 結果は file 経由 (npm test > test.log 2>&1 ‖ true)" |
| F3 MCP silent loss | "Error Handling: OAuth token は serialize 層に永続化、sanity check loop 内に" |
| F4 ロール配列破壊 | "公式 SDK (Claude Agent SDK) に寄せる、抽象化レイヤーを薄く" |
| F5 placeholder sneak | "Verification Gate Stage 1: placeholder grep (TODO ‖ return true ‖ ;\\s*$) 検出で reject" |
| F6 コスト暴走 | "Cost Guard: /cost を 5 ターン毎に check、超過で停止" |
| F7 無限ループ | "Termination: 同一エラー hash 5 回 → escalate" |
| F8 scope 暴走 | "Constraints: 1 ループの scope を 1 file / 1 function に fence" |
| F9 偽合言葉 | "Verification: 完了報告は output で証明 (file 内容 grep / git diff)" |
| F10 cache 破壊 | "Context Management: 動的タイムスタンプ / ツール順ランダム化を避ける" |
例
例 1: /loop-design "テストが通るまで src/ を直す"
→ 推定: deterministic / mid critical / 1 PR 規模 / verifier=Haiku
→ Hybrid 質問で「max-turns 30 で OK ?」を聞く
→ 確定後、spec 出力 + 実行プリミティブ選択 (deterministic なら Workflow か /loop)
例 2: /loop-design "Inbox の processed:false を 5 件 Card 化" --max-budget=2
→ 推定: deterministic / low critical / repo 全体 / verifier=Haiku
→ Stage 2 決定的 gate = grep "processed: false" Inbox/*.md | wc -l ≤ 旧値-5
→ State = Inbox の frontmatter を直接 mutate するため git diff で track
例 3: /loop-design "ホーム画面の hero セクションを改善" --type=non-deterministic
→ 推定: non-deterministic / mid critical / 1 file / verifier=Codex (adversarial)
→ Stage 1 = Codex に「視認性 / アクセシビリティ / ブランド整合」3 観点でレビュー依頼
→ 「人間 gate 必須」を spec 末尾に強調表示
Related (Cards)
- loop-engineering-autonomous-agents — 7 要素の理論背景
- claude-code-loop-harness-orchestration-2026 — フェーズ→プリミティブ対応、ネスト上限、per-phase subagent の注意点 (本 skill の実行プリミティブ選択の根拠)
- loop-failure-modes-mechanism-2026 — F1-F10 対策の出典
- llm-as-judge-bias-patterns — verifier 設計の根拠
- anthropic-pricing-and-tiering-2026 — cost guard / tiering
- karpathy-autonomy-slider — mission-critical 度の autonomy slider
- loop-engineering-intro-guide-jp — 入門ガイド (本 skill の使い方を理解する前提)
注意事項
- 本 skill は spec を生成するだけ。生成された spec は 人間が必ず目視 review してから実行する (F9 偽合言葉完了の連鎖を防ぐため)
--no-fail-hooks は意図して F1-F10 対策を外すときのみ使う (例: 既存 spec の minimal 化、教育目的の素朴版生成)- 実行プリミティブは Claude Code 2.1.185 時点で確認:
Workflow ツール / /loop skill / ralph-loop plugin / claude -p。旧 claude --goal / --max-iterations は存在しない (誤って出力しないこと)
- secret は spec に直書きしない (
op:// 経由を強制)
- 生成した spec を そのまま social に公開しない (内部のディレクトリ構造 / 業務情報が漏れる可能性)
