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 を小さく保ちながら、過去判断の再利用性を落としにくい。

アーキテクチャの履歴を残すフォーマット、ADRのメモ

Posted: 2021-07-30 | Categories: Documentation | Tags: ADR, Documentation

Architectural Decision Records (ADR)

Neco プロジェクトのスキルチェックシートアーキテクチャの意思決定を記録する Lightweight Architecture Decision Records について

インストール

brew install adr-tools

初期化

adr init example-system

作る

adr new "サンプルADR"

/usr/local/bin/adr-new を修正する必要がある

本来だと、newするファイルは英語に限るのかもしれない。ファイル名を修正している処理がある

slug=$(echo -n $title | tr -Ccs [:alnum:] - | tr [:upper:] [:lower:] | gsed -e 's/[^[:alnum:]]*$//' -e 's/^[^[:alnum:]]*//')

タイトルの大文字を小文字に変更している、などなど

このファイルに2点修正を加えている.

sed を gsed を使うようにスクリプトを修正( brew install gnu-sed )
ファイル名で英語限定にしている箇所を修正/ dstfile=$dstdir/$newid-$slug.md ↓ dstfile=$dstdir/$newid-$title.md タイトルをそのままファイル名にする

winds.from.oz 技術メモ

Tag: Documentation