winds.from.oz 技術メモ

AI Agent向けContext Hygieneの段階導入

Posted:

AI Agent向けContext Hygieneの段階導入

AI agent に長期運用を任せる場合、ドキュメントは多いほどよいとは限らない。

過去ログ、設計メモ、運用手順、トラブルシューティング、現在の作業状態が同じ場所に増えていくと、agent は読むべき情報を失う。情報が消えるのではなく、常時読む context の中で重要度が埋もれる。

この問題は、短い context だけで解決するものではない。必要なのは、情報を捨てることではなく、読み込む頻度と役割に応じて置き場所を分けることである。

基本方針

常時読むファイルは、現在の正だけを持つ。

履歴や失敗経緯は別の memory index に置く。再発する障害は known issues に昇格する。手順は runbook に、設計判断は design document に置く。

役割は次のように分ける。

current context
  agent が毎回読む working set
  現行構成、現在の制約、危険な前提、読むべき入口だけ

memory index
  過去経緯の索引
  日付、要点、詳細リンク

known issues
  現在も再発しうる障害
  症状、確認コマンド、原因候補、対応

operation docs
  手順、runbook、検証計画、実行境界

system docs
  設計判断、責務境界、contract、恒久制約

troubleshooting docs
  調査記録、原因分析、再発時の切り分け

archive
  現行ではない履歴
  memory index から必要時だけ辿る

この分割にすると、常時読む context を小さく保ちながら、過去判断の再利用性を落としにくい。

自動化は診断から始める

最初から自動移動を入れると危険である。

AI agent が「これは古い」と誤判定して current context から消すと、次回以降の計画が変わる。特に、過去の失敗から抽出した制約は、文章としては古く見えても現在の gate として有効な場合がある。

このため、初期段階では read-only checker に留める。

Phase 1: report
  ファイルを変更しない
  長さ、古い日付、長い bullet、移動候補を表示する

Phase 2: classify
  移動先候補を分類する
  memory / known issues / operation / system / troubleshooting を提案する

Phase 3: propose
  patch 案を作る
  ただし apply しない

Phase 4: apply
  明示指定時だけ実行する
  初期運用では作らなくてもよい

デフォルトは常に read-only にする。checker は判断を強制せず、候補を出すだけにする。

通知はプロンプト内で行う

hook や CI で機械的に失敗させるより、agent が最終回答で相談する形が扱いやすい。

その時点の作業文脈を agent が持っているため、次の判断をしやすい。

  • 一時的な検証経緯か
  • 現在も有効な制約か
  • operation doc へ移すべき手順か
  • known issues へ昇格すべき再発パターンか

出力例:

docs hygiene warning:
- current context: 328 lines, warning threshold 300
- memory index: 910 lines, warning threshold 800

整理候補:
- current context の dated verification detail
  suggested target: memory index

- current context の一時 Job / image / prefix 履歴
  suggested target: operation doc

自動移動はしていない。

この形なら、しきい値超過を error ではなく相談事項として扱える。

MarkdownをSource of Truthにする

永続情報を Markdown と JSON の両方で管理すると、いずれずれる。

このため、永続的な metadata は Markdown front matter に置く。JSON は必要になった時の一時出力に留め、repository には保存しない。

例:

---
status: current
audience: ai
scope: repository
last_reviewed: 2026-05-29
lifecycle: current-context
hygiene:
  max_lines_warn: 300
  max_lines_error: 450
  long_item_warn_chars: 1200
  review_after_days: 30
---

checker は front matter を読む。人間も同じ metadata を読める。

必要になった場合だけ、実行時オプションとして JSON を出す。

Markdown/front matter = source of truth
checker stdout        = human report
JSON output           = optional transient output

これで二重管理を避けられる。

しきい値は緩く始める

初期値は厳しくしない方がよい。

長いこと自体は即座に問題ではない。問題は、常時読むべきではない情報が current context に残り続けることである。

目安:

current context
  300 lines warning
  450 lines error
  1 item 1200 chars warning
  古い日付入りの詳細は移動候補

memory index
  800 lines warning
  1200 lines split suggestion
  1 entry 1600 chars warning

all docs
  missing front matter warning
  stale last_reviewed warning
  broken local link warning

ただし、これらは失敗条件ではない。まずは相談のきっかけにする。

移動先の判断

移動先は、文章の内容ではなく運用上の役割で決める。

内容移動先
次回以降も毎回必要な現行事実current context
完了済みの検証経緯memory index
現在も再発する障害known issues
実行手順、preflight、rollbackoperation docs
採用理由、不採用理由、責務境界system docs
原因分析、ログの読み方troubleshooting docs
現行ではない詳細履歴archive

特に注意すべきなのは、失敗ログ。

失敗ログはそのまま current context に置かない。そこから現在も有効な制約を抽出し、current context か system contract へ昇格する。詳細ログは troubleshooting や archive に置く。

段階導入の進め方

導入順は次のようにする。

  1. 文書上の方針を決める
  2. read-only checker を作る
  3. docs を更新した時だけ checker を実行する
  4. warning は最終回答で相談する
  5. false positive を見ながらしきい値を調整する
  6. 必要になったら --propose を追加する
  7. --apply は最後まで作らない選択肢も残す

最初から hook や CI で失敗させる必要はない。

まとめ

Context hygiene の目的は、情報を減らすことではない。

目的は、agent が毎回読むべき情報と、必要時だけ辿る情報を分けることである。

read-only checker、Markdown front matter、プロンプト内通知から始めると、挙動を急に変えずに導入できる。自動移動は急がない。まずは、肥大化に気づける仕組みを置く方がよい。