メインコンテンツへスキップ
見出し画像

CLAUDE.mdとは何か — AIへの取扱説明書を書く


    おはようございます。
    SE歴15年。小さな印刷会社の社内SE、40歳。"いえのした"です。
    今回はClaude Codeの「agents」について紹介します。

    毎回同じことを説明していないか

    「日本語で回答して」「テストはpytestで書いて」「このプロジェクトはGo製です」——
    Claude Codeに毎回言い直していないだろうか。

    CLAUDE.mdは、この繰り返しをなくす仕組み。

    CLAUDE.mdの基本

    何をするファイルか

    CLAUDE.mdは、Claude Codeがセッション開始時に自動で読み込むMarkdownファイル。
    ここに書いた内容が、すべてのやり取りの「前提知識」になる。

    ゲームのステータス画面を想像してほしい。キャラの能力値・装備・パッシブスキルが表示されている画面。CLAUDE.mdは、Claude Codeの「ステータス画面」に相当します。何が得意で、どういうルールで動くか、何をしてはいけないかを定義する場所です。

    配置場所

    CLAUDE.mdは2つの場所に置ける:

    • プロジェクト: `プロジェクトルート/CLAUDE.md` — そのプロジェクトのみに適用

    • ユーザーグローバル: `~/.claude/CLAUDE.md` — 全プロジェクト共通で適用

    まずはプロジェクトのCLAUDE.mdから始めるのがおすすめです。

    読み込みの仕組み

    セッション開始
      → ~/.claude/CLAUDE.md を読み込む(あれば)
      → プロジェクトルート/CLAUDE.md を読み込む(あれば)
      → 両方の内容が「前提知識」としてセッション全体に適用

    両方ある場合、両方とも読み込まれる。グローバル設定とプロジェクト固有設定を分離できる仕組みです。

    何を書くべきか

    最小限で効果が高い3カテゴリ

    1. 言語とスタイル

    - 日本語で回答する
    - コードのコメントは英語

    2. 技術スタック

    - Backend: Go (Echo framework)
    - Frontend: React + TypeScript
    - Database: PostgreSQL
    - テスト: go test / Jest

    これを書いておくだけで、「どのテストフレームワークを使う?」と聞かれなくなる。地味だけど効果は大きい。

    3. プロジェクト固有のルール

    - mainブランチへの直接コミット禁止
    - 環境変数は.envに定義(.env.exampleをテンプレートとして管理)
    - APIエンドポイントの命名規則: /api/v1/リソース名(複数形)

    プロジェクトで「当たり前」だけどコードからは読み取れないルールを書く。暗黙知をテキストにする作業です。

    何を書くべきでないか

    CLAUDE.mdはcontext windowの一部を消費する。書きすぎると他の作業に使える容量が減ります。

    書かなくてよいもの:

    • コードから読み取れること(ディレクトリ構造、依存関係)

    • 一般的なプログラミングの常識

    • 1回しか使わない一時的な指示

    • READMEに書くべき内容(セットアップ手順等)

    「Claude Codeが自分で読み取れる情報は書かない」が基本方針。

    書き方のコツ

    箇条書きで短く

    # 良い例
    - 日本語で回答する
    - テストはpytest
    - mainへの直接コミット禁止
    
    # 避ける例
    このプロジェクトでは日本語でコミュニケーションを取ることが
    望ましいです。テストフレームワークとしてはpytestを使用して
    おりますので、テストを書く際にはpytestの規約に従って
    ください。また、mainブランチへの...

    Claude Codeは構造化された短い指示を正確に理解する。文章で長く書くより、箇条書きで明確に書いたほうが効きます。

    セクションで整理する

    ## 技術スタック
    - Backend: Go
    - Frontend: React
    
    ## コーディング規約
    - 変数名: camelCase
    - 関数名: camelCase
    
    ## 禁止事項
    - mainへの直接コミット
    - .envファイルのgit管理

    セクション見出しを使うと、Claude Codeが「どのカテゴリの指示か」を正確に判断できる。

    実例: 最小限のCLAUDE.md

    # My Project 設定
    
    ## 基本
    - 日本語で回答する
    - コードのコメントは英語
    
    ## 技術スタック
    - Go 1.22 / Echo v4
    - PostgreSQL 16
    - テスト: go test -v ./...
    
    ## ルール
    - mainブランチへの直接コミット禁止
    - featureブランチで作業してPR経由でマージ
    - テストを書いてからcommit

    20行以下で十分。ここから必要に応じて育てていけばいい。

    ここから先

    指示書を「判断基準書」に育てる

    ここまでの内容は、Claude Codeの公式機能として用意されている基本的な使い方。これだけでも「毎回ゼロから説明」はなくなるし、十分に実用的です。

    ただ、実際にプロジェクトを回し始めると、CLAUDE.mdの役割が「指示を書く場所」から「判断基準を定義する場所」へと変わっていった。

    たとえば、こんなセクションが育っていく:

    • 行動哲学: 「依頼の範囲を超えない」「先送りする前に所要時間を見積もる」「前提を疑う」——こういった判断基準を明文化しておくと、細かい指示を出さなくてもAIが適切な判断を下せるようになる

    • アンチパターン: 過去に起きた判断ミスを「脳内の思考 → 実際の意味」の2列表にまとめて配置。「これを考えたら立ち止まれ」を仕組みで埋め込む

    • 信頼度評価方針: AIの回答に確信度(高/中/低)を付与させ、ユーザーがレビュー対象を絞り込めるようにする

    これらはClaude Codeの標準機能ではなく、自分で設計して書き足したもの。
    公式ドキュメントには載っていない。
    20行から始まったCLAUDE.mdが、運用を重ねることでプロジェクト固有の「判断基準書」に進化していく過程—— 
    具体的にどう書くか、どんな効果があったかは、別の記事で詳しく紹介します。

    まとめ

    CLAUDE.mdは、Claude Codeに「前提知識」を伝えるファイル。
    言語・技術スタック・プロジェクトルールの3カテゴリを箇条書きで短く書く。
    コードから読み取れる情報は書かない。

    最初は20行以下で始めて、使いながら育てる。
    これだけで「毎回ゼロから説明」がなくなります。
    地味だけど、全てのカスタマイズの土台になる一歩です。

    次の記事では、具体的に「最初に書くべき5行」を紹介します。


    Claude Code実践シリーズ

    次に読む:

    • → CLAUDE.mdに最初に書くべき5行

    • → 親CLAUDE.mdとプロジェクトCLAUDE.mdの使い分け

    カスタマイズの全体像:

    • → 20リポジトリを1人で回す — Claude Code統合運用の全体設計


     
     
    社内SE歴15年超。 Claude Codeで20リポジトリを並行運用する環境を構築。 トレンドを片っ端から検証し、現場で生きるものだけ残す主義。 机上の空論ではなく、業務で毎日使っている実践知を発信します。 猫派、2児の父。

    あなたへのおすすめ