最終更新 11月8日 18:55

現場開発向け|クロードでCLAUDE.mdの公式推奨項目に絞って作る最小構成

現場開発向け|クロードでCLAUDE.mdの初稿を公式項目だけで書く

ターミナルで動作する自律型AIコーディングエージェント「Claude Code (CLI)」を開発現場へ導入した際、多くのチームが最初に直面するのが「プロジェクト用指示ファイル(CLAUDE.md)を作成したにもかかわらず、エージェントが規約を守らず、毎回口頭で同じ注意を繰り返している」という問題です。

その原因の大半は、初稿のファイル内に長大な開発日記やアーキテクチャ解説、あるいは「読みやすく保守性の高いコードを書いてください」といった抽象的なスローガンを大量に詰め込んでしまうことにあります。コンテキストウィンドウに曖昧な長文を並べると、モデルのアテンション(注意の配分)が希釈され、肝心の規約が無視される確率が跳ね上がります。

本稿では、ソフトウェア開発チームのテックリードや現場エンジニアに向けて、公式ドキュメントで定義されている「5つの必須項目」だけに絞り込んだ CLAUDE.md の初稿テンプレートと、曖昧な指示を「検証可能な一行」へ変換する技術、そしてセッション内の /context コマンドで確実に読み込みを担保する実務フローを解説します。

【3秒でわかる結論:CLAUDE.md初稿作成の鉄則】
・公式5項目に限定: 初稿に書くのは「ビルド/テスト」「規約」「配置」「コミット前」「禁止事項」の5要素のみ。
・検証可能な一行にする: 「きれいに書く」は不可。「インデントは2スペース」「ハンドラは src/api/handlers/」のように客観判定できる記述に変換する。
・文脈と強制の分離: CLAUDE.md はプロンプト(文脈)。破壊的操作を確実に防ぐには hooks(PreToolUse)へ逃がす。
・初週の運用ルール: 毎日ファイルを太らせない。口頭で「同じ訂正が2度出たときだけ」1行追加する。

【図解】Claude Codeにおける指示の置き場分類。静的文脈(CLAUDE.md)、条件付きルール(rules)、手順(Skills)、強制遮断(hooks)の多層防御アーキテクチャ
目次

初稿作成における典型的な誤りと正しいアプローチ

現場で最も頻出する失敗パターンは、既存の社内WikiやMarkdown形式の開発マニュアルをそのままコピー&ペーストして CLAUDE.md を作ってしまうことです。

公式ドキュメントでも警告されている通り、長大すぎる指示ファイルはコンテキストを無駄に圧迫し、エージェントの指示追従性(従順度)を低下させます。また、古いマニュアルと新しい規約が混在して矛盾が生じると、エージェントはどちらを優先すべきか判断できず、挙動が完全に不安定になります。

項目 避けるべき初稿(失敗パターン) 正しい初稿(公式準拠の最小構成)
記述量 過去の障害履歴や日記を含む数百行の長文 200行未満(初稿は30〜50行程度)の箇条書き
表現の粒度 「きれいに」「適切に」「安全に」等の抽象表現 実行コマンドや絶対/相対パスを含む具体的な一行
ルールの整合性 過去の規約と最新の規約が混在し矛盾している 矛盾する古い行は即座に削除し、常に最新の1行のみ残す
禁止事項の扱い 「ファイルを削除しないこと」とプロンプトで懇願 「削除前に理由を提示し確認を取ること」+ hooks 連携

初稿の目的は、リポジトリの全ルールを網羅することではありません。「新しく参画した開発者に、口頭で毎回説明している最低限の環境情報」をファイルへ移すことが唯一の合格基準です。

初稿に書くべき「公式推奨の5大項目」と記述テンプレート

Claude Codeの公式ドキュメントが推奨する指示ファイルの構成要素は、以下の5つに集約されます。初稿の段階では、これら以外の見出しを設ける必要はありません。

見出し項目(公式推奨) 書くべき内容 具体的な記述例
1. ビルドとテスト 開発者がターミナルで実際に叩いているコマンド ビルド: npm run build / テスト: npm test
2. コーディング規約 フォーマッタやリンターが担保する客観的な仕様 インデント: 2スペース / TypeScript: strict準拠
3. ディレクトリ配置 新規ファイルを作成・配置すべき物理パス APIハンドラ: src/api/handlers/
4. コミット前確認 作業完了前に必ず手元で通すべき検証手順 PR作成前: npm run lint && npm test を実行
5. やってほしくないこと モデルが独断で行いがちな危険操作への制約 破壊的変更: ファイル削除前に理由を提示し確認を取る

そのまま使えるCLAUDE.md初稿テンプレート

リポジトリルートに CLAUDE.md を新規作成し、以下の構成をベースにプロジェクトの実態に合わせて書き換えてください。

# プロジェクト開発規約 (CLAUDE.md)

## ビルドとテスト
- ビルドコマンド: `npm run build`
- 単体テスト実行: `npm test`
- 単一テストの実行: `npx vitest run path/to/test.ts`

