見出し画像

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統合運用の全体設計


いいなと思ったら応援しよう！