2026年版 AIエージェント(Express)に効くルールファイルの書き方

#ai #claudecode #cursor #express

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

Node.js + Express のコードベースは、ルーティング・ミドルウェア・エラーハンドリングの慣習がプロジェクトごとに微妙に違います。AIエージェント(Claude Code / Cursor など)は優秀でも、その「あなたのプロジェクト固有の暗黙ルール」を毎回ゼロから推測します。結果、res.send と res.json が混在したり、独自のエラーラッパーを無視した素の throw を書いたりします。

CLAUDE.md / .cursorrules / AGENTS.md といったルールファイルは、この暗黙知をリポジトリ直下に明文化し、エージェントの初期コンテキストへ毎回自動で読み込ませる仕組みです。プロンプトに毎回貼る手間が消え、人間レビューで何度も指摘していた事項を「最初から守らせる」方向に変えられます。効果は環境依存ですが、少なくとも指摘の往復回数を減らす狙いがあります。

実例：Express プロジェクト向けの最小ルール

ファイル名はツールで異なります(Claude Code = CLAUDE.md、Cursor = .cursorrules、横断標準を狙うなら AGENTS.md)。中身はプレーンな Markdown / テキストで構いません。

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

## ルーティング
- ルートは routes/ 配下に機能単位で分割する
- ハンドラ内に業務ロジックを書かない。services/ に委譲する

## レスポンス
- 返却は必ず res.json() を使う(res.send は禁止)
- 成功は { data }、失敗は { error: { code, message } } 形式

## エラー処理
- 非同期ハンドラは asyncWrapper() で包む(try/catch を直書きしない)
- 例外は AppError クラスで throw し、集約 errorHandler に流す

## 禁止事項
- console.log での本番ログ出力(logger を使う)
- 新規依存の追加は提案のみ。npm install を勝手に実行しない

ポイントは「曖昧な理想」ではなく「検証可能な禁止/必須」で書くことです。良いコードを書く ではなく res.send は禁止 のように、エージェントが守ったか機械的に判定できる粒度にします。

運用Tips

短く保つ：長文化すると優先度が薄まります。プロジェクト固有の決定事項に絞り、一般的なベストプラクティスは書かない。
理由を1行添える：asyncWrapper で包む(集約 errorHandler に確実に渡すため) のように根拠を書くと、未知のケースでもエージェントが応用しやすくなります。
階層配置：ルートに全体規約、routes/admin/ などサブディレクトリに局所ルールを置くと、該当箇所だけ規約を上書きできます。
レビューで育てる：人間レビューで同じ指摘を2回したら、その内容をルールへ昇格させます。ルールファイルは「指摘ログの蒸留先」と捉えると更新が回ります。
複数ツール対応：AGENTS.md を正本にし、CLAUDE.md / .cursorrules からはそれを参照(あるいは内容を同期)させると二重管理を避けられます。