experiment-iterative-coder

Iterative Coder

構造化された「計画 → コード作成 → 評価 → 改善」のサイクルを通じて、コードを反復的に改良します。各サイクルでは客観的なチェック（lint、テスト）と自己評価を行い、失敗の原因を診断して、的を絞った改善を計画します。3～8 回の反復で本番品質に到達します。

このスキルを使う場面

• メインエージェントから、「MODE: MORE_EFFORT」を先頭に付けたコードタスクを委任された場合
• ユーザーがコード生成で「More Effort」モードを選択した場合
• 検証済みの正確性を備えた高品質なコードが必要なタスクの場合
• 複雑な実装を伴うタスク（5 個以上のファイル、複数のモジュール）の場合
• 初回のコードを提出するのではなく、コード品質を反復的に高めたい場合
• 「iterative refinement」、「code quality loop」、「plan-code-evaluate」に言及した場合

反復の考え方

コードの品質は、慎重な初回の試みではなく、素早いフィードバックループから生まれます。 「完璧な」初回実装に 30 分を費やすより、計画 → コード作成 → 評価 → 修正のサイクルを素早く回すほうが効果的です。評価のステップでは、考えるだけでは予測できない問題が明らかになります。lint エラー、インポートの失敗、テストの不具合、考慮漏れのエッジケースは、実際にコードを実行するとすぐに見つかります。

開始前：コンテキストを読み込む

1. /memory/experiment-memory.md を読み、過去のサイクルで効果が確認された戦略を確認します（存在しない場合はスキップしてください）
2. ワークスペース内に既存のテスト、lint 設定（pyproject.toml、ruff.toml）、CI 設定があるか確認します
3. 利用可能なツールを確認します：

   ruff --version 2>&1; echo "---"; python -m pytest --version 2>&1
   

   いずれかが見つからない場合は、評価中にそのチェックをスキップします（反復を失敗としないでください）。

フェーズの分解

反復を始める前に、タスクを分析して順序のあるフェーズに分解します。

タスクの複雑さ	推奨されるフェーズ数
単一ファイルで、仕様が明確な関数	1 フェーズ
2～4 個のファイルで、インターフェイスが明確	2 フェーズ
5 個以上のファイルで、相互に連携する複数のモジュール	3～5 フェーズ

各フェーズで、次の内容を定義します。

• 名前：簡潔なラベル（例：「データ読み込みパイプライン」）
• 目標：このフェーズで「完了」とはどのような状態か
• 検証シグナル：フェーズの完了を確認する方法（具体的なテスト、lint エラーがないこと、出力が一致すること）

フェーズは依存関係の順に並べます。後のフェーズが前のフェーズを基盤にする場合があります。

反復ループ

各フェーズでは、最大 3 回反復します。全フェーズを通じた最大反復回数は 10 回です。

ステップ 1：計画

現在のコードと、以前の評価フィードバック（ある場合）を読みます。簡潔な改善計画を作成します。

フェーズの最初の反復：フェーズの目標に基づいて、初期実装計画を作成します。

2 回目以降の反復：直近の評価フィードバックを分析し、変更を計画する前に失敗の根本原因を診断します。すでに失敗したアプローチを繰り返さないでください。

直近の評価での失敗の種類に応じて、計画を調整します。

直近の失敗	計画する対応
タイムアウト	--quick／--smoke モードを追加する、データサイズを減らす、早期停止を追加する
構文エラー	ロジックを簡潔にし、実行前に python -c "import ast; ast.parse(open('file.py').read())" を実行して検証する
インポートエラー	pip list を確認し、インストール済みのパッケージのみを使い、不足している依存関係を requirements に追加する
テスト失敗	失敗したテストに絞り、最小限の変更で対応する
lint 失敗	ロジックを変更する前に ruff check --fix . && ruff format . を実行する
自己評価が低い	元のタスク要件を読み直し、機能の不足がないか確認する

ステップ 2：コード作成

計画を実装します。変更は計画に記載した内容に絞ります。

• 計画で明示的に必要とされていない限り、正常に動作しているファイルを書き換えないでください
• コードを書いた後、変更したファイルに問題がないか簡単に読み直します

ステップ 3：評価

重要：毎回の反復で、必ず以下のコマンドを実行してください。評価をスキップしないでください。

# 1. Lint check
ruff check . 2>&1 | tail -20
echo "LINT_EXIT: $?"

# 2. Format check
ruff format --check . 2>&1 | tail -10
echo "FORMAT_EXIT: $?"

# 3. Run tests (only if test files exist in workspace)
python -m pytest -x -q --tb=short 2>&1 | tail -30
echo "TEST_EXIT: $?"

ruff がインストールされていない場合は、チェック 1～2 をスキップします。pytest がインストールされていない場合、またはテストファイルが存在しない場合は、チェック 3 をスキップします。スキップしたチェックを記録してください。

ステップ 4：スコアを算出する

客観的な指標と自己評価から複合スコアを算出します。

客観的な指標（ステップ 3 の終了コードから判定）：

