improve-system

システムを改善する — 効果を測定する改善ループ

システム自身の修正履歴から繰り返し発生する失敗パターンを見つけ、却下率の指標を時系列で追跡し、対象を絞った編集を提案します。**提案のみとし、自動適用はしません。**これは、測定できない作業向けに適応させた自動リサーチループです。チャット履歴の修正を代理シグナルとして、QA却下率をトレンド指標として使用します（video-insights の改善 #5、2026-06-12）。

対象範囲

• /system-audit は、一度だけ修正すればよい具体的なバグやずれを見つけます。/improve-system は、複数の実行にわたる繰り返し発生する行動パターンを見つけ、恒常的なルールにします。
• /li curate は、エージェントのオーバーレイをスキルの差分に統合します（3 回以上の実行が条件）。重複しないでください。パターンの根拠がオーバーレイにしかない場合は、ここで差分を作成せず、「CURATE 経由」と記してください。このスキル固有の対象は、QA ログ、却下率の指標、セッション履歴の修正です。
• /grade-system は全体的な品質の姿勢を評価します。このスキルは修正とコストを測定しますが、評価はしません。
• モデルのルーティングに関する判断は、ログだけを根拠にここで行いません。下記の「ルーティングに関する質問」を参照してください。
• 指標のない改善ループは儀式にすぎません。提案が何もない場合も、毎回、指標を報告してください。

手順