## コーディング規約
- 言語仕様: TypeScript 5.x (strictモード必須)
- スタイル: インデントは半角2スペース、末尾セミコロン必須
- 状態管理: ローカル状態はuseState、広域状態はZustandを使用

## ディレクトリ配置
- APIハンドラ: `src/api/handlers/`
- 再利用コンポーネント: `src/components/common/`
- 型定義ファイル: `src/types/`

## コミット前の検証手順
- コード編集後は必ず `npm run lint` および `npm test` をパスさせること

## やってほしくないこと
- `src/legacy/` 配下のファイルを許可なくリファクタリングしないこと
- ファイルの削除を行う前に、必ず理由を説明しユーザーの明示的な承認を得ること
【図解】曖昧な自然言語指示を「検証可能な一行」へ変換する設計パターン。客観的にテスト・判定できる記述のみを残す

抽象的な指示から「検証可能な一行」へ直す変換の型

CLAUDE.md に記述する文章は、人間が読んでもエージェントが読んでも「満たされたかどうかが二値(Yes/No)で判定できる記述」に変換する必要があります。

  • NG(抽象的):「コードはきれいにフォーマットしてください」

    ➔ OK(検証可能):「インデントは半角2スペースとし、npx prettier --write を適用すること」
  • NG(抽象的):「テストは念入りに実施すること」

    ➔ OK(検証可能):「コミット前に npm run test:coverage を実行し、新規コードの単体テストを同梱すること」
  • NG(抽象的):「適切なディレクトリにコードを配置してください」

    ➔ OK(検証可能):「ビジネスロジックは src/services/、ユーティリティ関数は src/utils/ に配置すること」
  • NG(抽象的):「危険なコマンドは打たないでください」

    ➔ OK(検証可能):「テーブル削除(DROP)を含むマイグレーションの実行前には、必ずコンソール上で停止し確認を求めること」

変換の型が思い浮かばないルールは、初稿には入れないでください。まずは口頭説明のまま残し、開発を進める中で具体的なパスやコマンド名が定まってから追加するのが確実です。

指示・ルール・スキル・フックの役割分担:肥大化を防ぐ多層設計

Claude Codeのアーキテクチャでは、開発ルールを管理するための機能が複数提供されています。これらを混同してすべて CLAUDE.md に書き込むことが、ファイル破綻の最大の原因です。

設定・機能 配置場所 / 適用スコープ 向いている役割
CLAUDE.md リポジトリルート(全セッションで自動ロード) プロジェクト全体の共通文脈(ビルド・主要パス・規約)
.claude/rules/ 特定ディレクトリや言語拡張子ごとの条件付き設定 フロントエンド専用ルール、特定モジュール固有の制限
スキル(Skills) オンデマンドで呼び出される手順・スクリプト 複数段のデプロイ手順、DBマイグレーション実行フロー
hooks(自動実行) 設定ファイル内のイベントリスナー(Pre/PostToolUse) 危険コマンドの強制遮断、編集後の自動Prettier実行
CLAUDE.local.md ローカル環境限定(.gitignoreに指定) 開発者個人のローカルパス、一時的な作業メモ

文脈(Prompt)と強制(Enforcement)の境界線

エンジニアが絶対に理解しておくべき原則は、「CLAUDE.mdは文脈を提供するプロンプトであり、システムの強制機能ではない」ということです。

「本番データベースへの接続を禁止したい」「特定の設定ファイルを絶対に書き換えさせたくない」といったクリティカルな要件を CLAUDE.md に自然言語で記述しても、確率的なすり抜けを100%防ぐことは不可能です。絶対に阻止すべき操作は、ツール実行前にOSレベルでインターセプトする hooks の PreToolUse イベントに委ねてください。

初稿作成から動作検証までの5ステップ

ファイルを作成した直後に、エージェントがその内容を正常に認識しているかを検証する標準手順です。

  1. ファイルの配置: リポジトリ直下に ./CLAUDE.md(または ./.claude/CLAUDE.md)を作成します。個人専用の検証行がある場合は、CLAUDE.local.md を作成して .gitignore に追加します。
  2. 初期草案の作成(任意): ターミナルで claude を起動し、/init コマンドを実行してプロジェクトの初期スキャンを行わせることも可能です。ただし、自動生成された長文はそのまま採用せず、公式5項目に削ぎ落とします。
  3. セッション内コマンドで読み込み検証: セッションを開始したら、まず /context コマンドを実行します。「Memory files」のリストに作成した CLAUDE.md が表示されていることを確認します。
  4. テストリクエストの送信: 「新規ファイルを作成する際の規約と、実行すべきテストコマンドは何ですか?」とエージェントに質問し、CLAUDE.md に記述した内容が正確に回答されるか確認します。
  5. リポジトリへのコミット: 検証が完了した最小の CLAUDE.md をGitにコミットし、チームメンバーと共有します。
【図解】CLAUDE.mdの初週運用サイクル。毎朝の/context確認と、「2回再発時のみ一行追加」のルールで肥大化を完全防止する

