self-checking

# self-checking エージェントが自身の成果物を評価・改善する反復ループスキル。コード・調査レポート・ドキュメントに対応する。 ``` 生成・実行 → 自己評価 → 改善 → 再評価 → 合格 ↑ │ └──────── スコア未達の場合のみ ─────────┘ ``` ## パス解決 このSKILL.mdが置かれているディレクトリを `SKILL_DIR` とする。 - スクリプト: `${SKILL_DIR}/scripts/check.py` - ルーブリック: `${SKILL_DIR}/references/rubrics/` --- ## 対応する成果物の種別 | artifact_type | 対象 | ルーブリック | |---|---|---| | `code` | ソースコード・テストコード・設定ファイル | `${SKILL_DIR}/references/rubrics/code.md` | | `research` | 調査レポート・技術調査・競合分析 | `${SKILL_DIR}/references/rubrics/research.md` | | `document` | 設計書・要件定義書・README・仕様書 | `${SKILL_DIR}/references/rubrics/document.md` | artifact_type が不明な場合は `check.py --detect [file]` で自動検出する。 --- ## 実行プロトコル ### Step 1: 成果物と種別の確認 1. 評価対象の成果物と artifact_type を確認する 2. artifact_type が未指定の場合: ```bash python ${SKILL_DIR}/scripts/check.py --detect [対象ファイルパス] ``` 出力例: `{"artifact_type": "code", "confidence": 0.95}` 3. 対応するルーブリックファイルを読み込む: ```bash # 例: code の場合 # ${SKILL_DIR}/references/rubrics/code.md を読む ``` 4. 完了基準（done_criteria）が渡されている場合は評価基準に追加する --- ### Step 2: 自動チェックの実行 スクリプトで定量チェックを実施する: ```bash python ${SKILL_DIR}/scripts/check.py \ --type [artifact_type] \ --files [対象ファイルパス（スペース区切り、複数可）] \ --criteria "[完了基準（任意）]" ``` 出力例（JSON）: ```json { "artifact_type": "code", "checks": { "syntax": {"passed": true, "details": ""}, "completeness": {"passed": true, "details": ""}, "test_presence": {"passed": false, "details": "テストファイルが見当たらない"} }, "auto_score": 0.67, "failed_checks": ["test_presence"] } ``` スクリプト失敗時（ファイルなし・パースエラー等）は自動チェックをスキップし、ルーブリック評価のみを実施する。 --- ### Step 2.5: 実行証拠ゲート（`code` のみ・必須） **`artifact_type` が `code` の場合、「動くはず」という推論だけで PASS にしてはならない。** 完了報告の前にエージェント自身が実際に動かし、客観的な実行証拠を取得する。これにより人間が後追いで検証する手間を肩代わりする。 **証拠として認める成果（いずれか 1 つ以上、対象成果物に応じて選ぶ）**: | 証拠 | 取得方法の例 | |---|---| | テスト実行結果 | テストランナーを実行し、件数・成否（pass/fail）の実出力を取得 | | ビルド／型チェック／リンタ | ビルド・型・lint コマンドを実行し、終了コードと出力を取得 | | 実行ログ | スクリプト・CLI を実際に走らせ、想定どおりの出力を確認 | | 画面の挙動 | Web/UI は `webapp-testing`（Playwright）で操作し、スクリーンショット・コンソールログを取得 | **ゲート判定**: - 実行証拠が**取得できた** → `execution_evidence = "verified"`。証拠の要約（実行コマンド・結果）を記録して Step 3 へ - 実行が環境制約等で**不可能だった** → `execution_evidence = "blocked"`。理由と、人間が確認すべき手順を `blocking_issues` に明記して Step 3 へ。**この場合 PASS にはできず NEEDS_IMPROVEMENT が上限** - まだ**実行していない** → 実行してから判定する（未実行のまま先へ進まない） `research` / `document` ではこのゲートは適用しない（Step 3 へ直行）。 --- ### Step 3: ルーブリック評価 読み込んだルーブリックに従って各ディメンションを評価する。 **評価スケール**: 各ディメンションを 1〜5 で採点し、重み付き合計スコアを算出する。 ``` スコア = Σ (採点 / 5 × 重み) ``` **評価結果を以下の形式で記録する**: ```json { "dimensions": { "[ディメンション名]": { "score": 4, "weight": 0.3, "verdict": "PASS", "feedback": "[評価コメント]" } }, "rubric_score": 0.82, "failed_dimensions": ["[基準未達のディメンション名]"] } ``` **判定閾値**: - `rubric_score >= 0.8` かつ `auto_score >= 0.7`（自動チェックあり時）かつ **実行証拠ゲートを通過（`code` 時は `execution_evidence == "verified"`）** → **PASS** - それ以外 → **NEEDS_IMPROVEMENT**（改善ループへ） > `code` で実行証拠が `blocked` の場合、スコアが閾値を超えていても PASS にはできない。NEEDS_IMPROVEMENT のまま、人間が確認すべき手順を添えて返す。 --- ### Step 4: 改善ループ（NEEDS_IMPROVEMENT の場合のみ） 基準未達のディメンション・チェック項目のみを対象に改善し、**PASS になるまで繰り返す**。 **終了条件（どちらか先に満たした方で Step 5 へ進む）**: | 条件 | 判定 | 次の処理 | |------|------|----------| | `rubric_score >= 0.8` かつ `auto_score >= 0.7`（自動チェックあり時）かつ 実行証拠ゲート通過（`code` 時）| **PASS** | Step 5 へ | | 連続 2 イテレーションでスコア改善幅 < 0.03（収束） | **NEEDS_IMPROVEMENT** | Step 5 へ（外部レビューに引き渡す） | 改善ループでは、実行証拠が `blocked`／未取得のまま PASS 条件に到達しても PASS とせず、まず実行証拠の取得を試みる。 ``` 各イテレーション: 1. 失敗した項目を特定する: failed_dimensions + failed_checks 2. 各失敗項目について改善を実施する 3. 改善内容を記録する: {"dimension": "...", "action": "...", "before": "...", "after": "..."} 4. Step 2〜3 を再実施してスコアを再計算する 5. 終了条件を確認する → 満たせば Step 5 へ。満たさなければ 1 へ戻る ``` **改善時の注意**: - 失敗していない項目には手を加えない - ただし、ある基準の改善が用語・構造・前提に波及する場合、その波及先は失敗項目でなくても整合のために修正する。整合性のための波及修正は回帰リスクではなく回帰防止である - 改善前後のスコアと主な変更点を記録する --- ### Step 5: 結果報告 評価結果を以下の形式でまとめる: ``` ## 自己評価結果 | 項目 | 値 | |------|-----| | 種別 | [artifact_type] | | 最終判定 | PASS ✅ / NEEDS_IMPROVEMENT ⚠️ | | ルーブリックスコア | [0.0〜1.0] | | 自動チェックスコア | [0.0〜1.0 / N/A] | | 実行証拠 | verified ✅ / blocked ⚠️ / N/A（code 以外） | | 反復回数 | [0〜N（PASS or 収束まで）] | 実行証拠が `verified` の場合は、実行したコマンドと結果の要約を「改善の軌跡」または専用の小節に残す。 ### ディメンション別結果 | ディメンション | スコア | 判定 | コメント | |---|---|---|---| | [name] | [N]/5 | PASS ✅ / FAIL ❌ | [feedback] | ### 改善の軌跡 [反復ごとの変更概要] ### 残存する懸念事項（あれば） [最終反復後も未解決の項目] ``` **verdict-json**（オーケストレーターが読み取る構造化出力）: ```json <!-- verdict-json --> { "skill": "self-checking", "verdict": "PASS | NEEDS_IMPROVEMENT", "artifact_type": "[code|research|document]", "rubric_score": 0.0, "auto_score": 0.0, "execution_evidence": "verified | blocked | n/a", "evidence_summary": "[実行したコマンドと結果の要約。code かつ verified 時は必須]", "iterations": 0, "improved_files": [], "blocking_issues": [] } <!-- /verdict-json --> ``` --- ## ベストプラクティス | プラクティス | 理由 | |-------------|------| | **失敗した基準のみ改善する（整合性の波及は例外）** | 合格済み項目への不要な変更を防ぎ、回帰リスクを下げる。ただし整合性に関わる波及は失敗項目外でも修正対象とする | | **PASSになるまで改善する** | 回数ではなく「スコア閾値を超えるまで」を終了条件とする | | **収束で安全に終了する** | 連続 2 回の改善幅 < 0.03 で収束とみなし、NEEDS_IMPROVEMENT のまま外部レビューに引き渡す | | **自動チェックとルーブリックを組み合わせる** | 定量的な客観指標と定性的な評価の両方を担保する | | **code は実行で裏取りしてから PASS にする** | 「動くはず」を排し、人間の後追い検証の手間を肩代わりする。証拠の要約を必ず残す | | **改善履歴をログに残す** | デバッグと振り返り分析のために全反復のトレースを保持する | --- ## エラーハンドリング | 状況 | 対応 | |------|------| | `check.py` が失敗する | ルーブリック評価のみで続行。自動チェックスコアは `N/A` とする | | ルーブリックファイルが見当たらない | artifact_type に最も近いルーブリックを使用するか、汎用的な評価（正確性・完全性・明確性）で代替する | | 収束（連続 2 イテレーションで改善幅 < 0.03）してもスコアが閾値未達 | NEEDS_IMPROVEMENT のまま結果を返す。外部レビュー（agent-reviewer）で追加確認する | | 成果物ファイルが存在しない | エラーを報告してスキルを終了する |