AIコーディングの限界を突破する「CLAUDE.md」断捨離術

深夜のデバッグ作業中、ふとエージェントの挙動に違和感を覚えたことはないだろうか。まるで新入社員に「あれもダメ、これもダメ」と禁止事項を羅列しすぎて、結局何も動けなくさせてしまったような、あの焦燥感だ。Claude CodeやCodexといったコーディングエージェントを使い込むほど、我々は親切心から『CLAUDE.md』や『AGENTS.md』に情報を詰め込みすぎる傾向がある。最初は数十行だったはずの指示書が、いつの間にか数百行の「何でも帳」へと変貌し、AIのコンテキストウィンドウを無駄に占有している事実に気づくべきだ。

白井暁彦氏が指摘するように、この巨大化した指示書は、もはや開発の助けではなく「トラウマの塊」と化している。過去の失敗、完了したタスク、特定のプロジェクトでしか使わないルールが混在し、AIは常に「古い進捗」というノイズの中で迷子になっている。これは、料理をするたびに家中の取扱説明書をすべてキッチンに持ち込むようなものだ。洗濯機の操作方法まで作業台に積まれていては、肝心の包丁の使い方が埋もれてしまうのは当然の帰結である。AIが賢く動けないのは、モデルの性能不足ではなく、我々が与える「コンテキストの質」が低いからに他ならない。

特に深刻なのは、静的な指示書に「現在地」を書き込んでしまうことだ。「DNS設定は未完了」「次は認証機能を実装する」といった流動的な情報は、数日後には陳腐化する。これを指示書に含めることは、AIに「賞味期限切れの地図」を渡して航海させるようなものだ。我々エンジニアは、AIを単なる「コード生成機」としてではなく、チームの一員として扱う必要がある。進捗はIssueやタスク管理ツールへ、日々の引き継ぎは専用のメモリやhandoffファイルへ。この「情報の分離」こそが、AIコーディングを次のステージへ引き上げるための第一歩である。

では、具体的に何を削り、何を残すべきなのか。その判断基準は「コードやテストから推論可能か」という一点に集約される。命名規則やディレクトリ構成など、コードを見れば自明なルールをわざわざ文章で記述するのは、AIの貴重なトークンを浪費する行為だ。我々が残すべきは、コードの行間には決して現れない「運用上の地雷原」である。例えば、「特定の値の組み合わせで無限リダイレクトが発生する」「マイグレーションを自動実行してはいけない」といった、過去の事故から得た教訓こそが、AIにとっての真の航海図となる。

ここで重要なのが「情報の蒸留」という概念だ。長い議事録や仕様書をそのまま放り込むのではなく、そこから「未来にも効くルール」だけを抽出する。例えば、単なる禁止命令ではなく、「なぜそれをしてはいけないのか」「代わりに何を使うべきか」という代替手段をセットで提示する。これにより、AIは「ブレーキを踏むこと」が目的化するのを防ぎ、より建設的な提案を行えるようになる。また、長い仕様書は別ファイルに分離し、必要なタイミングで参照させる「Progressive Disclosure（段階的開示）」の設計を取り入れるべきだ。人間のチームでも、新人に初日で全社文書を暗記させることはない。必要な時に必要な規程を参照させるのと同様に、AIに対しても「docs/billing.mdを参照せよ」といった適切な誘導を行うことが、コンテキストエンジニアリングの要諦である。

さらに、グローバル設定とプロジェクト固有設定の切り分けも不可欠だ。ホームディレクトリに置かれたグローバルなCLAUDE.mdに、特定のAPI例外処理などを書き込んでいないだろうか。それは無関係なプロジェクトでも毎回読み込まれる「ゴミ」となり得る。グローバル設定には、コミット方針や共通のコーディング規約など、全作業に適用される最小限のルールだけを残し、プロジェクト固有のルールは各リポジトリへ移設する。この棚卸しを行うだけで、AIの推論精度は劇的に向上するはずだ。以下に、整理の指針をまとめた。

コンテキストエンジニアリングの本質は、情報量ではなく「情報の配置」にある。AIに大量の文章を読ませることが賢さにつながるという幻想を捨て、何を常に見せ、何を必要時だけ見せるのかという設計思想を持つこと。これは、単なる指示書の整理術を超えた、AI時代の新しい開発作法である。我々シニアエンジニアが直面しているのは、AIという「極めて優秀だが、文脈を読み違えることもあるアシスタント」を、いかにして自律的な戦力へと育て上げるかという課題だ。

「やらないこと」を明示する価値も再評価すべきだ。一般論として正しい設計であっても、そのプロジェクトの運用上の理由で避けていることは存在する。AIが良かれと思って「改善」しようとするコードが、実はシステム全体を破壊するトリガーになることは珍しくない。だからこそ、「このプロジェクトでは、この手法は採用しない」という境界線を明確に引くことが、AIの暴走を防ぐ唯一のブレーキとなる。これは「仕事のための仕事」を増やすことではなく、AIのインテリジェンスを特定のゴールへ集中させるための戦略的な制約である。

最後に、読者であるエンジニア諸氏に問いたい。あなたのプロジェクトのCLAUDE.mdは、今も「絆創膏だらけの禁止事項リスト」になっていないだろうか。AIを「幼稚園児」のように扱っていないだろうか。もしそうなら、今すぐそのファイルを棚卸しし、AIを「航海図を持つパートナー」として再定義してほしい。明日から取るべき対策は明確だ。まず、現在の指示書から「進捗」と「自明なルール」を削除し、Issueドリブンな運用へ切り替えること。そして、AIが迷ったときに参照すべき「設計の原則」だけを蒸留して残すこと。AIコーディングの真価は、ツールを使いこなす側がいかに「問い」を研ぎ澄ますかにかかっている。あなたは、AIという最強の武器を、ただの「自動化ツール」で終わらせるつもりだろうか、それとも「共にシステムを構築するエンジニア」へと昇華させるだろうか。