ほとんどの人はCLAUDE.mdをプロンプトファイルのように扱っています。

それが間違いです。

Claude Codeをチャットボット—たまたまファイルアクセスを持つ—ではなく、リポジトリ内に住むシニアエンジニアのように感じさせたい場合、プロジェクトには構造が必要です。Claudeは常に4つのものを必要とします：why（システムが何をするか）、map（どこに何があるか）、rules（何が許可されているか）、workflows（作業がどう行われるか）。

これを機能させる5つのレイヤーを以下に示します。

1. CLAUDE.md — リポジトリメモリ（短く保つ）

これが北極星ファイルです。Claudeがプロジェクトに入ったときに最初に読むもので、後に続くすべてのトーンを設定します。

しかし、ここがほとんどのチームが間違う場所です：CLAUDE.mdを知識のダンプに変えます。アーキテクチャドキュメント、コーディング標準、APIリファレンス、デプロイメント手順—すべて1つのファイルに詰め込みます。

結果？ノイズが多すぎてモデルが重要なコンテキストを見逃し始めます。

CLAUDE.mdを3つのことに焦点を当てて保ってください：

  • 目的—なぜこのシステムは存在するのか？
  • リポジトリマップ—何がどこにあるのか？
  • ルールとコマンド—何が許可され、何が許可されず、作業はどう行われるのか？

それだけです。他のすべては以下のレイヤーのいずれかに属します。

2. Skills — 再利用可能なエキスパートモード

毎セッション指示を書き直すのをやめましょう。

Claude Code skills（.claude/skills/または~/.agents/skills/）を使用すると、一般的なワークフローをClaudeがオンデマンドでロードする再利用可能なモジュールにパッケージできます。エキスパートモードとして考えてください：

  • コードレビューチェックリスト
  • リファクタープレイブック
  • リリース手順
  • デバッグフロー

結果はセッションとチームメイト間の一貫性です。skillsがうまく構造化されていると、Claudeはコードを生成するだけでなく—チームの実際のプロセスに従います。

OpenClawや同様のエージェントフレームワークを使用している場合、skillsはさらに強力になります。スクリプト、参照ドキュメント、アセットを任意のエージェントが拾えるポータブルなパッケージにバンドルできます。

skill作成ツールがどう進化しているかの詳細は、Anthropicのskill creatorとGoogleのWorkspace CLIに関する最近の投稿をご覧ください。

3. Hooks — 忘れないガードレール

モデルは忘れます。hooksは忘れません。

Claude Code hooksは、Claudeが特定の操作を実行する前または後に自動的に発火する決定的なアクションです。必ず毎回起こるべきことのために使用します：

  • ファイル編集後にフォーマッターを実行
  • コアモジュールが変更された時にテストを実行
  • 安全でないディレクトリ（auth、billing、migrations）をブロック

この区別は重要です：プロンプトは提案です。hooksは保証です。プロンプトでClaudeに「src/auth/を編集した後は常にテストを実行」と伝えると、3回目の編集までには忘れるかもしれません。フックとして接続すると、それは自動です。

4. Docs — プログレッシブコンテキスト

Claudeが必要とする可能性のあるすべてをプロンプトに詰め込まないでください。代わりに、真実がどこにあるかのマップをClaudeに与えます：

  • アーキテクチャ概観—システム設計、データフロー、インフラストラクチャ
  • ADRs（Architecture Decision Records）—なぜその選択をしたのか
  • 運用ランブック—どうデプロイ、デバッグ、リカバリするか

Claudeはオンデマンドでファイルを読むのが得意です。前もってすべての詳細を必要としません—どこを見ればよいかを知る必要があります。うまく編成されたdocs/ディレクトリは、Claudeが関連するときに正確にコンテキストを引き出せることを意味します。

5. リスクの高いモジュール向けのローカルCLAUDE.md

これがほとんどのチームが完全に見逃すレイヤーです。

コードベースの鋭いエッジの近くに小さく焦点を絞ったCLAUDE.mdファイルを配置します：

src/auth/CLAUDE.md
src/persistence/CLAUDE.md
infra/CLAUDE.md

これらのファイルにはモジュール固有の落とし穴、制約、警告が含まれます。Claudeがsrc/auth/で作業する時、自動的に認証固有のガイダンス—トークンローテーションの特異性、セッションハンドリングのエッジケース、「この関数を変更する時は必ずマイグレーションを更新」の警告—を見ます。

これがルートCLAUDE.mdを膨らませることなく外科的精度を得る方法です。

プロンプティングより構造

プロンプティングは一時的です。構造は永続的です。

リポジトリがこのように編成されていると、Claudeはチャットボットのように振る舞うのをやめ、プロジェクトネイティブなエンジニアとして行動し始めます。コンテキストを知り、プロセスに従い、ガードレールを尊重し、正しいドキュメントを見つけます—プロジェクト自体がどう作業するかを教えるからです。

AIコーディングCLIの景観は急速に動いています。Claude Code、Codex CLI、Gemini CLI—すべてがエージェント機能を出荷しています。しかし真の価値を得るチームは最高のプロンプトを持つチームではありません。最もよく構造化されたリポジトリを持つチームです。

Kevin Kaminskiは17回 Microsoft MVP であり、Big Hat GroupのPrincipalです。エンタープライズチームのAIエージェント、Windows 365、モダン管理ソリューションのデプロイを支援しています。AIコーディングワークフローの構造化のサポートについては、ご連絡ください。