skill-iterative-loop

ホスト：Codex CLI — このスキルは Claude Code 向けに設計され、Codex 用に適応されています。 相互参照コマンドでは、/octo:* スラッシュコマンドではなく、Codex にインストール済みのスキル名を使用します。 現在の Codex シェルとサブエージェントツールを使用してください。現在のセッションで利用可能であることが確認されるまでは、プロバイダー、モデル、ホストのサブエージェントが利用可能だと断言しないでください。 ホストツールの代替手段については、skills/blocks/codex-host-adapter.md を参照してください。

反復ループの実行

概要

明確な目標、終了条件、進捗追跡に基づいて、体系的に反復実行します。

基本原則： 目標を定義 → 最大反復回数を設定 → 実行 → 評価 → 続行または完了。

使用する場面

次のような要望がある場合に、このスキルを使用してください。

• 改善を加えながら、タスクを複数回実行する
• 条件を満たすまでループする
• コード、テスト、パフォーマンスなどを段階的に改善する
• 変更を加えながら操作を再試行する
• ラウンドを重ねて段階的に強化する

次の用途には使用しないでください。

• 1回だけの実行（「テストを1回実行する」）
• 手動でのステップごとの作業
• 上限のない無限ループ
• 単純な再試行ロジック（skill-debug を使用してください）

プロセス

フェーズ 1：ループの設定

ステップ 1：意図を理解する

**Loop Intent:**

