2026年版 Expressエージェントに効くルールファイル(CLAUDE.md/AGENTS.md)実例と書き方

#ai #claudecode #cursor #express

なぜルールファイルが「効く」のか

AIエージェントは毎回ゼロからコードを読む。Node.js + Express のプロジェクトでも、ミドルウェアの登録順やエラーハンドリングの規約は、コードを全部読まないと分からない。ルールファイル(CLAUDE.md / .cursorrules / AGENTS.md)は、その「暗黙の前提」を毎回のコンテキスト先頭に注入する仕組みだ。つまり推論精度を上げる魔法ではなく、プロジェクト固有の制約を明文化して読み込ませるための設定ファイルにすぎない。だからこそ、曖昧な理念ではなく、検証可能で具体的な指示ほど効果が出やすい。

実例:Express プロジェクト用ルール

抽象論より一例。以下は実際に置けるルールだ。

# プロジェクト規約 (Express API)

## アーキテクチャ
- ルーティングは routes/、ロジックは services/ に分離する
- res.json() を直接書かず、必ず sendSuccess(res, data) ヘルパーを使う

## エラー処理
- async ハンドラは asyncWrapper() で包む(try/catch を手書きしない)
- 例外は next(err) で集約ミドルウェア errorHandler に渡す

## 禁止事項
- process.env を直接参照しない。config/index.js 経由で読む
- console.log を残さない。logger.info / logger.error を使う

## 検証
- 変更後は必ず `npm run lint && npm test` を実行し、結果を報告する

ポイントは三つ。①「やること」だけでなく禁止事項を書く、②sendSuccess のような実在するヘルパー名を指定する、③最後に検証コマンドを明示してエージェントに自走させる点だ。命名が実在しないとエージェントは幻のAPIを呼ぶので、必ずコードと一致させる。

運用Tips

短く保つ:長文は読み飛ばされやすい。原則20〜30行を上限にし、詳細はリンクで参照させる。
階層を使う:モノレポなら各パッケージ直下にもルールファイルを置く。近い階層のルールほど優先されやすい。
AGENTS.md は共通の入口:複数ツールを併用するなら、規約本体を AGENTS.md に書き、CLAUDE.md から参照する運用がメンテしやすい。
守られない規則は消す:無視され続けるルールは曖昧か矛盾している兆候。具体例つきに書き換えるか削除する。
PRで育てる:エージェントが同じミスを繰り返したら、それを1行のルールとして追記する。レビュー指摘の蓄積がそのまま資産になる。