はじめに
AIエージェントに「このプロジェクトの流儀」を毎回口頭で伝えていませんか。CLAUDE.md や AGENTS.md のようなルールファイルを置いても、「書いたのに守られない」「長くなって逆に迷走する」という声をよく見ます。
この記事では、ルールファイルを効かせるための書き方を整理します。
想定読者：Claude Code / Codex / Cursor などのエージェントを使い始めた人
前提：ファイル名や読み込み仕様はツールとバージョンで異なるため、必ず公式ドキュメントで確認してください
結論
コードを読めば分かることは書かない。書くのは「読んでも分からないこと」だけ
形容詞ではなく、コマンドと具体例を書く
ルールは先に作り込まず、失敗のたびに1行ずつ足す
絶対に守らせたいことは、文章ではなく仕組み（lint・hooks・CI）で守らせる
書くべきこと
エージェントが自力では推測できない情報に絞ります。
種類 例
コマンド テスト・ビルド・lint の実行方法（npm run test -- --run など）
プロジェクト固有の規約 ディレクトリ構成の意図、命名規則、採用していないライブラリ
禁止事項 .env を読まない、本番DBに接続しない、既存テストを消さない
完了条件 「テストが通り、lint が通ったら完了」
判断に迷うときの動き 不明点は推測せず質問する
書かない方がいいこと
コードから分かること（「このプロジェクトは React です」など）。冗長なだけです。
曖昧な形容詞（「きれいなコードを書く」「慎重に」）。守れたかどうか判定できません。
長い背景説明。長いほど重要な行が埋もれます。
機密情報（APIキー、未公開の仕様）。ルールファイルはリポジトリに入る前提で扱ってください。
テンプレート
プロジェクトルール
コマンド
- テスト:
npm run test -- --run - Lint:
npm run lint - 型チェック:
npm run typecheck
規約
- コンポーネントは
src/components/に置く（1ファイル1コンポーネント） - 新しい依存パッケージは追加しない。必要なら理由を添えて質問する
禁止事項
-
.envおよびsecrets/配下を読まない・出力しない - 既存テストを削除・スキップしない
- 本番環境に接続するコマンドを実行しない
完了条件
- テスト・lint・型チェックがすべて通っている
- 変更点と、確認できなかった点を最後に箇条書きで報告する
迷ったとき
- 仕様が曖昧なら、推測で実装せず質問する
ルールは「失敗」から育てる
最初から完璧なルールを書こうとすると、必ず長くなります。おすすめは次のループです。
まず、エージェントの出力を直します。次に「同じ指摘を来週もするか？」と自問します。するなら、ルールに1行足します。しないなら、足しません。
これを続けると、ファイルが「自分のレビュー観点の記録」になります。
効いていないときの確認ポイント
読み込まれているか：エージェントに「今読んでいるルールを列挙して」と聞くと確認できます。
置き場所は合っているか：ファイルの探索範囲（ルート直下か、サブディレクトリか）はツール依存です。
ルール同士が矛盾していないか：「簡潔に」と「詳細な例を必ず付ける」が同居していないか確認します。
長すぎないか：1画面で読める量を目安に、肥大化したら用途別に分割します。
ツールごとにファイルが分かれていないか：複数のエージェントを併用する場合、内容を一本化する方法（参照・シンボリックリンクなど）は各ツールのドキュメントを確認してください。
文章では守らせきれないもの
ルールファイルの指示は、あくまでお願いです。常に100%守られる保証はありません。したがって、重大なものは仕組みで止めます。
秘密情報の流出 → .gitignore、シークレットスキャン、権限の分離
コード品質 → lint・型チェック・CI で機械的に落とす
危険なコマンド → ツール側の許可設定や hooks
「文章で頼む」と「仕組みで止める」を分けて考えると、ルールファイルを短く保てます。
まとめ
ルールファイルは「読んでも分からないこと」だけを、具体的に書く
失敗のたびに1行足して育てる
絶対に守らせたいことは lint・CI・権限設定に任せる
まずは、直近で自分が2回以上同じ指摘をした内容を、1行だけ書き足すところから始めてみてください。