self-healing

自己修復

コーディングエージェント向けの、実行時のアクティブな復旧機能です。何かが壊れたら、診断 → パッチ適用 → 検証 → 記録のループを実行します。失敗をうやむやにして済ませるのではなく、再利用可能で検証済みの成果物を残します。

その前提は、browser-use/browser-harness と同じです。ハーネスは実行のたびに改善されます。エージェントが不足に気づいた場合、失敗するのではなく、実行中に修正を書き、動作することを検証して、今後の実行で使える永続的な成果物として記録します。コーディングタスクにも同じループが必要です。

このスキルの目的

コーディングエージェントがタスクの途中で行き詰まったとき、一般的な失敗パターンは次のとおりです。

1. 取り繕う — 「別の方法を試してみます」 — そして復旧の機会を逃す
2. 修正できたふりをする — 壊れた処理を再実行しない
3. 症状だけを修正する — テストを省略し、エラーを無視し、成功するまで再試行する

これらはすべて、一度きりの失敗を再発へと変えてしまいます。同じプロジェクトで次に作業するエージェントも、同じ壁にぶつかります。

このスキルが徹底する規律はひとつです。永続化する前に検証する。失敗した操作を再実行し、成功するのを確認するまでは、パッチは完成したとは言えません。成功したら、検証済みの修正を記録し、次回の実行にも役立てます。

自己改善との関係

この2つのスキルは、意図的に分けられています。両方を実行してください。互いに活用し合いますが、役割は重複しません。

側面	self-healing（このスキル）	self-improvement
タイミング	実行中に、発生したばかりの失敗に対応します	事後の自然な区切りで対応します
動詞	今すぐ修復する — 動作する状態に戻す	後で活用できるよう記憶する — 知識を蓄積する
成果	検証済みパッチ +（任意の）再利用可能な成果物	学び、修正、リクエストの記録
検証	必須 — 証明なしに永続化しない	不要
ファイル	.learnings/HEALS.md + .learnings/heals/<HEAL-ID>/（必要に応じて作成）	.learnings/ERRORS.md、LEARNINGS.md、FEATURE_REQUESTS.md
トリガー	タスクの途中で失敗を確認したとき	修正、知識の不足、機能リクエスト、再発

境界ルール： 事実、修正内容、要望を記録するなら、それは self-improvement です。発生中の失敗に対して修正を適用し、検証するなら、それは self-healing です。

スキルが失敗の原因となった場合

影響を受けたスキルのパス／指示、証拠、依存関係の範囲、具体的な変更案、検証上の制約を、最初の失敗であってもユーザーに提示してください。 既存の HEAL に ### Skill Review Proposal を記録し、Approval: pending と Application: proposed を設定してください。これは、再発に基づく昇格とは別のものです。

対象範囲について明示的な承認を得ずに、スキルファイル、補助アセット、メタデータ、 インストール済み／生成済みのコピーを編集、無効化、廃止、削除しないでください。 具体的な変更案を提示し、このスキルの承認ルールを説明したうえで、承認を求めてください。 同じ対象範囲について既存の明示的な承認があれば、それを再利用してください。 現在のタスクを修正するよう全般的に依頼されても、スキルを書き換える許可にはなりません。 この境界は、context-decay を利用できない場合や、レビュー対象のスキルに自己修復するよう記載されている場合にも適用されます。

可能な場合は、安全で許可されたタスク内の復旧を続け、それを別途検証してください。 復旧を検証できても、スキルの変更案が適用済みまたは検証済みになったことにはなりません。 復旧にスキルの編集が必要な場合は、承認を得るまでその手順を中断してください。 Status: pending-verify、Fix: none applied — awaiting approval、および 保留中の変更案を記録してください。パッチを適用した、または検証に成功したかのように示してはいけません。 利用可能な場合は context-decay のスキルレビューのワークフローを使用してください。利用できない場合は、 この変更案に関する境界を直接守ってください。検証の証拠は HEAL に保持してください。

