プロジェクトのコンテキスト整理
はじめに
AIツールの利用において、コンテキストはとても重要なものです。
ハーネスエンジニアリングという言葉が登場してしばらく経ちましたが、その中でも必要なときに必要なコンテキストを渡す設計の重要性はとても高いと感じています。
今回は、必要なときに必要なコンテキストを渡し、より良い出力を得るために私が実践していることをまとめます できるだけ複雑な仕組みを利用せず、Claude Codeに用意されている仕組みを最大限使いこなすことが重要だと考えています
前提条件
Claude Codeを利用します
この記事では、AIツールとしてClaude Code(v2.1.140)を利用することを前提とします Claude Codeは更新頻度が高く、本記事の内容は執筆時点(2026年5月)の挙動に基づきます
外部ツールを多用しない
外部ツールを利用した仕組みは今回のスコープから外します AIツールは黎明期であり、エコシステムも成熟しているとは言えません 日々試行錯誤が行われている環境下では、その中心となるAIツールの公式機能を十分に使いこなすことに集中したほうが良いと考えています
もちろん公式機能であっても仕様変更や非推奨化のリスクは避けられませんが、外部ツールに比べると、後のマイグレーションコスト、公式機能への吸収による陳腐化、メンテナンス停止のリスクは相対的に低いと考えています プロジェクトを育てるためにより良い生成結果を得ることにフォーカスするため、今回はClaude Codeの公式機能のみでコンテキストを整理します 具体的には以下を中心に利用します
- CLAUDE.md
- Rules
- Skills
コンテキスト整理の基本方針
基本方針として、以下の3点の達成を目指してコンテキストを整理しています
- コードの調査を効率的に行えるようにする
- コードからは読み取れない暗黙知をコンテキストとして与える
- 行動の再現性を高める
コードの調査を効率的に行えるようにする
なぜコードの調査を効率的にするのか
Claude Codeに何らかの指示をしたとき、多くの場合には最初に現状のコードの調査を始めることが多いのではないでしょうか コード調査の効率や精度の向上はその後のプラン作成や修正に大きく影響を与えます 例えばコード調査の際、該当のファイルがどこにあるかピンポイントで見つけられないかもしれません 該当ファイルを見つけるために全文検索をしたり、それっぽいディレクトリを掘り進めながらファイルを探したりしていると、本来不要なコンテキストがコンテキストウィンドウにたまります 不要な情報をコンテキストウィンドウに残しておくとその後のプランや実装の精度を下げる原因になります
どうやってコードの調査を効率化するのか
CLAUDE.mdに必要なコンテキストを乗せることで問題を解決します CLAUDE.mdは、セッションの最初にユーザーメッセージとして読み込まれます そのため、セッションの序盤には大きな影響力を持ちますが、以後効果が薄れていきます 最初に行うことの多い既存コードの調査は、CLAUDE.mdの特性と相性が良いです 例えば、各モジュールの責務や依存関係をコンテキストとして与えれば、検索対象を大きく絞り込める可能性があり、無駄なディレクトリの探索を減らせます
コードからは読み取れない暗黙知をコンテキストとして与える
なぜ暗黙知を与えるのか
ソースコードから読み取れない暗黙知とは、例えば次のようなものです
現在はAというOSSを使っているが、メンテナンス頻度が落ちているのでBというOSSへ移行している。 現在のソースコードでは、Aを使って書かれたコードが大部分を占めている Aを使ったコードを修正する場合にはBへの移行を検討する必要がある。新規の実装では必ずBを使わなければならない
この内容を、Claudeがソースコードから読み取ることは困難でしょう。 Aを使って書かれたコードを参考にして、新しいソースコードを生成する可能性は非常に高いです
Claude Codeはユーザーメッセージを受けて、コンテキストとソースコードを見て行動を決定します ユーザーメッセージは毎回手打ちする必要があり、メンバーによってブレやすく、毎回暗黙知を手打ちするのは非常に面倒です 一方、コンテキストとソースコードは、ユーザーメッセージに対して変化が少ないため、コンテキストに入れるのが最適だと考えます
どうやって暗黙知を与えるのか
コード全体の探索に大きな影響を与える内容であればCLAUDE.mdに記載します また、特定のファイル群でのみ意味を持つコンテキストであれば、Rulesに記載します
どちらか迷う場合には、Rulesに記載するほうが良いでしょう 特定のディレクトリ内のファイルをロードしたときに読み込まれるRulesは、必要なタイミングでコンテキストをロードできることが強みです CLAUDE.mdと違い、必要なタイミングになった時点でロードすることでセッションが長くなってきた場合でも新鮮な情報としてコンテキストをロードできます
行動の再現性を高める
なぜ行動の再現性を上げるのか
行動の再現性を上げることは、Claudeの振る舞いを予測可能なものとするために非常に重要です 例えば、AIにレビューを依頼したとき、聞くたびに真逆の指摘がされる場合、そのレビューフローを業務に組み込むことは難しいでしょう
曖昧な指示でも毎回意図した通りの挙動をしてくれると、ユーザーメッセージが柔軟であるもののメンバーによってブレやすいという弱点を吸収してくれます
どうやって行動の再現性を上げるのか
Skillsの利用が最適です 自然言語による曖昧な条件をフックにして、定型処理を任せることができます
CLAUDE.mdやRulesがコンテキストとして情報を渡すのに対し、Skillsは手順そのものを渡せる点が再現性に効きます
セッションの最初に常駐するCLAUDE.md、ファイル参照時にロードされるRulesと違い、Skillsは特定の条件で発火し定型処理を実行するため、同じ指示に対して同じ手順を踏ませやすくなります
Skillsはリポジトリに入れてメンバーに共有することで、チーム内での利用を強制できます チーム全員が全く同じクオリティで同じアクションをする必要がある場合に非常に役立ちます
チーム内で強制はしないものの、希望すれば利用できるという状態にしたい場合には、pluginによる配布が最適です メンバーは必要であればpluginをインストールし、いつでも利用できます
両方とも、Skillsの改善がチーム全体に影響を与えることは共通しています スキルの改善効果がチーム全体に波及するので、リポジトリに入れるかplugin化するか(もしくはその他の方法でも)で共有することを強くおすすめします
コンテキスト整理で避けていること
逆に、コンテキストの整理で避けていることは、以下の2点です
- 調査コストが低い情報をコンテキストに入れる
- 更新頻度が高い情報をコンテキストに入れる
Claudeは渡されたコンテキストを信用して行動をしますが、そのコンテキストが実態と乖離している事がわかると、意図しない行動を始めることが多いです 上記2点の情報は、コンテキストと実態との乖離を生みやすいため、あえてコンテキストには入れないようにしています
調査コストが低い情報をコンテキストに入れる
調査コストの低い情報は、都度最新の情報を調査するようにしています 例えば、ディレクトリツリーはtreeコマンドで簡単に素早く調査可能です このような情報をコンテキストとして残してしまうと、最新の情報との齟齬が出やすいです
変更頻度が高い情報をコンテキストに入れる
更新頻度が高い情報も、同様に都度調査させるようにしています 例えば、特定の画面の仕様は、コンテキストとして固定すると、後の修正によって実態との齟齬が出やすいです
また、更新頻度が多いにも関わらず調査コストが重い場合には、事前に別セッションで調査をさせるなどの工夫をしています
コンテキスト整理の継続
更新頻度の高い情報をコンテキストに入れることを避けているとはいえ、継続的な整備は必須です モデルの変化によって明示せずともコンテキストを把握できるようになったり、新たな意思決定によって誤ったコンテキストを保持してしまうことも多いです
Claudeが意図に反する行動を取った場合には、なぜその判断に至ったのかを調査し、コンテキストの曖昧性を排除したり、追加、削除したりする必要が出てきます
現在は、/btwコマンドを使って判断の原因を確認してから、コンテキストを調整するようにしています
この部分はhooksやskillsを使った自動化を試しているものの、しっくり来るものが作れず、現在試行錯誤中です
まとめ
私のコンテキスト整理では、以下のような方針を取っています
- CLAUDE.md: 初動のファイル探索を効率化すること、もしくはコード探索だけでは知り得ない情報のみを記載
- Rules: 特定のパス内のファイルにのみ必要なコンテキストのみを記載
- Skills: 行動の再現性が必要な場合に記載
特にCLAUDE.mdとRulesの整備を行ってからは、AIがコード探索に戸惑うことが減ったように思います
また、これらのコンテキストは古くならないよう定期的に棚卸しすることが重要です
棚卸しの具体的な手段は前述の通り/btwコマンドでの判断理由の確認が中心で、自動化はまだ模索中です。良い方法が見つかった際には別記事で共有します