最終更新 11月8日 18:55

アプリ開発|CLAUDE.md(指示ファイル)に残すべき記述と削るべき記述

アプリ開発で、AIに同じ訂正を何度も書いている方向けです。

本記事では、ターミナルで動く Claude Code(CLI)のプロジェクト用指示ファイル(CLAUDE.md)に、消すと誤りが増える行だけを短く残す書き方を整理します。Web版Claudeのプロジェクト設定とは異なります。

次は、1ファイル200行未満を目安に、残す例と削る例から始めます。

長い丸投げと短い残し方。避ける進め方はスタック一覧と抽象スローガンを全部積むこと、長いほど従いにくくなるのに削らないこと。正しい進め方は消すと誤りが増える行だけ短く残し、1ファイル200行未満を目安にする。
長い丸投げと短い残し方。避ける進め方はスタック一覧と抽象スローガンを全部積むこと、長いほど従いにくくなるのに削らないこと。正しい進め方は消すと誤りが増える行だけ短く残し、1ファイル200行未満を目安にする。
目次

長い丸投げと短い残し方

避けるべき運用は、技術スタックの一覧、全ファイルの説明、抽象的な「きれいなコードを書け」といった精神論を1枚のファイルに詰め込むことです。正しい運用は、「削除するとAIの誤りが増える行」だけを短く残すことです。公式の目安は1ファイル200行未満であり、文章が長くなるほどAIは指示に従いにくくなります。

各記述について「これを消したらAIの誤りが増えるか?」を問い、増えないのであれば削ってください。また、機械的に検証できる文だけを残します。「適切に整形して」ではなく「インデントはスペース2」、「テストして」ではなく「保存前に npm test を実行」と具体的に記述します。

残す例と削る例。残すのは推測できない検査コマンド名と、この案件だけの構成判断。削るのはコードを読めば分かることと、「きれいなコードを書け」という抽象文。
残す例と削る例。残すのは推測できない検査コマンド名と、この案件だけの構成判断。削るのはコードを読めば分かることと、「きれいなコードを書け」という抽象文。

残す例と削る例

残すべき記述は、コードから推測できないビルド・テストコマンド、プロジェクト独自のアーキテクチャ方針、ブランチ作成やプルリクエスト(PR)の作法、環境変数の扱い方です。 削るべき記述は、ソースコードを読めば分かること、言語やライブラリの標準的な書き方、変わりやすい一時的な詳細、ファイル単位の補足、抽象的な品質スローガンです。

・残す:ファイル保存前に実行させるLint・テストコマンド名 ・残す:フロントエンドとバックエンドで規約が異なる場合の判断基準 ・削る:ライブラリの一般的な使い方や文法の再説明 ・削る:今週だけ有効な一時的な作業メモの全文

提示するプロンプト例:「この CLAUDE.md を200行未満に削減してください。削除してもAIの誤りが増えない行を削り、残した理由を1行で添えてください。」 何度も同じ実装ミスが発生する項目だけを重点的に記載します。手順が長くなる場合や特定のフォルダでのみ必要なルールは、サブフォルダ側の設定や個別の実行手順書へ切り出します。

指示ファイルに残す項目。1 言語・禁止:返答言語と使ってよい手段・禁止操作。2 コマンド:ビルド・テスト・整形のうち推測できないもの。3 構成:この案件だけの構成判断と入口ファイル。4 作法:枝分かれ・変更提案・レビュー前の作法。
指示ファイルに残す項目。1 言語・禁止:返答言語と使ってよい手段・禁止操作。2 コマンド:ビルド・テスト・整形のうち推測できないもの。3 構成:この案件だけの構成判断と入口ファイル。4 作法:枝分かれ・変更提案・レビュー前の作法。

