ゼロドリフトのためのフェンスドブロックを使用した自己維持ドキュメントシステム

r/ClaudeAIで、Claude CodeのようなAIコーディングエージェントがセッション間でコンテキストを忘れてしまうマルチプロジェクトワークスペースにおいて、正確なドキュメントを維持するための解決策が共有されました。このシステムは、エージェントが関数名を推測したり、間違ったファイルを編集したり、コンテキストを失ったりしていた、8つのプロジェクト、20のLambda関数、42のAPIキー、12のAPIエンドポイント、19の環境変数に関する問題に対処しています。

フェンスシステム

実装後にClaudeにドキュメントを更新させる代わりに、開発者は740行のbashスクリプトを構築しました。このスクリプトは、ソースファイルから構造化データを直接抽出し、HTMLコメントブロックで囲まれた領域（フェンス）を通じてCLAUDE.mdに注入します。各CLAUDE.mdには、自動生成セクションをマークするフェンスがあります：

## Serverless Functions <!-- auto:lambdas generated="2026-03-26" source="infrastructure/lib/api-stack.ts" -->
| Function | Route | Memory | Timeout |
|----------|-------|--------|---------|
| quote-save | /quotes/save | 256MB | 15s |
| quote-get | /quotes/get | 256MB | 15s |
...20 rows extracted from CDK config...
<!-- /auto:lambdas -->

## Architecture <-- 手書き、スクリプトでは触れられない

仕組み

このスクリプトは：

• 実際のソースファイル（CDK TypeScript、FastAPI Python、package.jsonなど）を解析します
• 構造化データ（関数名、ルート、環境変数、依存関係のバージョン）を抽出します
• フェンス間のすべてを置き換えます
• 生成日を更新して新鮮さを示します
• 検証：すべてのLambda名に対応するハンドラーファイルがあるか、すべての環境変数が.envに存在するかをチェックします

手書きのセクション（アーキテクチャの説明、注意点、ビジネスロジックのコンテキスト）はフェンスの外にあり、決して触れられることはありません。

自動生成される内容

• 引用ツール（20のLambda）：Lambdaインベントリ、CDKスタック、環境変数、テスト数、CDK TypeScriptとpackage.jsonからの依存関係
• 販売ダッシュボード（12のエンドポイント）：APIルート、テーマリスト、FastAPIデコレータ、TypeScript型、requirements.txtからの依存関係
• データ解析（42のユーザー）：ユーザーデータ、Python認証ファイルとrequirements.txtからの依存関係
• 他の5つのプロジェクト：package.json/requirements.txtからの依存関係バージョン

陳腐化警告システム

ドキュメント同期フック（すべてのコード編集後に発火）は、各フェンスの生成日をチェックします。いずれかのセクションが7日以上古い場合：

警告：agent-quoting-tool/CLAUDE.mdの3つの自動生成セクションが陳腐化しています（最も古い：2026-03-19）。
実行：./scripts/generate-inventory.sh quoting

これは非ブロッキングです — 警告は出しますが、作業を止めることはありません。陳腐化チェックは、既存のフックと同じ10分間のスロットルウィンドウに乗り、追加のオーバーヘッドはゼロです。

実装の詳細

このセットアップは、grep/sed/awk/jqを使用した純粋なbashで、依存関係はゼロです。コマンド：

scripts/generate-inventory.sh all # すべてを更新
scripts/generate-inventory.sh quoting # 1つのプロジェクトのみ

スクリプトはまず各CLAUDE.mdをバックアップします（1日1回、プロジェクトごと）。開発者は、bashからASTを解析しないように注意しています — 彼らのTypeScriptパーサーは、制御されたファイルでは機能するが、任意のTypeScriptには脆弱であろう、行ごとのgrep/sedループです。

重要な洞察

フェンスにより、自動生成されたコンテンツと手書きのコンテンツが同じファイル内で共存できます。Claudeはセッション開始時にCLAUDE.md全体を読み、両方を取得します：正確に抽出されたデータと、コードから推測できない人間のコンテキストです。開発者は、最も価値の高い抽出（Lambdaインベントリと、ずれるとバグを引き起こす環境変数テーブル）から始めることを推奨し、陳腐化警告は自動実行よりも価値があると指摘しています。

このシステム全体の構築には約3時間かかりました（設計、実装、テスト、初回実行）。