AIエージェントの指示書「CLAUDE.md」を徹底棚卸し：知識の蓄積と運用基準の再構築
本記事は、AIエージェントの動作指示書（CLAUDE.md）を運用した経験に基づき、その構造と記述基準を根本的に見直した記録である。筆者は、3ヶ月間の運用で56行に膨れ上がった指示書を棚卸しし、単なる「削除」ではなく「構造化」と「検証」を通じて改善を試みた。指示書の内容は、以下の3つの層に分類されるという新しい基準が提案された。第一に「Rules」（どう振る舞うか）は策定者の意図に基づくルール、第二に「Navigation」（どこへ行くか）は具体的な情報への道標、第三に「Capability」（そこで何ができるか）は情報ではなく「操作」のリストである。この分類基準に基づき、24項目を一つずつ判定した結果、単に「削除」できる項目は少なく、むしろ「選好」と「事実」の区別や、複数の層が混在する項目（例：Git運用）の分離が重要であることが判明した。特に大きな発見は、単なる「道標」として外部ログを参照する際、その一次情報がすでに古い、あるいは現在の運用と矛盾している（例：認証トークンの保存方式）という点であった。この矛盾を解消するため、筆者はログの改訂、記述の移設、そして指示書側を道標として圧縮するという具体的な修正を行った。最終的に、指示書を短くすることよりも、構造を明確にすること（Capability層の新設など）が重要であると結論づけ、AIエージェントの指示書作成における「基準」から「置き場所による担保」へとアプローチを転換した。
背景
AIエージェントの指示書（プロンプトや設定ファイル）は、開発が進むにつれて、障害対応の経緯や試行錯誤の結果が「知識の地層」のように蓄積されがちです。この記事は、その膨大な情報量を単に削減するのではなく、情報の種類（ルール、参照先、能力）に基づいて構造的に整理し、運用可能な状態に戻すという、高度なドキュメンテーション技術の課題解決プロセスを描いています。
重要用語解説
- MOC: Map of Contents（コンテンツの地図）の略。特定のトピックに関する関連情報や知識を構造的に整理し、AIが効率的に辿れるように設計された知識マップのこと。
- 道標化: 具体的な情報を指示書本体に記述する代わりに、「この情報はこのファイルを参照せよ」という形で、参照先へのリンクや指示（道標）のみを残す手法。指示書を簡潔に保つ目的で用いられる。
- Capability層: AIエージェントが「情報」として知るだけでなく、「実行できる操作」や「手段」として整理した能力のリスト。単なる知識の羅列ではなく、具体的なアクションの分類を目的とする。
今後の影響
本記事で示された「3層構造」と「一次情報検証の徹底」は、複雑なAIエージェントの運用ドキュメント作成における新たな標準的なワークフローとなり得ます。特に、単なる知識の蓄積ではなく、どの情報が「ルール」で、どの情報が「操作」であるかを明確に分けることで、エージェントの誤動作リスクを大幅に低減できると予想されます。今後のAIシステム設計の指針となるでしょう。