CursorやClaude Codeなどの自律型AIコーディングエージェントを利用する際、AIの出力精度を高めるための最大の鍵は「適切な前提情報の提供」です。
プロジェクト固有のコーディング規約をまとめたMarkdownファイルを配置するだけで、コード生成におけるハルシネーション（誤動作）を大幅に減らせます。本記事では、AIの理解力を高めるための「コンテキスト用Markdownファイル」の書き方を解説します。
1. なぜルールファイルの配置が必要なのか
AIは高度な推論能力を持ちますが、初期状態ではプロジェクトの暗黙のルール（ライブラリのバージョンや命名規則など）を知りません。
ルールを事前に明文化しておかないと、AIは一般的な知識に基づいて古い書き方を提案したり、プロジェクトで禁止されている手法でコードを修正したりしてしまいます。これらを防ぐために、人間にとってもAIにとっても一貫した道標となる「コンテキストファイル」が必要です。
2. コンテキスト用Markdownに記述すべき5つの要素
効果的なコンテキストファイルを作成するためには、以下の5つの情報を整理して記述します。
- ① プロジェクト概要と技術スタック: システムの目的と、使用している言語やフレームワーク（TypeScriptやNext.jsなど）を明記します。
- ② ディレクトリ構造の解説: どのフォルダに何のコードを配置するルールになっているかを示し、AIが必要なファイルを探す時間を短縮します。
- ③ コーディング規約とデザインルール: 命名規則や状態管理の方針、CSSの書き方などを記載します。
- ④ よく使うコマンドリスト: テスト（
npm test）やビルド、静的解析など、AIが自動でコード品質を確認するための実行コマンドをまとめます。 - ⑤ AIに対する動作制約・禁止事項: 「勝手に一括リファクタリングをしない」や「対話型コマンドを走らせない」などの動作制御を記述します。
3. 各ツールにおけるルールファイルの配置方法
代表的なAIコーディングツールでは、以下のようにファイルを配置することで自動的に読み込ませることができます。
Cursor（.cursorrules および .mdc ファイル）
Cursorでは、プロジェクトのルートディレクトリに .cursorrules ファイルを置くことで、チャットやインライン編集の際にルールが読み込まれます。
さらに最新の機能では、.cursor/rules/ ディレクトリ内に .mdc（Markdown Cursor） というファイルを置く方法が推奨されています。以下のようにフロントマターを記述することで、特定のファイルパターンが編集されたときのみ、ピンポイントでルールを適用させることができます。
---
description: Reactのクライアントコンポーネントを作成する際のルール
globs: src/components/**/*.tsx
---
# React Component Rules
- クライアントサイドの処理を含む場合は必ず先頭に "use client" を記述してください。
- スタイリングには必ずCSSモジュールを使用し、インラインCSSは避けてください。
Claude Code（CLAUDE.md）
AnthropicのCLIツールであるClaude Codeでは、リポジトリのルートに CLAUDE.md というファイルを配置する規約があります。Claude Codeは起動時にこのファイルをスキャンし、開発規約やテストの実行コマンドを理解した上で動作します。
4. すぐに使える汎用Markdownテンプレート
以下は、多くのプロジェクトでそのまま応用できるコンテキストMarkdownの構成例です。必要に応じて書き換えてリポジトリのルート（AGENTS.md や CLAUDE.md など）に配置してください。
# Project Context & Rules
## 1. System Overview
- **Project Name**: Tech Note Blog
- **Stack**: Next.js (App Router), TypeScript, Vanilla CSS
- **Database**: PostgreSQL (Prisma ORM)
## 2. Directory Structure
- `src/app/`: ルーティングと各ページのコンポーネントを配置
- `src/components/ui/`: 再利用可能な最小限のUIパーツ
- `src/hooks/`: カスタムフックを管理
- `src/lib/`: APIクライアントや共通ユーティリティ関数
## 3. Coding Standards
- TypeScriptの型定義では `any` の使用を禁止し、厳格に型を定義する。
- 状態管理は原則としてReactの標準Hooks（useState/useContext）で行う。
- 見出しやボタンなどの共通部品は、既存の `src/components/ui/` 内のものを最優先で再利用する。
## 4. Useful Commands
- 開発サーバー起動: `npm run dev`
- テスト実行: `npm run test`
- 静的解析と整形: `npm run lint` && `npm run format`
- ビルド確認: `npm run build`
## 5. Instructions for AI Agent
- コードを変更する前に、必ず関連ファイルの構造 and 既存の実装パターンを確認してください。
- 変更を行った後は、関連するテストがあれば必ずテストコマンドを実行して動作を確認してください。
- ライブラリの新規インストールが必要な場合は、実行前に人間に確認を求めてください。
5. まとめ
リポジトリにMarkdownファイルを1つ配置するだけで、AIエージェントの理解力は飛躍的に向上します。このルールファイルはAIのためだけのものではなく、新しくプロジェクトに参画した人間の開発者にとっても優れたオンボーディング（導入）ドキュメントになります。
プロジェクトの進化やライブラリの選定変更に合わせて、ルールファイルも定期的に更新し、リポジトリの鮮度を高く保つようにしましょう。