Goal: [what should be achieved]
Success criteria: [how do we know we're done]
Max iterations: [safety limit]
Per-iteration tasks: [what to do each loop]

ステップ 2：パラメーターを明確にする

不明な点がある場合は AskUserQuestion を使用します。

• 最大反復回数： 最大で何回実行しますか？
• 成功条件： 早期に停止できることを示すものは何ですか？
• 各反復でのアクション： 各ラウンドで具体的に何をしますか？
• 失敗時の対応： 成功しなかった場合はどうしますか？

ステップ 3：安全性の確認

**Safety Validation:**

- [ ] Max iterations defined (no infinite loops)
- [ ] Success condition is measurable
- [ ] Each iteration makes progress
- [ ] Failure exit strategy exists
- [ ] User aware of potential duration

最大反復回数を定義せずに、決して続行しないでください。

フェーズ 2：ループの実行

ステップ 1：ループを初期化する

**Starting Iterative Loop**

Goal: [description]
Max iterations: [N]
Success criteria: [condition]


### Iteration 1 / [N]

ステップ 2：反復を実行する

各反復で、次の処理を行います。

**Iteration [current] / [max]**

**Actions:**
1. [Action 1]
   → [result/output]
2. [Action 2]
   → [result/output]
3. [Action 3]
   → [result/output]

**Evaluation:**
- Success criteria met? [Yes/No]
- Progress made? [Yes/No]
- Issues found: [list any issues]

**Status:** [Continue/Success/Need intervention]

ステップ 3：進捗を追跡する

タスク計画ツールを使用して反復を追跡します。

Iteration Progress:
✓ Iteration 1 - [what was done]
✓ Iteration 2 - [what was done]
⚙️ Iteration 3 - [in progress]
- Iteration 4 - [pending]
- Iteration 5 - [pending]

フェーズ 3：終了条件

終了条件 1：成功

🎉 **Success! Loop complete.**

**Goal achieved:** [description]
**Iterations used:** [N] / [max]

**Final state:**
[description of what was achieved]

**Summary of iterations:**
1. Iteration 1: [what happened]
2. Iteration 2: [what happened]
...
N. Iteration N: [what happened] ✓ Success

終了条件 2：最大反復回数に到達

⚠️ **Max iterations reached without full success**

**Iterations completed:** [max]
**Goal:** [description]
**Current state:** [how close we got]

**Progress made:**
- [Improvement 1]
- [Improvement 2]
- [Improvement 3]

**Remaining issues:**
- [Issue 1]
- [Issue 2]

**Options:**
1. Accept current state (substantial progress made)
2. Continue with [N] more iterations
3. Change approach (current method may not work)

What would you like to do?

終了条件 3：進捗が検出されない

🛑 **Stopping early: No progress detected**

**Iteration:** [N] / [max]
**Reason:** Last [M] iterations showed no improvement

**Analysis:**
This suggests the current approach may be fundamentally flawed.

**Recommendation:**
Rather than continue looping, let's:
1. Analyze why no progress is being made
2. Consider alternative approaches
3. Re-evaluate the goal or success criteria

Shall we pause and reassess?

よくあるパターン

パターン 1：テストを伴うループ

User: "Loop around 5 times auditing, enhancing, testing, until it's done"

Implementation:

**Loop Goal:** Code passes all quality gates
**Max Iterations:** 5
**Per-iteration:**
1. Audit code for issues
2. Enhance/fix identified issues
3. Run tests
4. Check if all pass

**Success:** All tests pass + no issues found

Execute:
Iteration 1:
- Audit → Found 8 issues
- Fix → Fixed 8 issues
- Test → 2 tests still failing
- Continue

Iteration 2:
- Audit → Found 2 new issues from fixes
- Fix → Fixed 2 issues
- Test → All tests pass ✓
- Success! Stopping early (2/5 iterations used)

パターン 2：パフォーマンス最適化ループ

User: "Keep trying optimizations until we hit < 100ms response time"

Implementation:

**Loop Goal:** Response time < 100ms
**Max Iterations:** 10
**Per-iteration:**
1. Measure current performance
2. Identify bottleneck
3. Apply optimization
4. Re-measure

**Success:** Response time < 100ms

Execute:
Iteration 1: 450ms → Cache database queries → 280ms (Continue)
Iteration 2: 280ms → Add index to frequent query → 150ms (Continue)
Iteration 3: 150ms → Implement response compression → 85ms (Success!)

パターン 3：バックオフを伴う再試行

User: "Try deploying, retry up to 3 times if it fails"

Implementation:

**Loop Goal:** Successful deployment
**Max Iterations:** 3
**Per-iteration:**
1. Attempt deployment
2. Check status
3. If failed, wait before retry

**Success:** Deployment succeeds

Execute:
Iteration 1: Deploy → Failed (API timeout) → Wait 10s
Iteration 2: Deploy → Failed (API timeout) → Wait 20s
Iteration 3: Deploy → Success ✓

パターン 4：段階的な改善

User: "Iterate 4 times improving the error messages based on user feedback"

Implementation:

**Loop Goal:** Error messages meet clarity standard
**Max Iterations:** 4
**Per-iteration:**
1. Review current error messages
2. Identify confusing ones
3. Rewrite for clarity
4. Evaluate against criteria

**Success:** All messages rated 8+/10 for clarity

Execute each iteration with progressive improvement

他のスキルとの連携

skill-debug との連携

Loop for debugging:
"Keep debugging until all tests pass, max 5 tries"

Each iteration:
- Use skill-debug to investigate failure
- Apply fix
- Re-run tests
- Evaluate

skill-audit との連携

Loop for comprehensive checking:
"Loop 3 times auditing different aspects"

Iteration 1: Audit security
Iteration 2: Audit performance
Iteration 3: Audit accessibility

skill-tdd との連携

Loop for TDD cycles:
"Do 5 red-green-refactor cycles"

Each iteration:
- Write failing test (red)
- Make it pass (green)
- Refactor (refactor)
- Evaluate and continue

ベストプラクティス

1. 最大反復回数を必ず定義する

良い例：

Loop max 5 times trying to fix the issue

危険な例：

Keep trying until it works
(What if it never works? Infinite loop!)

2. 成功基準を測定可能にする

良い例：

Success: All 15 tests pass AND code coverage > 80%

不適切な例：

Success: Code looks better
(Too subjective)

3. 進捗を可視化する

**Progress Tracking:**

Iteration 1: 5/15 tests passing
Iteration 2: 10/15 tests passing
Iteration 3: 13/15 tests passing
Iteration 4: 15/15 tests passing ✓

4. 成功したら早期に終了する

目標を達成したら、ループを続けないでください。

**Iteration 2/5:** All tests pass!

Stopping early - goal achieved.
No need to continue to iteration 3.

5. 停滞を検知する

Iteration 4: 10/15 tests passing
Iteration 5: 10/15 tests passing
Iteration 6: 10/15 tests passing

⚠️ No progress in 3 iterations - stopping to reassess approach

危険信号 — してはいけないこと

アクション	危険な理由
最大反復回数がない	無限にループする可能性があります
成功基準が曖昧	いつ停止すべきかわかりません
進捗を追跡しない	進捗があるかどうか判断できません
停滞を無視する	効果のない方法に時間を浪費します
毎回同じアクションを行う	うまくいかない場合は、別の方法が必要です

戦略の切り替え

戦略切り替えフックが作動した場合は、直ちにアプローチを変更してください。同じアプローチを再試行しないでください。次の試行の前に、何をどう変えるかを説明してください。このフックは、同じツールで失敗が連続した後に作動します。これは、現在のアプローチが少しずれているだけでなく、根本的に間違っていることを示す強いシグナルです。

自己調整（必須）

すべての反復ループでは、危険信号を蓄積する自己調整スコアを追跡する必要があります。これにより、エージェントが実際には進展していないのに、物事を「修正」し続ける暴走ループを防ぎます。

スライディングウィンドウによる停滞検出

直近10回のイテレーション（10回に満たない場合はそれ以下）を頭の中で記録します。各イテレーション後に、繰り返しパターンがないか確認します。

単一状態の繰り返し： 同じ結果やエラーが3回以上連続して発生しましたか？

• 同じテスト失敗、同じエラーメッセージ、同じファイルの変更 → 停滞

複数ステップのサイクル検出： A→B→A→B のような振動が起きていますか？

• イテレーションNでファイルXに触れ、N+1でファイルYに触れ、N+2で再びファイルXに触れ、N+3で再びファイルYに触れる → サイクルを検出
• 成功／失敗だけでなく、イテレーション間で変更されたファイルとエラーメッセージを比較します

初回検出時： パターンをユーザーに伝えます。明確に認識したうえで、診断のための再試行を1回だけ行います。「このパターンが繰り返されています。次のように変更して対応します：[具体的な変更]」

2回目の検出時： ただちに停止します。 検出したサイクルを表示し、まったく異なる方法で続けるか、停止するかをユーザーに尋ねます。

WTF 可能性スコア

0%から始まる累積スコアを記録します。イベントごとにスコアが加算されます。

デフォルトの重み（~/.claude-octopus/loop-config.conf で上書きできます）：

イベント	スコアへの影響
元に戻す（git revert、取り消し、ロールバック）	+15%
明示された目標に無関係なファイルへの変更	+20%
3ファイルを超える変更が必要な修正	+5%
15回目の修正試行以降	修正を1回追加するごとに+1%
残りの問題がすべて低重要度	+10%

WTFスコアが20%を超えた場合： ただちに停止します。 次の内容を表示します。

1. 現在のWTFスコアと、そのスコアに影響した要因
2. これまでに完了した作業
3. ユーザーに尋ねます：「別の方法で続けますか、それともここで停止しますか？」

上限： スコアや進捗に関係なく、50回のイテレーションまでです。例外はありません。

重みの設定

ループの開始時に、~/.claude-octopus/loop-config.conf があるか確認します。存在する場合は、key=value のペアを読み込み、デフォルトの代わりに使用します。形式：

# Loop Self-Regulation Configuration
WINDOW_SIZE=10
REVERT_PENALTY=15
UNRELATED_FILES_PENALTY=20
LARGE_FIX_PENALTY=5
AFTER_FIX_15_PENALTY=1
ALL_LOW_SEVERITY_PENALTY=10
WTF_THRESHOLD=20
HARD_CAP=50
STUCK_THRESHOLD=3

ファイルが存在しない場合は、上記のデフォルトを使用します。ユーザーはこのファイルを作成して、自分のワークフローに合わせて感度を調整できます。

追跡方法

外部ツールは必要ありません。ループ中に頭の中で追跡します。

• 各イテレーション後に、変更したファイル、結果、元に戻す操作があったかを記録します
• 直近のイテレーションのスライディングウィンドウと比較します
• WTFスコアを累積します
• 各イテレーションの概要で、イテレーション数と自己制御スコアの両方を報告します。

Iteration 5/20 | Self-regulation: 10% (1 revert, 0 unrelated files)

戦略ローテーションとの連携

戦略ローテーションフックと自己制御は、相互に補完するものです。

• 戦略ローテーションは、同じツールで同じエラーが連続して発生した場合に作動します
• 自己制御は、結果のパターン（サイクル、元に戻す操作、スコープの逸脱）を検出した場合に作動します
• それぞれ独立して作動する場合があります。両方が作動した場合は、停止します。ループが確実に停滞しています。

安全機構

1. イテレーション上限

MAX_ITERATIONS = user_specified or 10  # Always have a limit
HARD_CAP = 50  # Absolute maximum regardless of user setting

2. 自己制御スコア

Track WTF score across iterations.
If score > 20%: STOP and ask user.

3. スライディングウィンドウ検出

Track last 10 iterations.
If repeated pattern detected twice: STOP and ask user.

4. 進捗検出

If last 3 iterations show same result:
  → Stop and ask user

5. 時間制限（長時間の操作向け）

If total time > 30 minutes:
  → Checkpoint progress
  → Ask user if should continue

6. ユーザーチェックポイント

Every N iterations:
  → Show progress
  → Ask if should continue or adjust approach

クイックリファレンス

パターン	最大イテレーション数	成功条件	早期終了
テストに合格するまで実行	5-10	すべてのテストに合格	あり
パフォーマンス最適化	10-20	指標が目標値未満	あり
バックオフ付き再試行	3-5	操作の成功	あり
段階的な調整	3-7	品質のしきい値を達成	場合による
包括的な監査	3-5	すべての領域を網羅	なし

指標検証モード

ユーザーが指標コマンドを指定した場合は、機械的な指標検証モードに切り替えます。主観的な評価を、自動測定、git に基づく実験、回帰発生時の自動ロールバックに置き換えます。

指標が指定されていない場合は、標準のループ動作（上記）に戻ります。

重要な原則

• 1 回のイテレーションにつき変更は 1 つ（アトミック） — 無関係な変更を複数まとめないでください
• 機械的な検証のみ — 主観的に「よさそう」と判断せず、メトリクスコマンドの結果で決定します
• 回帰が発生したら自動でロールバック — メトリクスが悪化した場合は git revert HEAD --no-edit を実行します
• シンプルさを優先 — メトリクスの結果が同じなら、コードが少ないほうを採用します
• Git を記憶として使う — 検証の前に、すべての実験を experiment: プレフィックス付きでコミットします
• ガードコマンドも成功する必要があります — メトリクスが改善していても、ガードに失敗した場合は変更を元に戻します

パラメーター

パラメーター	形式	必須	説明
メトリクス	Metric: <shell command>	はい（このモードでは必須）	標準出力が数値（メトリクス値）となるコマンド
方向	Direction: higher|lower	はい	メトリクス値が高いほうと低いほうのどちらがよいか
ガード	Guard: <shell command>	いいえ	変更を維持するには終了コード 0 である必要があります。メトリクスの実行後に実行します
イテレーション	Iterations: N	いいえ	イテレーションの最大回数（デフォルト：無制限。中断されるまで実行）

実験ログ

すべての結果は .claude-octopus/experiments/<YYYY-MM-DD>.jsonl に JSONL 形式で記録されます。

各行は JSON オブジェクトです：

{"iteration": 1, "timestamp": "2026-03-21T14:30:00Z", "metric": 72.5, "best": 72.5, "status": "kept", "description": "Add index to users table", "commit": "abc1234"}

フィールド：

• iteration — イテレーション番号（1 から開始。イテレーション 0 はベースライン）
• timestamp — ISO 8601 形式のタイムスタンプ
• metric — メトリクスコマンドで測定した値
• best — これまでに確認された最良のメトリクス値
• status — "kept"（改善）、"reverted"（回帰）、または "error"（メトリクス／ガードの異常終了）
• description — 変更内容の 1 行の要約
• commit — 実験コミットの短縮 Git SHA（ロールバック前）

実行契約

各イテレーションでは、以下の手順を正確に守る必要があります。手順を省略したり、順序を変更したりしてはいけません。

イテレーション 0：ベースラインの確立

1. 実験ログのディレクトリが存在しない場合は作成します：

   mkdir -p .claude-octopus/experiments
   

2. 既存の実験ログを確認 — .claude-octopus/experiments/<today>.jsonl が存在する場合は読み込み、現在の最良のメトリクス値とイテレーション数を確認します。次のイテレーション番号から再開します。
3. メトリクスコマンドを実行し、出力された数値を取得します。これがベースラインです。
4. ベースラインを記録します：

   {"iteration": 0, "timestamp": "...", "metric": <baseline>, "best": <baseline>, "status": "baseline", "description": "Baseline measurement", "commit": "<current HEAD short SHA>"}
   

5. ベースライン値をユーザーに報告します。

以降の各イテレーション（1..N）

ステップ 1：状態を確認します。 実験ログ（.claude-octopus/experiments/<today>.jsonl）を読み、Git の履歴（git log --oneline -10）を確認して、これまでに試したこと、成功したこと、失敗したことを特定します。

ステップ 2：次の変更を選びます。 成功した変更、失敗した変更、まだ試していない変更に基づき、焦点を絞った変更を 1 つ決めます。関連のない変更を複数組み合わせないでください。

ステップ 3：変更を加えます。 アトミックな変更を 1 つだけ実装します。

ステップ 4：検証の前に Git にコミットします。 experiment: プレフィックスを付けてコミットします。

git add -A && git commit -m "experiment: <one-line description of the change>"

これにより、結果にかかわらず、すべての実験が Git の履歴に記録されます。

ステップ 5：機械的な検証を実行します。 メトリックコマンドを実行し、数値の結果を記録します。

ステップ 6：評価して対応します。

• メトリックが改善した場合（Direction=higher の場合は値が大きく、Direction=lower の場合は値が小さくなる）：

  • Guard コマンドが指定されている場合は、ここで実行します。
    • ガードが成功した場合（終了コード 0）→ コミットを保持します。最良のメトリックを更新します。
    • ガードが失敗した場合（終了コードが 0 以外）→ 取り消します：git revert HEAD --no-edit。ステータスを "reverted" として記録します。
  • ガードがない場合 → コミットを保持します。最良のメトリックを更新します。

• メトリックが変わらない場合：

  • 変更によってコードの複雑さやサイズが減るか確認します。よりシンプルになる場合は保持します（シンプルさを優先します）。
  • それ以外の場合 → 取り消します：git revert HEAD --no-edit。ステータスを "reverted" として記録します。

• メトリックが悪化した場合：

  • 取り消します：git revert HEAD --no-edit。ステータスを "reverted" として記録します。

• メトリックコマンドがクラッシュした場合（終了コードが 0 以外で、数値の出力がない）：

  • 簡単な修正を試みます（試行は 1 回のみ）。修正できた場合は、再測定します。
  • それでも動作しない場合 → 取り消します：git revert HEAD --no-edit。ステータスを "error" として記録します。

ステップ 7：結果を記録します。 .claude-octopus/experiments/<today>.jsonl に JSONL エントリーを追加します。

ステップ 8：イテレーションの概要を報告します。 次を表示します。

Iteration N: <description>
  Metric: <value> (best: <best>) — <kept|reverted|error>

ステップ 9：繰り返します — 次のイテレーションのステップ 1 に進みます。ただし、以下の場合を除きます。

• イテレーションの上限に達した → 停止して最終概要を報告します
• ユーザーが中断した → 停止して最終概要を報告します

再開時の動作

今日の実験ログがすでに存在する場合：

1. ログを読み、最後のイテレーション番号と現在の最良のメトリック値を確認します
2. 次のイテレーション番号から再開します
3. 記録された最良の値を比較の基準として使用します
4. これにより、セッションをまたいで実験を停止・再開できます

最終概要

ループが終了したとき（イテレーションを使い切った場合、またはユーザーが停止した場合）は、次を報告します。

Experiment Complete
  Iterations: N
  Baseline: <initial metric>
  Final best: <best metric>
  Improvement: <delta> (<percentage>%)
  Kept: K changes, Reverted: R changes, Errors: E

例

/octo:loop Metric: npm test -- --coverage | grep 'All files' | awk '{print $(10)}' Direction: higher Guard: npm test Iterations: 20

この例では、次のことを行います。

1. ベースラインのコードカバレッジ率を測定します
2. 各イテレーションで変更を 1 つ加え、experiment: ... としてコミットし、カバレッジを測定します
3. カバレッジが改善し、かつ npm test が成功した場合は保持します
4. カバレッジが低下するか、テストが失敗した場合は git revert HEAD --no-edit を実行します
5. 20 回のイテレーション後、改善の合計を報告します

要点

Iterative loop → Clear goal + Max iterations + Progress tracking + Exit strategy
Otherwise → Infinite loops + Wasted effort + Unclear when done

目標を定め、上限を設定し、進捗を追跡し、停止するタイミングを見極めましょう。