指示ファイルに残す項目

    1. 返答言語の指定、使用許可ツール・禁止操作

    2. 推測不可能なビルド、テスト、フォーマット用の実行コマンド

    3. 案件固有のディレクトリ構成・エントリーポイントの判断基準

    4. ブランチ命名規則、プルリクエスト(PR)、コードレビューの作法

    5. 秘密情報(APIキー等)や本番環境操作への注意制限

    ファイルの配置場所もあらかじめ定義します。全案件共通の個人ルールならホーム(ユーザー)ディレクトリ配下、チーム共有ならリポジトリ直下、自分だけの案件用ならローカル専用ファイルへ配置します。上位階層から順に読み込まれ、より深い階層の設定が優先(上書き)されます。/init コマンドでたたき台を作成でき、既存ファイルがある場合は上書きせず改善案を提示してくれます。読み込み状態の確認は /context コマンドで行います。

コードで分かる行と必ず書く行。書かなくてよいのはコードで分かる関数の役割や一般的な作法。必ず書くのは推測できない運用(検査名・禁止・提案の作法)。
コードで分かる行と必ず書く行。書かなくてよいのはコードで分かる関数の役割や一般的な作法。必ず書くのは推測できない運用(検査名・禁止・提案の作法)。

コードで分かる行と必ず書く行

ソースコードを読めば自明な内容は、指示ファイルに書く必要がありません。関数の役割や標準的な言語仕様は、AIがコードを解析すれば理解できます。必ず書くべきなのは、リポジトリを閲覧しても推測できない運用ルールです。実行すべき検証コマンド名、本番環境での禁止操作、チーム独自のPR作成フローなどが該当します。

パス指定付きのルール(例:.claude/rules/ 等)を配置すると、該当フォルダ内のファイルを編集する際のみルールが読み込まれます。フロントとバックエンドで規約が異なる大規模リポジトリでは、すべてのルールをルートの1枚に詰め込まず、各フォルダ配下へ分散させます。また、外部ファイルは @パス で取り込み(インポート)が可能です。作業フォルダ外を指す参照の読み込み時には初回承認が求められます。これは他人が仕込んだ外部参照を安全確認なしに読み込まないためのセキュリティ設計です。

指示ファイルの更新習慣。1 移す:同じ訂正が二度出たら三行に要約して移す。2 削る:古い行を消し矛盾する規則を残さない。3 強調:強調語は本当に守らせたい一行だけ。4 確認:/context で載っているかを見てから共有する。
指示ファイルの更新習慣。1 移す:同じ訂正が二度出たら三行に要約して移す。2 削る:古い行を消し矛盾する規則を残さない。3 強調:強調語は本当に守らせたい一行だけ。4 確認:/context で載っているかを見てから共有する。

指示ファイルの更新習慣

  • ・同じ訂正をAIに2度行ったら、3行程度に要約して CLAUDE.md へ追記する ・古くなったルールは定期的に削除し、矛盾する指示を残さない ・「MUST」などの強調語は、本当に厳守させたい1行だけに絞って使う ・設定が反映されているかは /context で確認し、効いていない場合は診断コマンドを実行する ・レビュー・検証済みの CLAUDE.md はチームのリポジトリで共有して育てる

    強調語を多用しすぎると重要な指示が埋もれてしまいます。矛盾するルールが複数存在すると、AIの動作が不安定になります。メンテナ向けの補足事項はコンテキストを消費しない注釈形式で残すことで、毎回のトークン消費を抑えられます。

 

置き場の決め方

場所 向く内容
個人の全案件 ホーム(ユーザー)フォルダ配下の指示ファイル 自分だけの好み
チーム共有 リポジトリ直下の指示ファイル 構成、コマンド、規約
自分だけこの案件 手元専用の指示ファイル 手元のパスや試験データ

取り込みの相対パスは、書いたファイルからの解決です。ホームフォルダなど作業フォルダ外を指す取り込みは、初回に承認が出ます。定期的に古い行を消し、検証できない抽象文は残さないでください。

権限設定(Permissions)との分担

