self-improving-agent

自己改善型エージェント

完了した作業から得た証拠を、小さく監査可能な動作変更につなげます。 デフォルトの結果は候補または変更なしであり、スキルが自動的に書き換えられることはありません。

このスキルを使用する場面

• ツールやワークフローが、再発する可能性のある形で失敗した場合。
• ユーザーが前提、要件、または運用ルールを修正した場合。
• 同じ回避策が複数回現れた場合。
• 限定的なテストで、より適切な再利用可能な方法が実証された場合。
• ユーザーから学習候補の確認や統合を依頼された場合。

定例のセッション要約、生のトランスクリプトの保存、証拠のない推測上のアイデア、またはプロジェクトのドキュメントに記載すべきプロジェクト情報には使用しないでください。

必須の結果

各実行は、必ず次の状態のいずれか1つで終了します。

1. candidate：再利用可能ですが、まだ検証されていません。
2. validated：代表的な証拠が教訓を裏付けていますが、オーナーへの変更はまだ主張されていません。
3. applied：検証済みの教訓が、変更参照とともに、名前を特定した1つの永続的なオーナーに反映されています。
4. rejected：誤り、安全でない、特定の状況に限定されすぎている、または古くなっています。
5. superseded または rolled_back：適用済みまたは検証済みの教訓が置き換えられたか、元に戻されました。
6. no-delta：再利用可能な動作変更は見つかりませんでした。
7. open-question：証拠が不十分で、不足している証明が明記されています。

成果物は改善の証明ではありません。教訓を適用したとみなすには、今後の動作を変え、その変化を示す代表的なチェックが必要です。

開始パケット

永続的なガイダンスを編集する前に、次の内容を明記してください。

• 今後の動作：次回、エージェントが何を変えるべきか。
• 代表的なタスク：変更後に成功するはずの具体的なシナリオを1つ。
• 証拠：現在のソース、失敗時の出力、ユーザーによる修正、または限定的なテスト。
• オーナー：教訓を管理する1つのスキル、指示ファイル、スクリプト、またはランタイムコンポーネント。
• 書き込み境界：変更を許可するファイルと、ローカルに留めるべき情報。
• 証明：新しい動作を確認するコマンド、評価、またはレビュー。

いずれかが不明な場合は、候補として記録し、検証または適用に進む前に停止してください。

ライフサイクル

1. シグナルを記録する

解釈よりも事実を優先します。再利用可能な最小限の要約のみを記録し、トランスクリプト、ツール入力、認証情報、非公開パス、顧客データをコピーしないでください。

apb init --hooks で明示的に有効にした Claude Code の失敗フックは、次を呼び出すことができます。

agent-playbook self-improve

手動での修正や成功は、明示的な要約と証拠ラベルを使用します。

apb self-improve capture \
  --kind correction \
  --summary "Verify the current source before relying on cached state" \
  --evidence "focused-test"

CLI は、編集済みイベントと重複排除された候補を ~/.agent-playbook/self-improvement/ に保存します。ルートを上書きするには、AGENT_PLAYBOOK_DATA_DIR または --data-dir を使用します。

2. 再利用可能性を評価する

次のすべてに当てはまる場合のみ、候補として残してください。

• 何が起きたかだけでなく、今後の動作を記述している。
• 1つの非公開タスクやリポジトリを超えて役立つ。
• 現在の権威ある情報源と矛盾しない。
• 対象を絞ったオーナーと、現実的な検証方法がある。

優先順位付きキューを確認するには、apb behavior inbox を使用します。証拠が繰り返されると発生回数は増えますが、真実性が自動的に高まるわけではありません。ローカルの候補を確認するには apb behavior owners <candidate-id> --repo . を使用します。ただし、すべての結果はオーナーを決定するものではなく、レビュー候補として扱ってください。

3. 検証する

候補を反証できる最小限の証明を選び、それを実行可能な成果物として記述して、apb self-improve eval で実行します。スキーマと安全性の境界については、references/eval-artifact.md を参照してください。

候補	最低限必要な証明
プロンプトまたはワークフローのルール	代表的なプロンプトと評価基準
CLI／ランタイムの動作	限定的な自動テスト
外部連携	現在のドキュメント／ランタイムに対する、実際の機能チェック
安全性ルール	安全でない経路が阻止されることを示すネガティブテスト
繰り返し使われるヒューリスティック	複数の独立した事例、または人による明示的な確認