1. シグナルを収集する（作業フォルダー内で並行して読み取ります）。

   • agent-improvements/qa-rejection-log.md — 判定、再委任回数、理由（主要指標）。
   • agent-improvements/qa-disagreement-log.md — Ane または Ann が QA の判定を覆した箇所。
   • agent-improvements/cost-calibration-log.md — 見積もりと実績のずれ、および各セッション行内の番号付き較正シグナル一覧。これはシステムが持つ最も情報量の多い修正チャネルです。各行には、何がうまくいかなかったか、何が誤診されたか、発生源で何が修正されたかを示すシグナルが 5～9 個記載されています。前回の実行以降に追加されたすべての行について、コスト欄だけでなくシグナル一覧も読んでください。Run 5（2026-07-31）の根拠：リストに挙げた直接モードの 3 つのチャネルからは何も得られませんでしたが、3 行にわたる 19 個のシグナルから、今回見つかったすべてのパターンが得られました。この表はファイルの最後のセクションです（Run 7 P4、2026-08-05 に再構成されたため、ファイル末尾への追記は表の中に追加されます）。最新の行は表の末尾にあります。
   • agent-improvements/{ann,vi,li,researcher}-overlay.md の ## Active Improvements セクション。
   • .remember/recent.md および .remember/today-*.md — Ane が会話中に行った修正の、セッション履歴を使った代理シグナル。
   • agent-improvements/pre-flight/*-lessons-learned.md — 4 つの従来型成果物クラスに関する直接モードの修正シグナルです。作業のほとんどは現在、単独／直接で行われており（Ann／Vi のオーケストレーションなし）、QA却下ログは意図的に情報が不足しています。直接的な成果物の修正はこれらのログに記録されます。agent-improvements/pre-flight/ 以下にある *-lessons-learned.md をすべて読んでください。
   • 対象期間中に作成または更新されたフィードバックメモリー — 4 つのクラスログの対象外となるすべての作業について、直接モードのシグナルとなります。従来型クラスに含まれない成果物（Excel ツール、運用ドキュメント、パイロット計画、メール、スキル）の修正は、クラスログではなく、セッションメモリーディレクトリ内の feedback_* メモリーに記録されます。メモリーディレクトリ内のファイルを更新日時順に一覧表示し（ls -l --time-style=+%Y-%m-%d）、対象期間内の feedback_* エントリーを読んでください。Run 2（2026-07-17）の根拠：クラスログには 10 週間にわたり記録がありませんでしたが、フィードバックメモリーには実際の修正が 3 件ありました。
   • agent-improvements/improve-system-runs.md — 過去の実行（却下された項目を再提案しないため）。

2. メトリクスの傾向を把握します（4 つのシグナル）。

   • オーケストレーションされた実行（qa-rejection-log）。 報告する内容：記録されたオーケストレーション実行の総数、再委任または PASS 以外の判定があった割合、繰り返し発生している理由の上位 3 件、前回実行時の数値との比較。 このログが対象とするのは Ann/Vi のオーケストレーションのみです。明らかにオーケストレーションを実行したセッションの後にログが空の場合、これは「wrap-up の 4b ログ記録ステップが失敗している」という問題、つまりログ記録の欠落です。ただし、対象期間の作業がダイレクトモードだった場合、ログが空なのは想定どおりであり、問題ではありません。結論を出す前にどちらなのか確認してください（セッション履歴と cost-calibration-log を確認し、対象期間にオーケストレーションされた実行があったかを調べます。また、予想していた実行より前にログが作成されていることを確認します）。

   • ダイレクトモードでの修正、従来のクラス（事前確認用の lessons-learned ログ）。 各 *-lessons-learned.md について、対象期間内のエントリ数と、繰り返し発生している修正テーマを報告します。この 4 つのログ（ToC、indicator framework、evaluation design、evidence brief）は、該当するクラスの成果物が実際に納品されたときにのみ記録されます。該当する成果物がない期間にログが空なのは想定どおりであり、問題ではありません。同様に傾向を把握します。同じテーマの修正が繰り返し増えている場合は、ルールが適用されていません。

   • ダイレクトモードでの修正、その他すべて（feedback memories）。 対象期間内に作成または更新された feedback_* メモリの数と、そのテーマを報告します。対象期間の作業内容が 4 つのクラス別ログに当てはまらない場合、これがダイレクトモードの最新シグナルとなります。複数のメモリにまたがるテーマの繰り返しは、パターン候補です。既存の feedback memory のルールに該当する修正は、ルールが適用されていない失敗として、より重く評価します。

   • ダイレクトモードでの修正、キャリブレーションシグナル（cost-calibration-log の行）。 前回の実行以降に追加された行数と、それらに含まれる番号付きシグナルの数を報告し、その後、シグナルをテーマごとに分類します。既存のルールを指摘するシグナルは、feedback memories とまったく同じように、ルールが適用されていない失敗として重く評価します。/wrap-up はすべてのセッションで 1 行を記録するため、作業内容が変わってもこのチャネルが途絶えることはありません。この性質は、他の 3 つのチャネルにはありません。

3. パターンを分類します。 パターンとして扱うには、実行またはログをまたいで独立した発生が 2 回以上必要です。1 回だけの発生は要観察項目として記載しますが、対応は行いません。各パターンは、発生箇所を挙げて 1 文で説明します。

4. 編集を提案します。 パターンごとに、対象箇所（CLAUDE.md のルール、スキルの編集、エージェントの編集、チェックリスト、feedback memory、または禁止事項用の PreToolUse フック）、編集文案、メトリクスへの期待される効果を示します。すべての提案を番号付きリストで提示し、Ane が項目ごとに承認、却下、または保留するまで待ちます。

5. 承認された項目のみ適用します。 Edit ツールを使用し、対象範囲を限定します。対象ファイルが存在する場合は、mel_wiki/wiki/concepts/edit-preservation-protocol.md を適用します。

   生成されたミラーではなく、正規ファイルを編集します。 このスキルが書き込む対象のうち、いくつかは同期スクリプトによって再生成されるミラーです。claude-ai-shareable-export/* はリポジトリのルートにある同名ファイルから、.claude/skills/<name>/SKILL.md は個人用スキルのクローンから、.claude/agents/* は ~/.claude/agents/ から生成されます。ミラーへの編集は次の同期まで残りますが、その後はエラーなしに消失します。エクスポート、ミラー、またはキャッシュのディレクトリ内のファイルを編集する前に、どのファイルを生成しているかを調べ（同期スクリプトでファイル名を grep し）、生成元を編集してください。証拠：Run 4 では claude.ai のスコープゲート変更を claude-ai-shareable-export/ に書き込み、同じターン内に sync_shareable_export.py がそれを上書きしました。 承認済みの項目によってスキルファイルまたはエージェントファイルが編集された場合は、実行を終了する前にハーネスを再実行してください。 SKILL_BUDGETS（tests/run_tests.py）の行数上限がこれらのファイルを制限しているため、ルールを追加すると上限を超え、最後のハーネス実行で初めて失敗が表面化することがあります。数値は変動するため、推測せず、この辞書から現在の上限を確認してください。上限超過を修正する場合は、追加した内容を隣接する段落にまとめてください。自分が書いていない内容を削ってはいけません。根拠：Run 3では、vi の再試行ルールを1つ追加したことでファイルが2行超過し、追加のコミットが必要になりました。

6. 実行を終了します。 日付入りの要約（メトリクスの数値、見つかったパターン、提案と Ane の決定）を agent-improvements/improve-system-runs.md に追記します（ファイルが存在しない場合は、# Improve-System Run Log の見出しを付けて作成します）。次に、定期実行の記録を付けます：python ~/.claude/hooks/maintenance_due.py --mark improve-system 2>/dev/null || true

Spend-audit モード — トークンの実際の使用先

支出に関するトリガー（「トークンはどこに使われているのか」「トークン監査」「なぜこのセッションは高くついたのか」「コンテキスト最適化」）があった場合、またはステップ2の傾向分析で説明すべきコスト異常が見つかった場合に実行します。読み取り専用です。出力は Tier 1 の作業用ブリーフで、許可される書き込みは、オプトインのバックログ行のみです。token-economy-audit のバックログ項目から統合されました（2026-08-05）。2026-07-30 の手動実行が証拠の基盤です。

1. 常時読み込まれる基準量をセッション内で計算します。保存済みの数値を引用してはいけません。 ユーザーとプロジェクトの CLAUDE.md、MEMORY.md、スキルのフロントマター合計、エージェントのフロントマター合計、SessionStart の挿入内容の現在のサイズを合計します。実測値のルールが最も重要になるのはここです。このターンで計算していない支出の数値は、数値ではなく⚠️データの欠落です。
2. ctx_execute_file を使って agent-improvements/cost-calibration-log.md をデータセットとして分析します。Read は使ってはいけません。 ファイルは140k文字を超えており、large_read_gate フックが範囲を指定しない Read を拒否します。行ごとの出力1kあたりのドル額、キャッシュ書き込み比率、「Calibration signals」ブロックをすべて抽出して、要因表にまとめます。既知の3つの要因（出力量、キャッシュ書き込み、仕様作成後のクリア）は、これまでログを最初から最後まで読んで初めて見つかりました。この監査は、誰も手作業で同じことを繰り返さずに済むように設けられています。
3. （節約額 × 信頼度）/ 作業量で施策の優先順位を付けます。 各施策を、品質中立、品質向上、またはトレードオフのいずれかに分類します。何を犠牲にするのかを明確に示さずに、トレードオフを提案してはいけません。
4. 最適化してはいけないもの — 恒常的なルールです。 トークン節約のために恒常的な指示を削ってはいけません。基準量そのものがコストではありません。キャッシュ読み取りは93〜99%を占めるため、それを維持しても数セント程度のコストです。一方、その中のルールが出力品質を保っています。支出は、作成した文章量とコンテキストに新たに取り込まれるバイト数に応じて増えます。効果的な施策は厳密さを損なうことではなく、やり直しを減らすことです。手動監査を行えば、おそらく最初に CLAUDE.md を削ろうとするでしょう。それはわずかな節約のために品質を犠牲にする唯一の変更です。このルールがあるのは、そのような事態を防ぐためです。

ルーティングに関する疑問 — ログで判断せず、パイロットを実施する

分析によってモデルのルーティングに関する疑問が浮上した場合 — 特定のモデル階層が関係する修正パターン、Haiku 階層の候補、妥当性が疑われる Opus へのエスカレーションルール、レビュアーモデルの比較など — 修正ログやコストの行だけで結論を出してはいけません。mel_wiki/wiki/concepts/routing-pilot-method.md に従い、欠陥を仕込んだブラインドパイロットを実施します。回答キーを封印し、各ゲートクラスに約10件の欠陥を仕込み、合格基準を事前に宣言したうえで、各条件のトークン使用量を把握できるよう、名前を付けない非同期 Agent を起動します。レジストリ（agent-improvements/agent_registry.md § Routing tiers）では、Haiku 階層を追加する前にパイロットの記録を必須としています。また、パイロットの判定によって削除されたエスカレーションは、再導入前に再検証用のパイロットが必要です。パイロットの判定結果は、cost-calibration-log.md の PILOT 行と、それに伴うレジストリの編集に反映します。ほかの提案と同様に、その編集案もステップ4を通じて提案してください。

危険信号 — こうしたことをしていると気付いたら、作業を止めてください

• Ane が該当項目を承認する前に、編集を適用する。「当然承認するはず」は承認ではありません。
• 「見覚えがある」という理由で、1 回の発生をパターンに格上げする。
• 新たな根拠もないのに、runs log で Ane が却下したことが示されている項目を再提案する。
• 指標の数値を表示せずに「システムは正常です」と報告する。
• 今回のターンで計算していない下限額、支出額、またはコストの数値を引用する（spend-audit モード）。
• モデルのルーティングに関する問題を、シードされた不具合のパイロットではなく、ログから判断する。

言い訳	実態
「修正は簡単だから、適用するだけ」	恒久ルールへの些細な編集も積み重なります。承認が必須です。
「データは少ないけれど、パターンは明らか」	データポイントが 1 つなら、それは逸話にすぎません。監視項目として記録してください。
「ログが空なら、問題のない記録だ」	qa-log が空の場合、ログ記録が壊れているか、オーケストレーションが行われていないダイレクトモードの期間のどちらかです。結論を出す前に、どちらなのか確認してください（オーケストレーションは実行されたか？ ログは想定される実行より前のものか？）。また、ダイレクトモードを示す兆候について、lessons-learned ログと cost-log のキャリブレーションシグナルを確認してください。