DEV Community

スシロー
スシロー

Posted on

2026年版 Expressエージェントを動かすルールファイル実践ガイド

#ai #claudecode #cursor #express

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

Node.js + Express でAIエージェント(Claude や Cursor など)に開発を手伝わせると、最初は快適でも、規模が大きくなるほど「同じ指摘を毎回し直す」「プロジェクト規約を無視したコードが返る」といった摩擦が増えます。原因はシンプルで、エージェントは毎回の文脈をゼロから推測しているからです。

CLAUDE.md / .cursorrules / AGENTS.md といったルールファイルは、この推測を減らすための「常に読まれる前提知識」です。リポジトリ直下に置くだけで、エージェントはタスクのたびに規約・ディレクトリ構成・禁止事項を読み込みます。プロンプトに毎回貼り付ける手間が消え、チーム内で挙動が揃うのが実利です。効果は環境やモデルに依存するため万能ではありませんが、指示の再現性は明確に上がります。

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

ポイントは「抽象論を書かない」ことです。ファイル構成・コマンド・具体的な禁止事項を書きます。

# CLAUDE.md

## プロジェクト構成
- Node.js 20 + Express 4。ESM(`"type": "module"`)を使用。
- ルーティングは `src/routes/`、ビジネスロジックは `src/services/` に分離。
- ルートハンドラに DB クエリを直書きしない。必ず service 層を経由する。

## コマンド
- 開発起動: `npm run dev`
- テスト: `npm test`(変更後は必ず実行し、緑を確認してから完了とする)
- Lint: `npm run lint`(コミット前に通すこと)

## 規約
- 非同期ハンドラは `asyncHandler` でラップし、エラーは中央の
  エラーミドルウェア(`src/middleware/error.js`)へ委譲する。
- 環境変数は `process.env` を直接参照せず `src/config/env.js` 経由で読む。
- レスポンスは `res.json()` を使い、ステータスコードを明示する。

## 禁止事項
- `console.log` でのログ出力(代わりに `logger` を使う)。
- 新規依存パッケージの無断追加。提案時は理由を添える。
Enter fullscreen mode Exit fullscreen mode

.cursorrules(Cursor)や AGENTS.md(OpenAI Codex など)もファイル名と置き場所が違うだけで、書く中身の思想は同じです。複数ツールを併用するなら、本体を1ファイルにまとめ、他はそこを参照させると二重管理を避けられます。

運用Tips

  • 短く、具体的に。長文の理念より「やる/やらない」の箇条書きが効きます。数千行のルールはノイズになり、肝心な指示が埋もれます。
  • 検証コマンドを必ず書く。npm test を「完了条件」として明記すると、エージェントが自分で結果を確認するようになります。
  • 更新を習慣化。同じ修正指示を2回したら、それはルールに昇格させる合図です。
  • 機密を書かない。APIキーや本番URLはルールファイルに置かず、env.js 経由の参照だけ記述します。
  • 差分で育てる。最初から完璧を目指さず、運用しながら追記・削除して磨き込むのが現実的です。

ルールファイルは「エージェントへのオンボーディング資料」です。新メンバーに渡す手順書を書く感覚で整備すると、過剰な期待をせずとも着実に手戻りを減らせます。

5フレームワーク分の実例をまとめたキット

Next.js/React/FastAPI/Godot/Express のルールファイル実例集を用意しました。👉 詳細・入手はこちら

Top comments (0)