事実、仮説、不足している証拠を分けてください。構造上の検証だけでは、ガイダンスの内容が現在も有効であることや、ホスト上で実行できることの証明にはなりません。

4. 検証、適用、または却下

まず成果物を実行します。以前の動作を安全に再現できる場合は、ベースラインシナリオを推奨します。少なくとも1つの候補シナリオが必要です。

apb self-improve eval cand-123 --artifact behavior-eval.json

apb self-improve review cand-123 \
  --decision validate \
  --reason "baseline reproduced and candidate scenarios passed" \
  --eval-result /path/printed/by/the/eval/command.json

検証で受け入れられるのは、同じ候補に対する CLI 生成の評価結果が合格した場合のみです。実行時の動作が変わったと主張するものではありません。

オーナーを編集する前に、ローカルの Behavior Change Proposal を生成します。

apb behavior proposal cand-123 \
  --owner "skill:self-improving-agent" \
  --output behavior-proposal.md

この提案には、動作差分の意図、評価の証拠、受け入れ基準、プライバシーの境界、ロールバック計画が含まれます。オーナーを編集したり、リモートのプルリクエストを作成したりすることはありません。

永続的なオーナーをちょうど1つ変更した後、その適用を別途記録します。

apb self-improve review cand-123 \
  --decision apply \
  --reason "installed after the focused test passed" \
  --owner "skill:self-improving-agent" \
  --change-ref "commit:abc123"

その他の判断：

apb self-improve review cand-123 --decision observe --reason "needs a second episode"
apb self-improve review cand-123 --decision reject --reason "project-specific exception"

最も範囲の狭いオーナーに適用します。

1. 動作を強制できる場合は、実行可能なテスト、スクリプト、またはバリデーター。
2. エージェントの判断が必要な場合は、オーナーとなるスキル、またはそのリファレンス。
3. プロジェクト全体に適用される制約に限り、プロジェクトの指示。
4. 常に読み込むのではなく、検索して取得するべき永続的な事実には、ナレッジノートブック。

記録の副作用として、リポジトリのルールを黙って変更したり、パッケージを公開したり、外部アクションを実行したりしてはいけません。

5. ループを実証する

適用後に代表的なタスクを実行します。以下を報告してください。

• 候補 ID と最終状態
• 使用した証拠と、未確定の事項
• 変更した永続的なオーナー
• 実行可能な評価の結果と成果物のハッシュ
• ロールバックの方法

新しいルールによって代表的な動作が変わらない場合は、元に戻すか、却下してください。

ナレッジのエクスポート

適用済みのルールと未解決の候補を、Obsidian または別のローカルナレッジシステム用に Markdown としてエクスポートします。

apb self-improve export --output /path/to/vault/Agent/Learning.md

エクスポート先は出力先であり、信頼できる唯一の情報源ではありません。候補と有効なルールの状態は、引き続き CLI のデータディレクトリで構造化され、監査可能な状態に保たれます。

ホストの境界

スキルは判断を記述し、ホストアダプターはイベントとアクションを提供します。対応状況を示す前に、現在のホストを確認してください。

• Claude Code：決定論的な失敗フックは、明示的な apb init --hooks によってのみインストールされます。
• Codex、Gemini、DeepSeek Harness：スキルの配布には対応しています。学習イベントの配線は、各ホストの現在の拡張 API に依存します。
• 対応していないフックは、手動またはアダプター固有のままにする必要があります。文書化されていない動作を使ってシミュレートしてはいけません。

apb conformance を使って、ローカルの静的コントラクトを確認します。配布またはフック設定が proven であっても、ホストによる検出や実行時の呼び出しが証明されたことにはなりません。範囲が限定された証拠を提供するホスト実行が観測されるまで、それらは unverified のままです。

スキーマとアダプターのコントラクトについては、references/learning-lifecycle.md を参照してください。このスキルを変更する場合は、evals/cases.json と evals/rubric.md を使用してください。

完了チェックリスト

• 候補を採用しない場合の判断が明示されています。
• 保存するテキストは最小限で、機密情報が除去され、移植可能です。
• 関連する場合、現在の信頼できる情報源を確認しています。
• 検証では、同じ候補に対する実行可能な評価結果が合格していることを確認しています。
• 適用先として永続的なオーナーを1つ指定し、具体的な変更参照を記録しています。
• 適用後に代表的な動作をテストしています。
• プライベートなプロジェクトの詳細を、公開スキルのアセットに含めていません。