初週の更新ルール:同じ訂正が2度出たときだけ1行足す

初稿を配備した後の1週間は、「毎日ルールを追加しない」ことを徹底してください。

作業中に思いついた些細な好みや、1度しか起きなかったミスをその都度 CLAUDE.md に追記していくと、数日でファイルが肥大化し、誰も全貌を把握できない負債と化します。

2回ルール(Two-Strike Rule)の運用手順

  1. エージェントが期待と異なるコードを出力した場合、1回目はその場のチャットプロンプトで修正を指示します。
  2. 別のセッションや別の日でも「全く同じ指摘(例: またインデントが4スペースになった、また指定ディレクトリ以外にファイルを置いた)」が発生した瞬間にのみ、CLAUDE.md への追加を検討します。
  3. 追加する際は、その場の感情的な注意文を貼るのではなく、「検証可能な一行」に整形し、該当する公式見出しの下へ箇条書きで1行だけ追記します。
  4. 追記する前に、既存の行と矛盾していないかを確認します。古いルールが残っている場合は必ず先に削除します。

よくある質問(FAQ)

Q1. 既存の AGENTS.md がある場合、CLAUDE.md に統一すべきですか?

A1. 併用可能ですが、新規プロジェクトなら CLAUDE.md を推奨します。
Claude Codeは既存の AGENTS.md を自動的に認識し、単独または CLAUDE.md と併用して読み込むことが可能です。ただし、チーム内での仕様管理を一本化するため、どちらを正のドキュメントとするかをプロジェクト内で合意しておく必要があります。

Q2. 指示ファイルの行数に「200行の上限」という厳密な制限はありますか?

A2. 技術的な強制上限ではありませんが、公式が強く推奨する実務上の目安です。
200行を超えると、エージェントのコンテキスト圧迫とアテンションの希釈が顕著になります。行数が増えてきた場合は、特定ディレクトリ限定のルールを .claude/rules/ 配下に分割するか、長大な手順を「スキル(Skills)」へ外出ししてください。

Q3. Claude Desktop の「Codeタブ」でも同じ CLAUDE.md が読み込まれますか?

A3. 完全に共有されます。
Claude DesktopのデスクトップGUI環境であっても、CLI版と同じワークスペースフォルダを開いている限り、同一の CLAUDE.md および設定が自動ロードされます。ただし、会話の実行履歴(セッションログ)は環境ごとに独立しています。

Q4. HTMLコメント(<!– –>)でメンテナンス用メモを書いても大丈夫ですか?

A4. 問題ありません。エージェントの文脈からは自動的に除外されます。
公式仕様上、HTMLコメント形式で記述されたブロックはエージェントへ渡されるコンテキストから除外されるため、人間向けの更新履歴や「なぜこのルールを設けたか」という背景メモを安全に残すことができます。

Q5. 「きれいに書いて」以外の文章スタイル(文体)はどう指定すべきですか?

A5. 出力の語尾や解説レベルを一行で指定します。
「解説は不要、コードのみ出力」「コミットメッセージのプレフィックスは conventional commits に従う」など、出力フォーマットを客観的に縛る一行を記述してください。

導入初週(1週間)の定着ロードマップ

開発チームへ CLAUDE.md の文化を定着させるための5日間のステップです。

  • Day 1: 公式5項目テンプレートによる最小初稿の作成

    本稿のテンプレートをベースに、プロジェクトの実態に即したコマンドとパスを記述。30行以内で作成しリポジトリへ配置する。
  • Day 2: セッション内での /context 読み込み確認

    チームメンバー各自のローカル環境で claude を起動し、/context コマンドで「Memory files」に正しく認識されていることを確認する。
  • Day 3: 個人設定(CLAUDE.local.md)の分離

    各個人のローカル端末固有のパスやテスト用トークンがある場合は、CLAUDE.local.md へ切り離し、Git管理対象外にする。
  • Day 4: 実装タスクでの挙動観察と口頭訂正のカウント

    通常の実装業務を開始。エージェントへの口頭指摘が発生しても即座にファイルを編集せず、同じ訂正が発生するか観察する。
  • Day 5: 初週レビューと「2回目再発ルール」の厳格な適用

    週の終わりにチームで集まり、2回以上再発した指摘のみを「検証可能な一行」に整形して CLAUDE.md に追加。矛盾した行の棚卸しを実施する。

まとめ

CLAUDE.md を成功させる鍵は、網羅的なマニュアルを作ることではなく、「公式の5項目に絞り、検証可能な一行だけを並べること」です。

曖昧な指示を排除し、コマンドとパスで語る。特定フォルダのルールは .claude/rules/ へ、複数段の手順はスキルへ、そして破壊的変更の阻止は hooks へ逃がす。この多層設計を意識するだけで、エージェントは驚くほど正確にプロジェクトの文脈を汲み取るようになります。

まずは今日、リポジトリルートに30行のシンプルな CLAUDE.md を作成し、ターミナルで /context を叩くことから始めてください。

参考文献

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

この記事を書いた人

コメント

コメントする

目次