CLAUDE.md はあくまでAIに対する「ガイドライン(お願い)」です。無承認で実行させたいコマンドや、絶対に実行させたくない危険コマンドは、設定ファイル(settings)の権限設定(Permissions)で制御します。すべてのダイアログを自動承認(スキップ)にするよりも、許可・拒否のリストを明示する方がチーム運用に適しています。絶対に阻止したい操作は、権限の拒否設定(Deny)やフック機能(hooks)へ移してください。

自動メモ(Auto-memory)と指示ファイルの違いも重要です。自動メモはAIが会話の訂正から自動生成する一時的な記録です。指示ファイルはチームが意図して明記する恒久的なルールです。毎回守らせたい重要ルールは必ず CLAUDE.md に明記してください。禁止事項を指示ファイルだけに頼ると、漏れが発生しやすくなります。

現場での進め方

  1. 毎回書いている訂正を集める 過去1週間分の会話履歴から、「また同じ指示を出した」と感じる内容を3つだけ抜き出します。3つを超える場合は整理が足りていません。

  2. 検証できる文に直す 「きれいに」などの抽象語を消し、具体的なコマンド名や禁止操作に置き換えます。短く検証可能な表現であれば言語(日本語・英語)は問いません。

  3. 置き場を選ぶ チーム共通ルールならリポジトリ直下、個人の好みならローカル専用ファイルに配置します。個人用の秘密パスなどは共有ファイルに入れないよう注意します。

  4. 読み込みを確認する /context コマンドを実行し、ルールが正常にロードされているか確認します。反映されていない場合は診断コマンドで状態を確認します。

  5. 週次で削る ルールを追加した時間と同じだけ、古くなったルールを削る時間を設けます。追記するだけの運用では、AIが無視する肥大化した指示ファイルになってしまいます。

よくあるつまずき

・技術スタック一覧を全文記載し、本当に必要なテストコマンドが埋もれる ・「コードを綺麗に」とだけ書いて満足し、実行すべきLint・テストコマンドが指定されていない ・危険操作の禁止を CLAUDE.md にだけ書き、権限設定(Permissions)側で拒否指定していない ・大規模リポジトリの全規約をルートの CLAUDE.md 1枚に詰め込んで肥大化させる ・他人が指定した外部参照(@パス)を内容確認せずにそのまま読み込ませる

FAQ

Q. 日本語で記述しても問題ありませんか?

A. 形式は固定されていないため、短く明確に検証できる文章であれば日本語で問題ありません。長くて矛盾のある英語ルールよりも、簡潔で正確な日本語ルールの方がAIは正確に従います。

Q. 大規模なリポジトリでも1つのファイルにまとめますか?

A. まとめる必要はありません。各サブフォルダ配下に配置されたルールは、そのフォルダ内のファイルを編集する際に自動で読み込まれます。

Q. 自動メモ(Auto-memory)との違いは何ですか?

A. 自動メモは対話の修正からAIが自動学習して残すメモです。指示ファイル(CLAUDE.md)は人間が明示的に定義するルールです。チームで確実に共有・適用したいルールは CLAUDE.md に書く必要があります。

Q. /init コマンドを実行すると既存のファイルは上書きされますか?

A. 上書きされません。既存ファイルが存在する場合は内容を解析し、改善案を提示する動作になります。提案をたたき台とし、不必要な行は削除して利用してください。

Q. 200行を超えてしまった場合はどうすればいいですか?

A. 削除しても誤りが増えない記述を削り、特定のフォルダでのみ使うルールはサブフォルダ側の設定や個別の実行手順書へ切り出します。行数削減そのものが目的ではなく、「AIが誤りなく従える簡潔さ」を維持することが目的です。

まとめ

アプリ開発で真に効果を発揮する CLAUDE.md は、長い文章ではなく「消すとAIの誤りが増える最小限の短い記述」です。Claude Code (CLI) を運用する際は、ガイドライン(お願い)と権限・フック機能(物理的な強制)を明確に分離しましょう。

迷ったらまずは記述を削り、自動テストやLintで判定できる具体的な指示だけを残す運用を意識してみてください。

参考文献

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

この記事を書いた人

コメント

コメントする

目次