• LINT_EXIT=0 → lint_score = 1.0、それ以外 → lint_score = 0.0
• FORMAT_EXIT=0 → format_score = 1.0、それ以外 → format_score = 0.0
• TEST_EXIT=0 → test_score = 1.0、それ以外 → pytest の出力から合格率を解析します（例：「3 passed, 1 failed」→ 0.75）

自己評価（0.0 ～ 1.0 で評価）： 正確性（コードは依頼されたとおりに動作するか？）、完全性（すべての要件に対応しているか？）、エラー処理（妥当なエッジケースをカバーしているか？）、可読性（名前や構成は明確か？）を評価します。

複合スコア — 利用可能な指標に応じて重み付けを動的に変更します：

• lint とテストを利用可能：0.2 × lint + 0.1 × format + 0.3 × test + 0.4 × self
• lint のみ（テストなし）：0.3 × lint + 0.1 × format + 0.6 × self
• テストのみ（ruff なし）：0.4 × test + 0.6 × self
• どちらも利用不可：1.0 × self

自己評価の上限 — 自己評価によるスコアの水増しを防ぎます：

• lint チェックに失敗した場合 → 自己評価にかかわらず、複合スコアの上限は 0.4 です
• いずれかのテストに失敗した場合 → 複合スコアの上限は 0.6 です
• 複合スコアが 0.85 以上であると報告できるのは、lint とテストの両方に合格し、かつ実装が完全な場合に限ります
• 減点：明らかなケースに対するエラー処理の不足（−0.1）、絶対パスのハードコード（−0.05）

スコア算出に関する詳細な例外については、references/evaluation-protocol.md を参照してください。

ステップ 5：判断する

• 複合スコアが ≥ 0.85 → 次のフェーズに進みます（最後のフェーズの場合は終了します）
• 複合スコアが < 0.85 → 評価フィードバックをもとにステップ 1 に戻ります
• フェーズの反復上限に達した場合（フェーズあたり 3 回）→ 残りの問題を記録して、いずれにしても次のフェーズに進みます
• 全体の反復上限に達した場合（合計 10 回）→ 停止し、現時点で最善の結果を出力します

ステップ 6：記録する

重要：反復ごとに /artifacts/iteration_log.md に追記してください。

assets/iteration-log-template.md のテンプレートを使用してください：

## Iteration {N} (Phase {M}/{T})
- **Score**: {composite} (lint={X} format={X} test={X} self={X})
- **Lint**: passed/failed ({N} issues)
- **Tests**: passed/failed ({passed}/{total})
- **Changes**: [{files changed}]
- **Feedback**: [{key evaluation findings}]
- **Next**: continue / next_phase / done

完了

すべてのフェーズが完了するか、全体の反復上限に達した後：

1. 呼び出し元に報告します：
   • 使用した反復の合計回数
   • 最終的な複合スコア
   • フェーズごとの主な改善点（各 1～2 文）
2. すべての出力ファイルのパス（コード、設定、テスト）を一覧表示します
3. 残りの問題を記載します：lint の警告、テストの不足、既知の制限、TODO

直感に反する反復ルール

1. ロジックより先に lint を修正する：lint エラーは連鎖します。インポートエラーが 1 つあると、その後のテスト失敗がすべて隠れてしまいます。ロジックのバグを調べる前に、必ず ruff check --fix . を実行してください。

2. フェーズあたり 3 回の反復で十分です：的を絞った 3 回の反復で修正できない場合、問題は段階的なものではなく、アーキテクチャ（分解方法の誤り）にあります。さらに反復するのではなく、次のフェーズに進むか、計画を立て直してください。

3. コードを読むよりテストを実行するほうが多くを学べます：10 秒間テストを実行すれば、5 分間コードを読むより、正確性について多くを把握できます。コードが正しいと確信していても、必ずテストを実行してください。

4. スコアの低下は情報です：変更後に複合スコアが低下した場合、何が重要かを示すシグナルです。変更を元に戻す前に、低下の理由を分析してください。

5. 過剰に作り込まないでください：目標は 1.0 ではなく 0.85 です。0.9 を超えると、改善による効果は急速に薄れます。必要であれば、成果を出して次の会話で反復してください。

スキルの統合

開始前（メモリを読み込む）

evo-memory を参照 → 過去の戦略について /memory/experiment-memory.md を読みます

失敗時（反復上限に達して行き詰まった場合）

再試行の前に根本原因を特定するため、experiment-craft を参照 → 5 ステップの診断フローを実行します

成功時（すべてのフェーズが完了し、スコアが ≥ 0.85 の場合）

メインエージェントに報告します → メインエージェントがパイプライン（データ分析、執筆など）を続行します

引き継ぎ成果物

成果物	場所	使用者
反復ログ	/artifacts/iteration_log.md	メインエージェントの要約、evo-memory ESE
最終コード	ワークスペースのルート	次のパイプラインステップ
テスト結果	反復ログのエントリー	data-analysis-agent

参照情報

トピック	参照ファイル	使用するタイミング
スコアリングルールとエッジケース	evaluation-protocol.md	エッジケースのスコアリングが発生した場合（部分的なテスト、ツールの不足）
反復ログのテンプレート	iteration-log-template.md	毎回の反復（ステップ 6）