AI Agent向けContext Hygieneの段階導入

Posted: 2026-05-29

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、rollback	operation docs
採用理由、不採用理由、責務境界	system docs
原因分析、ログの読み方	troubleshooting docs
現行ではない詳細履歴	archive

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

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

小規模・個人運用での最初の一歩

checker を作る前に試せることがある。

しきい値や削除規律を、current context ファイル自体に行動原則として書くだけで十分なケースがある。

## context hygiene 規律

- タスクが完了したら外部参照（issue tracker・wiki 等）を確認してから即削除する
- このファイルが 300 行を超えたら整理する
- 行動原理・禁則以外の内容が混入していないか確認する

この方法は checker が不要で、agent が毎回 current context を読む限り自然に機能する。shell script や CI を用意するより先に、まずここから始めるとよい。

外部スクリプトを PostToolUse hook として実行する場合、同期実行（async: false）は agent の応答を遅延させ、再編集を誘発すると RAG 等の外部インデックスへの中間状態投入が増える。行動原則として context に書けば、この問題が起きない。

checker が有効になるのは、チーム運用・大規模コードベース・CI 統合など、個人の行動規律だけでは担保できない規模になってからでよい。

段階導入の進め方

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

文書上の方針を決める
しきい値と削除規律を current context に行動原則として書く（checker 不要）
必要を感じたら read-only checker を作る
docs を更新した時だけ checker を実行する
warning は最終回答で相談する
false positive を見ながらしきい値を調整する
必要になったら --propose を追加する
--apply は最後まで作らない選択肢も残す

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

具体的なファイル構成の例（Claude Code + Obsidian）

7層の概念を Claude Code + Obsidian で実装した場合の対応例。

current context  →  ai-context.md
                    行動原理・禁則事項・ツール参照
                    安定情報のみ。タスクは書かない。

memory index     →  memory.md
                    現在の作業タスク（冒頭テーブル）＋長期的な技術的事実
                    完了タスクは即削除。詳細は外部参照に任せる。

operation docs   →  runbook/*.md
                    手順・preflight・rollback

system docs      →  system/*.md
                    設計判断・採用理由・不採用理由

known issues     →  known-issues/*.md
                    再発しうる障害の症状と対応

archive          →  archive/*.md
                    memory index から必要時だけ辿る履歴

この構成では、Claude Code が会話冒頭で常時読むのは ai-context.md と memory.md の2ファイルのみになる。他のファイルは作業に応じて都度参照する。

current context 内の変化サイクル

current context の中でも、情報の変化サイクルは一様ではない。

行動原理・禁則事項・ツール参照: 数週間から数ヶ月単位でしか変わらない安定した情報
現在の作業タスク・ブロッカー: 毎日変わる揮発的な情報

この2種類を同じファイルに混在させると、安定した情報がタスクの更新ノイズに埋もれる。また、完了済みタスクが「✅」に変わっても放置されると、安定情報との区別が難しくなりファイルが肥大化する。

current context を設計するとき、安定情報と揮発情報を分けることを検討する。揮発情報には「完了したら即削除する」という規律が必要になる。「完了したらアーカイブに移す」では、移動先が同じ経路で肥大化する。

制約の賞味期限

昇格した制約は、それ自体が肥大化の原因になる。

制約とは「過去の失敗が今も有効だ」という主張である。しかしバグが修正された、ライブラリが更新された、運用フローが変わった場合、制約の根拠は消える。誰も削除しなければ制約は積み上がる。失敗を適切に処理するほど制約が増えるという逆説が生じる。

制約を昇格するとき、必ず2つを一緒に記録する。

なぜこの制約が生まれたか（原因となった障害・失敗の日付と概要）
何が変われば不要になるか（review trigger）

constraints:
  - rule: "本番DBへの直接操作禁止"
    reason: "2025-03 本番データ誤削除インシデント"
    review_trigger: "承認フロー付きのDB操作ツール導入時"

この2つがない制約は、時間とともに「なぜあるか不明なルール」になる。checker は reason と review_trigger が欠けている制約を warning 対象に加えるとよい。

まとめ

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

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

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