AIコーディングエージェントのルールファイル：CLAUDE.md、.cursorrules、プロジェクト指示

ルールファイルは永続的な指示として機能します。一度のリクエストにのみ適用されるチャットプロンプトとは異なり、ルールファイルはエージェントが作業を開始するたびに自動的に読み込まれます。タスクを入力する前から、コーディング規約、アーキテクチャの決定事項、命名規則、制約についてエージェントに伝えることができます。

形式は通常シンプルです。ほとんどのエージェントはMarkdownファイルまたは構造化されたセクションを持つプレーンテキストファイルを想定しています。必須のスキーマはありません。プロジェクトにとって重要なことを記述すれば、エージェントはそれをコードと並行してコンテキストとして読み取ります。

ルールファイルに含めるべき内容

ルールファイルはセキュリティ境界ではない

ルールファイルはガイダンスであり、強制ではありません。エージェントはコンテキストとして読み取りますが、ルールを無視したり、意図と異なる解釈をしたりすることを防ぐ仕組みはありません。「ファイルを絶対に削除しない」とルールファイルに書いても、エージェントがタスク完了のためにファイル削除が最善だと判断すれば、削除する可能性があります。

プロンプトインジェクションにより、この問題はさらに深刻になります。悪意のある依存関係、README、コードコメントにルールファイルを上書きする指示が含まれている場合、エージェントはそちらの注入された指示に従う可能性があります。ルールファイルは、エージェントが読む他のテキストに対する特権を持ちません。コンテキストウィンドウの一部にすぎないのです。

実践的な結論は明確です。危険な動作を防ぐためにルールファイルに頼らないでください。望ましくない変更がコードベースに反映される前にキャッチするにはdiffレビューを使いましょう。エージェントが実行できる操作を制限するにはサンドボックスを使いましょう。出力が基準を満たしているか検証するには自動チェックを使いましょう。ルールファイルはエージェント出力の平均品質を向上させますが、制御メカニズムではありません。

ポータブルな指示 vs ベンダーロックイン形式

AIコーディングツールにはそれぞれ独自の慣例があります。Claude CodeはCLAUDE.mdを、Cursorは.cursorrules を、Windsurfは.windsurfrules を読み取ります。チームが複数のツールを使用している場合、ツールごとに個別のファイルを管理するメンテナンスの負担は、新しいツールが増えるたびに大きくなります。

よりポータブルなアプローチは、プロジェクトの指示を汎用的なMarkdownファイル（PROJECT_RULES.mdやCODING_GUIDELINES.mdなど）に記述し、各ベンダー固有のファイルからそれを参照またはインクルードする方法です。これにより、核となる指示は一箇所にまとまり、ツール固有のファイルは薄いラッパーになります。

ポータビリティの利点は利便性だけではありません。特定のベンダーのモデルだけでなく、どのエージェントにとっても明確な指示を書くことが求められるからです。特定のモデルの癖に依存した指示は脆くなりがちです。プロジェクトを明確に記述した指示は、ツールやモデルのアップデートをまたいでもうまく機能する傾向があります。

ルールファイルでよくある間違い

実践的なルールファイルテンプレート

以下は、プロジェクトに合わせてカスタマイズできる構造化されたテンプレートです。該当するセクションをコピーし、不要なものを削除して、簡潔に保ちましょう。

# Project: [プロジェクト名]

## Overview
このプロジェクトの概要、主な目的、
解決する主要な問題の簡潔な説明。

## Tech Stack
- Language: TypeScript 5.x
- Framework: React 18 with Next.js 14
- Styling: Tailwind CSS
- Testing: Vitest + Testing Library
- Package manager: pnpm

## Conventions
- フックを使った関数コンポーネントを使用。クラスコンポーネントは不可。
- コンポーネント名はPascalCase。ユーティリティ名はcamelCase。
- 1ファイル1コンポーネント。テストはソースファイルの隣に配置。
- default exportではなくnamed exportを使用。
- ネストされた条件分岐よりもearly returnを優先。

## Forbidden Patterns
- `any` 型の使用禁止。`unknown` を使い、型を絞り込む。
- 本番コードでの `console.log` 禁止。loggerを使用する。
- PRに記載なく新しい依存関係を追加しない。
- /generated 内のファイルは変更禁止（自動生成のため）。

## Testing
- テストはソースの隣に配置: `Component.test.tsx`
- テスト実行: `pnpm test`
- 新機能には最低1つのインテグレーションテストが必要。
- 外部APIはモック化し、テスト内で実際に呼び出さない。

## Key Files
- Entry point: `src/app/layout.tsx`
- API routes: `src/app/api/`
- Shared utilities: `src/lib/`
- Database schema: `prisma/schema.prisma`

CodeWingerの位置づけ

CodeWingerはプロジェクトレベルの指示をサポートしており、エージェントのコンテキストに反映されます。ローカルファーストかつBYOKのため、ルールファイルはお使いのマシンに留まり、選択したプロバイダーに直接送信されます。

• プロジェクトレベルの指示はローカルで読み取られ、エージェントのコンテキストに含まれます。
• ローカルファーストアーキテクチャにより、ルールファイルはAPIキーのプロバイダーへのAPI呼び出しの一部としてのみマシンから送信されます。
• BYOKにより、モデルとプロバイダーを自分で選べます。ルールファイルの互換性はIDEベンダーではなくモデルに依存します。
• インラインdiffレビューにより、変更がコードベースに反映される前にエージェントがルールに従ったかを確認できます。

まとめ

ルールファイルは、AIコーディングエージェントの出力を改善する最もシンプルな方法の一つです。作成コストはゼロで、リポジトリ内に保存でき、エージェントの最初の推測を的確にします。しかし、魔法ではありません。何かを強制する力はなく、diffレビュー、テスト、開発者の判断に代わるものでもありません。短く明確なルールファイルを書き、常に最新の状態に保ち、ガバナンスではなくガイダンスとして扱いましょう。

よくある質問