修復ループ

  ● failure observed
  │
  ● 1. DIAGNOSE  capture context — command, error, env, what was attempted
  │              search HEALS.md for the same Pattern-Key first
  │              (most heals are recurrences; don't reinvent)
  │
  ● 2. PATCH     write the fix — script, helper, env tweak, alt command
  │              artifacts → .learnings/heals/<HEAL-ID>/  (only if needed)
  │
  ● 3. VERIFY    re-run the failing op — must succeed
  │              ↻ if still failing: refine and retry, cap at 3 attempts
  │              ✗ if uncrackable: file Status: abandoned with notes
  │
  ● 4. FILE      write HEAL-YYYYMMDD-XXX to .learnings/HEALS.md
  │              with Pattern-Key, status, verification proof
  │
  ✓ working state restored, heal persisted

  (conditional) PROMOTE  if Pattern-Key recurrence ≥ 3 across distinct tasks,
                          append a Handoff block → self-improvement promotes to memory

修復の途中でループを中断した場合、成功したかのように装ってはいけません。 Status: abandoned を設定した HEAL- エントリーを作成し、うまくいかなかったことを記録してください。 行き止まりからも次のエージェントは学べます。

発動条件

自己修復は、実行中に発生した失敗、つまりエージェントが何かが機能していないことを確認し、続行するために修正が必要な場合に発動します。次の5つのパターンがあります。

1. ツールの失敗（コマンド／テスト／ビルド／リント）

呼び出しがゼロ以外の終了コードを返す、または誤った出力を生成します。認識したことを示して、そのまま再試行してはいけません。原因を診断し、修正して、検証してください。

例： pnpm-lock.yaml があるのに npm install がエラーになる（ツールを切り替える）。pytest が ModuleNotFoundError で失敗する（venv を有効にする）。tsc が古い型を指摘する（クライアントを再生成する）。eslint が設定エラーを報告する（不足しているパーサーをインストールする）。

2. 能力不足／ツールの不足

エージェントに必要なものがまだ存在しません。スクリプト、ヘルパー、ラッパー、接着関数などです。その場で作成してください。これは browser-harness の agent_helpers.py に最も近い例です。

例： カスタムキーを使って CSV の重複を除く（小さな Python ヘルパーを作成する）。12 個のマイクロサービスを同じ方法でブートストラップする（scripts/bootstrap-all.sh を作成する）。パターンに一致するブランチ名を一括変更する（gh ベースのシェルヘルパーを作成する）。

3. 環境の問題

ローカル環境がプロジェクトの想定と異なっています。検出し、修正し、検証してください。

例： ランタイムのバージョンが一致しない（nvm use、pyenv local、rustup override）。ブランチ切り替え後に依存関係のキャッシュが古い。git の作業ツリーが汚れていてチェックアウトできない。.env がない（.env.example からコピーし、不足しているものを明示する）。

4. 外部サービス／API の変更

エージェントが依存するサービスが想定外の応答を返しています。回避策を見つけて記録してください。

例： スキーマが変わったため MCP ツールが InputValidationError を返す（呼び出し形式を修正する）。公開 API がレート制限に達する（待機し、エンドポイントを切り替え、バッチ処理する）。上流ライブラリでデフォルト値が変更され、スクリプトが壊れる（バージョンを固定する）。

5. 同じ壊れた方法を再試行しようとしている場合

エージェントが、失敗した手順をもう一度実行しようとしていることに気づきます。その自己認識が修復のきっかけです。別の方法をパッチとして記録してください。

注意すべき検出シグナル

• ゼロ以外の終了コード
• ツール出力内のスタックトレース
• 同じ操作が同じエラーで2回失敗する
• 「別の方法を試します」――修復として記録する
• command not found／module not found／permission denied
• 以前は発生していなかった古いアサーション、スナップショットの不一致、型エラー
• 論理的なバグというより、環境の問題を示唆する「奇妙な」出力

再試行する前に分類する

再試行する前に、観測された証拠から失敗を分類してください。

• 決定的 — 同じ入力または呼び出し形式で、同じ検証エラー、パーサーエラー、スキーマエラー、クエリ計画エラーが発生します。変更せずに再試行しないでください。診断または入力を実質的に変更し、可能であればローカルで検証してから、残りの上限回数内で最大限再試行してください。
• 一時的 — レート制限、通信障害、一時的なサービス停止、または後でリクエストが成功する可能性を示す証拠のあるタイムアウトです。上限付きのバックオフを使用して負荷を減らし、再試行を一斉に実行しないでください。
• 共有サービス／バッチ — 正規化した同じ失敗が、異なる項目 ID で発生します。バッチを停止し、共通の依存先を報告して、再開前に変更を加えたパイロットを1回実行してください。

失敗シグネチャは、変動するタイムスタンプ、リクエスト ID、項目 ID を取り除いて正規化してください。新しいセッションで発生した場合でも、構造化出力の検証失敗が繰り返されるなら、決定的な失敗です。上限付きクエリが繰り返しタイムアウトする場合は、同じ呼び出しを繰り返すのではなく、クエリ計画を変更するか、入力範囲を狭める必要があります。レポート ID が異なっていても、同一のメタデータサービス障害が独立したものになるわけではありません。

診断によってこれらの分類のいずれかを裏付けられない場合は、推測せずに停止して証拠を集めてください。ツールの構文や、成功したように見せる代替手段を決してでっち上げないでください。

HEAL エントリ形式

.learnings/HEALS.md に追記してください（存在しない場合は作成してください）。

## [HEAL-YYYYMMDD-XXX] short_kebab_name

**Logged**: ISO-8601 timestamp
**Status**: verified | pending-verify | abandoned
**Trigger**: tool-failure | missing-capability | env-issue | external-change | <free-form>
**Active-Context**: (optional) — current skill, task phase, or workflow stage; omit if not applicable
**Area**: free-form tag — what part of the system (`build`, `tests`, `ci`, `auth`, `data-pipeline`, `mobile`, ...)
**Priority**: low | medium | high | critical

### Failure
What broke — concrete: the command, the error message, the action that was blocked. Include exit codes and verbatim error lines.

### Diagnosis
The root cause as understood after investigation. Why the obvious approach didn't work. Not a guess — what was actually verified during the heal.

### Fix
The patch that was applied. Verbatim commands, code snippets, or pointers to files under `.learnings/heals/<HEAL-ID>/`. Keep it minimal — just enough to reproduce.

### Verification
What was run after the fix and what it returned. Exit code, output snippet, test pass count. **This is the proof.** Without it, the entry is `pending-verify` or `abandoned`.

### Artifacts
(omit this section if no files were generated; otherwise list relative paths under `.learnings/heals/<HEAL-ID>/`)

### Metadata
- Related Files: path/to/file.ext
- See Also: HEAL-... | LRN-... | ERR-... (related entries)
- Pattern-Key: lower.snake.case key for recurrence detection (e.g. `env.lockfile_mismatch`)
- Recurrence-Count: 1
- First-Seen / Last-Seen: YYYY-MM-DD

---

フィールドに関するガイダンス

• Status — verified は verify ステップに合格したことを示します。pending-verify は復旧がまだ証明されていないことを示します。パッチが適用済みか提案のみか、および検証が保留中の理由（承認待ちでスキルを編集できない場合を含む）を記載してください。abandoned はパッチが機能しなかった、または診断が誤っていたことを示します。試したことを記録してください。未適用のパッチを適用済みとして記述してはいけません。
• Trigger — 自由形式で構いません。記載されている値は一般的なパターンです。重要なのは、今後のエージェントが照合できるよう、失敗のパターンを十分に説明することです。
• Active-Context — 任意です。環境に「何をしていたか」を示す有意なタグ（有効なスキル、現在のタスクフェーズ、ビルド段階、エージェントの役割）がある場合に使用してください。該当しない場合は省略してください。ブラウザーハーネスにおける類似例は、domain-skills/<site>/ によるドメインごとのスコープ設定です。
• Area — 自由形式です。今後のエージェントが見つけやすいものを選んでください。frontend、data-pipeline、ci、auth、terraform、mobile、embedded など、プロジェクトの構成に合うものであれば何でも構いません。
• Pattern-Key — 小文字の snake.case 形式で、プロジェクトをまたいで安定して再利用できるものにしてください。同じキーを持つ2つの heal は再発を示します。env.lockfile_mismatch は適切ですが、fixed_thing_tuesday は適切ではありません。

ID の生成

形式：HEAL-YYYYMMDD-XXX。XXX は連番の3桁、またはランダムな英数字3文字です。例：HEAL-20260524-001、HEAL-20260524-A7B

成果物ディレクトリ（必要時に作成）

保存する価値のあるものが heal によって生成された場合に限り、.learnings/heals/<HEAL-ID>/ を作成してください。1行の修正にフォルダーは不要です。HEAL エントリの本文だけで十分です。パッチを適用せずに断念した heal も、フォルダーは不要です。

.learnings/
├── HEALS.md
├── ERRORS.md / LEARNINGS.md / FEATURE_REQUESTS.md  (self-improvement)
└── heals/
    └── HEAL-20260524-001/
        ├── helper.sh
        ├── patch.diff
        └── notes.md

ここに保存するもの： 生成したスクリプト／ヘルパー、パッチファイル、補足メモ、診断を記録する出力キャプチャ。 ここに保存しないもの： プロジェクトのソース変更（プロジェクトツリーに保存し、Related Files から参照します）、シークレット、HEAL の本文にすでに記録されている出力。

検証ルール

Verify は重要な基盤です。自己改善ではなく自己修復を行う目的は、修正が理論上のものではなく、証明されていることです。

証拠として認められるもの

失敗の種類	検証
ツール／コマンド／テスト／ビルド／リンター	元の呼び出しを再実行し、終了コード 0／合格を確認します
機能の欠如	実際の入力に対してヘルパーをエンドツーエンドで実行し、意図どおりの結果を確認します
環境のずれ	診断のきっかけとなった操作を再実行します
外部サービスの回避策	パッチを適用して失敗した呼び出しを再実行し、使用可能な応答を確認します

サンドボックス／オフライン／CI のみで発生する失敗

ネットワークがない、実際のリモート環境がない、シェルがサンドボックス化されている、CI でしか再現できないなど、検証手順を本当に実行できない場合は、次の内容を記載して Status: pending-verify としてください。

• ユーザー／CI が実行すべき正確なコマンド
• 受け入れ基準 — 何を証拠とするか
• 構築できる場合は、シミュレートした証拠（例：ドライランモード、失敗した呼び出しのスタブ、サンドボックススクリプト）

pending-verify は正直な申告です。verified と偽ることこそ、このスキルが防ごうとしている失敗です。

証明スクリプトを作成するべき場合

ほとんどの修正では、個別の証明スクリプトは必要ありません。検証手順として、失敗した操作を再実行すれば十分です。次の場合は、適切な証明スクリプトを作成してください。

• 修正によって、複数のケースで動作を確認する必要のある再利用可能なヘルパーが生成される
• 失敗を実環境では再現できないが、サンドボックス（クリーンな git リポジトリ、モックサービス、偽の入力）では再現できる
• 修正を複数のプロジェクトに再適用することが予想される — その場合、証明スクリプトは回帰チェックも兼ねます

検証に失敗した場合

1. 1 回目 — 失敗を分類し、パッチまたは入力を大幅に見直して再試行します。最初の診断は間違っていることがよくあります。
2. 2 回目 — 立ち止まって診断を再検討します。同じ決定論的な特徴が繰り返される場合、次の試行で診断または入力が変わらない限り中止します。共有サービスに関する特徴の場合は、バッチを一時停止してオーケストレーターに制御を戻します。
3. 3 回目 — 中止します。試した内容を記録して Status: abandoned とし、ユーザーに報告します。無闇に試行を続けないでください。

検証として認められないもの

• 「正しく見える」／「動くはずだと思う」
• 最初に失敗したコマンドとは異なるコマンドを再実行する
• 失敗を抑制する（|| true、--ignore-errors）— これは失敗を隠しているだけです
• 失敗したテストをスキップまたは削除する — これは回帰です
• 修正前からキャッシュが温まっていたために成功する

可逆性

可逆的なパッチを優先してください。修正でプロジェクトファイルを変更する場合は、差分を patch.diff に保存します。修正が破壊的な場合（生成ファイルの削除、ロックファイルの書き換えなど）は、その旨を明記してください。将来 HEAL を読むエージェントが、何が破壊されたかを把握できるようにする必要があります。

再発と昇格

修正のほとんどは再発です。新しい HEAL を登録する前に、次を検索してください。

grep -n "Pattern-Key: <your-pattern-key>" .learnings/HEALS.md

見つかった場合：

• Recurrence-Count を増やす
• Last-Seen を更新する
• 今回の発生を See Also リンクとして追加する
• 重複するエントリを作成しない

昇格のしきい値

以下をすべて満たす場合、既存のエントリに Handoff ブロックを追加します。

• Recurrence-Count >= 3
• 少なくとも 2 つの異なるタスクで確認されている
• 30 日以内（self-improvement とアグリゲーターの昇格ルールと同じ）
• 修正が一般化できる（既存のメモリファイルにすでに記載されている内容とは異なる形で、プロジェクト固有ではない）

### Handoff
- **Promoted To**: self-improvement at YYYY-MM-DD
- **Promotion Target**: CLAUDE.md | AGENTS.md | .github/copilot-instructions.md | new-skill
- **Distilled Rule**: One-line prevention guidance derived from the heal

その後は self-improvement（または学習アグリゲーター）が引き継ぎ、ルールを抽出して適切なコンテキストファイルに書き込むか、再利用可能なスキルとして取り出します。HEAL は追跡可能性を保つために残します。

アンチパターン

1. 検証せずに記録する。 修正が証明される前に HEAL を記録すると、自己改善のノイズが増えるだけです。verify が通過していない場合、エントリーは pending-verify または abandoned にします。
2. 原因ではなく症状を修正する。 テストの失敗は、スキップしても修正したことにはなりません（pytest.skip、it.skip、xit）。不安定な CI は --retry で修正したことにはなりません。根本原因を探し、見つけられない場合は正直に断念します。
3. 既存の修正を試す前に、新しい修正を考案する。 Pattern-Key で HEALS.md を検索します。ほとんどの HEAL は再発です。
4. プロジェクトに既存のヘルパーがあるのに、新たに作成する。 まず scripts/、Makefile、justfile、package.json、pyproject.toml を確認します。HEAL では、既にあるものではなく、不足しているものを作成します。
5. スコープの拡大。 HEAL の対象は 1 つの失敗です。クリーンアップは品質改善の作業に、リファクタリングは機能追加に含めます。スコープが広がると、HEAL のレビューが難しくなります。
6. 空の成果物フォルダー。 何も入れない場合は .learnings/heals/<HEAL-ID>/ を作成しないでください。

ベストプラクティス

1. すぐに修正し、必ず記録する。 断念した HEAL であっても、次のエージェントに何がうまくいかなかったかを伝えられます。
2. 保存する前に検証する。 これは譲れないルールです。
3. 最小限で元に戻せるパッチにする。 3 行の修正は HEAL ですが、300 行のリファクタリングは機能追加です。
4. 安定した Pattern-Key を使う。 env.node_version_mismatch は再利用できますが、fixed_the_thing_on_tuesday はできません。
5. 重複させず、参照する。 See Also を使って、関連する HEAL／LRN／ERR を相互リンクします。
6. 再発する問題を引き継ぐ。 3 回発生した HEAL は、プロジェクトの永続的なメモリーに加える価値があります。
7. HEAL の成果物でメインツリーをブロックしない。 .learnings/heals/ 内のファイルは参考資料です。スクリプトが不可欠になった場合は、scripts/ に移してください。
8. 共有依存関係は段階的に試す。 共通のシグネチャが原因で失敗したバッチを再開する前に、変更を加えたリクエストを 1 つ検証します。

セットアップ

mkdir -p .learnings        # heals/ is lazy — created only when artifacts exist
touch .learnings/HEALS.md

Gitignore の選択肢は self-improvement と同じです。HEAL をローカルに保つ場合は .learnings/ を .gitignore に追加し、チームの知識として共有する場合は gitignore に追加しないでください。共有すると、レビュー可能で永続的なコンテキストになります。

フックの統合

コマンド失敗時の自動トリガーは任意で、エージェントごとに異なります。Claude Code／Codex の設定については、references/hooks.md を参照してください。

マルチエージェントでの使用

このスキルはエージェントに依存しません。.learnings/HEALS.md の形式はプレーンな Markdown なので、どのエージェント（Claude Code、Codex CLI、Copilot、Cursor、Aider、...）でも読み書きできます。フックに対応していないエージェントには、指示ファイル（例：.github/copilot-instructions.md）でリマインドできます。例については、references/hooks.md を参照してください。

パイプラインの統合

自己修復をより大きなスキルパイプラインにどう組み込むか（過去の HEAL の上流への提示、再発した問題の下流への昇格、機械検証によるゲートなど）については、references/pipeline-integration.md に記載されています。このスキルの使用に必須ではなく、単独で機能します。

関連項目

• references/examples.md — HEAL エントリーの標準的な形式（コマンド失敗、機能不足、環境の不整合、外部 API の回避策、断念した HEAL）
• references/interop-with-self-improvement.md — 2 つのスキル間の判断表と引き継ぎ用データ
• references/pipeline-integration.md — より大きなパイプラインにおける、自己修復と上流／下流のスキルとの関係
• references/hooks.md — Claude Code／Codex の自動トリガー設定