AIエージェント向けの設定ファイルには、2つの設計思想があります。静的なベストプラクティス集として書くか、動的に蓄積される経験則ライブラリとして運用するか。
この調査では、後者を採用している3つのOSSプロジェクトを比較し、長期運用を前提とした設計思想を抽出しました。
本記事はOSS横断調査シリーズの深掘り記事です。全体像は「AGENTS.md / CLAUDE.md 実装事例 横断調査」をご覧ください。
この調査の概要
| 項目 | 内容 |
|---|---|
| 調査日 | 2026年5月4日 |
| 対象 | 失敗ログを動的に蓄積している3プロジェクト |
| 着目点 | 「いつ書くか」のポリシー／セルフインプルーブメントループ／tribal knowledgeの蓄積設計 |
結論：「いつ書くか」を決めないと肥大化する
動的蓄積の最大の利点は、ドキュメントが実際に発生した事象に裏打ちされていることです。エージェントが「過去に同じ罠に落ちた事例」を参照できるため、再発防止の精度が高くなります。
しかし同時に、書き手側に「いつ書くか」の判断基準が要求されます。ここを決めていないと、ただ膨れ上がるだけのファイルになります。
| 観点 | 静的ベストプラクティス | 動的経験則ライブラリ |
|---|---|---|
| 記述タイミング | 設計時に一括記述 | 失敗・訂正のたびに追記 |
| 主たる目的 | 「あるべき姿」の規範化 | 「実際に起きたこと」の記録 |
| 肥大化リスク | 高（網羅的に書きがち） | 低（更新基準で制御） |
| 陳腐化リスク | 高（コードと乖離） | 低（実体験に紐づく） |
事例①：ユーザー訂正を恒久知識に変換するループ
あるプロジェクトでは、エージェントの行動規範として次のループが定義されています。
"After user corrections, document patterns in
.cursor/lessons.md. Incrementally refine rules to prevent recurring mistakes."
つまり「ユーザーから訂正を受けたら、そのパターンを記録し、ルールを継続的に改善する」という自己改善ループを、公式ワークフローとして組み込んでいます。
実際に蓄積されている内容
実障害が時系列で記録されています。代表例は次のようなものです。
- フレームワークのアップグレードで
@Overrideがサイレント失敗——バージョン違いによりインターフェース変更が無告知で発生し、@Overrideが消えてもコンパイルが通る - 特定のスクリーンリーダーで挙動が崩れるアクセシビリティ問題
- 並列テストの共有setupパターン——複数テスト間でのリソース競合
これらは公式ドキュメントには載りませんが、実際にエージェントが踏んだ地雷の記録として、後続のセッションに渡されます。
設計上の要点
- ユーザー訂正をエージェント自身が恒久知識に変換する経路を公式化している——通常はメンテナが手動で書くtribal knowledgeを、AIが記録する
- ファイル名が「lessons」（教訓集）であってベストプラクティス集ではないのは意図的。失敗から学んだ事項に限定することで、エントロピーの増加を防いでいる
- 別ファイルには「複雑な問題にはサブエージェントを活用して研究・探索・並列分析を委譲」というエージェント分担戦略も明示
事例②：「いつ書くか」をルール化する
別のプロジェクトは、入口ファイルからドメイン別ファイル（general / network / cli 等）を参照する分散構造をとっています。
特徴的なのは、「このファイルをいつ更新するか」の基準そのものを明示している点です。
- 手動介入が必要だった時
- 複数試行が必要だった時
- gotcha（落とし穴）に当たった時
- 経験則として「次回も役立つ」と感じた時
これは「ドキュメントを書くタイミング」をエージェント自身に判断させるためのメタルールです。
実際に蓄積されている内容
- 3箇所同時更新のゴッチャ——1つの定義変更には3ファイルの同期更新が必要。さもないとAPI側でサイレントリセットが発生する
- キャッシュタイミングの例外ケース——通常のフローから外れる条件
- 変換マッピングのような「動かしてみないとわからない」性質の知識
設計上の要点
- 「いつ書くか」の基準をルール化することで、肥大化を抑制しつつ価値の高い知識だけが残る
- 「動かしたら詰まった事項」だけを記録することで、ファイルが「最新の地雷マップ」として機能する
- ドメイン分割によりコンテキスト効率が高い——エージェントが関連ファイルだけを読めばよい
事例③：独立ファイルを切らない軽量な方式
3つ目は、設定ファイル内に「Operational Insights」セクションとして運用知見を蓄積する方式です。
注目すべきはセクション名です。
「Best Practices」ではなく「Operational Insights（運用上の洞察）」になっています。これは「あるべき姿」ではなく「実際に起きたこと」を記録する意図の表れです。
独立ファイルを切らず同居させる軽量な実装で、リポジトリ規模に応じた選択肢として有効です。
共通する4つの設計パターン
パターンA：ベストプラクティスと経験則を別ファイルに分離する
混在させると更新責任が曖昧になります。静的指針と動的蓄積を完全に分けるのが明快です。
パターンB：「いつ書くか」を明文化する
追記の判断基準そのものをドキュメント化します。これにより肥大化と陳腐化を同時に抑制できます。
パターンC：失敗の主体を「エージェント」と認識する
従来の運用手順書は人間のオペレーター向けでした。しかしAI設定ファイルではエージェントが踏んだ地雷を記録します。
このシフトにより、エージェント特有のミス（訓練データに無いAPI変更へのサイレント失敗など）が記録対象になります。
パターンD：エージェント自身に記録を委ねる
エージェントの行動ループに記録を組み込みます。これによりメンテナの手動更新負荷を下げられます。
導入すべきかの判断フレーム
| 条件 | 動的ライブラリの有効性 |
|---|---|
| エージェントセッションが繰り返し走る | 高 |
| コードベースが古く、tribal knowledgeが多い | 高 |
| 公式ドキュメントが追いつかないペースで開発される | 高 |
| エージェントセッションが1回限り | 低 |
| 規範的ガイドだけで十分な小規模プロジェクト | 低 |
繰り返し使うかどうかが分岐点です。1回限りの作業では、蓄積のコストが回収できません。
よくある質問
ベストプラクティス集を書くのではだめですか？
併存させる構成が現実的です。ただし混在させると更新責任が曖昧になるため、静的指針と動的な失敗ログはファイルを分けるのが明快です。
ファイルが肥大化しませんか？
「いつ書くか」の基準を明文化することで抑制できます。手動介入が必要だった時、複数試行が必要だった時、落とし穴に当たった時——といったトリガーを定義します。
誰が書くのですか？
エージェント自身に記録させる設計があります。ユーザーから訂正を受けたらパターンを記録する、という行動ループを公式ワークフローに組み込む例が観測されました。
どんなプロジェクトに向いていますか？
エージェントセッションが繰り返し走り、tribal knowledgeが多く、ドキュメントが開発ペースに追いつかないプロジェクトです。1回限りの作業では効果が薄くなります。
まとめ
- 設定ファイルには静的なベストプラクティス集と動的な経験則ライブラリの2つの思想がある
- 動的蓄積の利点は実際に起きた事象に裏打ちされていること。再発防止の精度が高い
- 「いつ書くか」を決めないと肥大化する。トリガーの明文化が鍵
- ファイル名を「lessons」「Operational Insights」にすることで、記録対象を失敗に限定できる
- ベストプラクティスと経験則はファイルを分ける——混在は更新責任を曖昧にする
- 記録対象は「エージェントが踏んだ地雷」。人間向け運用手順書とは主体が違う
- 繰り返し使うかどうかが導入判断の分岐点
AIに渡す情報は、書いた時点で完成するものではありません。運用しながら更新する経路を設計に含めておくと、使うほど精度が上がります。
株式会社AI棒では、こうしたAI活用の検証を日々行い、企業の開発体制へのAI導入を支援しています。ご相談はお問い合わせフォームから、継続的な伴走支援についてはAI参謀をご覧ください。