レッスン5：ルールファイル運用——AGENTS.md／CLAUDE.md／.cursorrules／.windsurfrules

このレッスンで学ぶこと

ルールファイルが「モデルへのシステムプロンプト」でありコードの一部であることを理解する
AGENTS.md（2025 年に登場した業界横断規約）と各ツール固有ファイルの共通・差異を押さえる
ルールファイルに書くべき内容 6 分類（プロジェクト概要・技術スタック・コーディング規約・禁止事項・テスト戦略・ディレクトリ地図）を設計できる
README・寄稿ガイドとルールファイルの棲み分けを判断できる
アンチパターン（長すぎる／更新されない／複数ツール向けを 1 か所に押し込む）を回避できる

前回のレッスン 4 では、エージェント型・自律型のツール使い分けと非同期委譲の運用設計を扱いました。今回は、それらのツールがリポジトリを読み込む際に「最初に見る」ルールファイルの運用に踏み込みます。AGENTS.md／CLAUDE.md はコードの一部である——今回の中核メッセージが、コース全体を通して大きな意味を持ちます。

ルールファイルとは何か——「モデルへのシステムプロンプト」

ルールファイル（rule file）は、AI 駆動開発ツールがリポジトリを扱う際に、自動的に読み込んで参照するテキストファイルの総称です。プロジェクトのルート（あるいは特定のディレクトリ）に配置し、そのプロジェクトを扱うすべての AI 対話・エージェント実行に共通で適用されます。

役割としては、大規模言語モデルの「システムプロンプト」に近いものです。ユーザーが個別の対話で毎回書かなくても、モデルが最初に読み込んで「これに沿って振る舞う」ように設定できます。

「コードの一部」として扱う意味

ルールファイルを README や寄稿ガイドと同じ扱いにしてしまうと、次のような問題が起きます。

チームメンバーが目を通さず、内容が古くなる
変更履歴が意識されず、いつ・なぜ変わったかが追えなくなる
レビュー対象にならず、質が保証されない

本コースでは、ルールファイルをコードの一部として扱うことを提案します。具体的には次の 4 点です。

コードと同じリポジトリで管理し、Git 履歴を残す
変更は Pull Request 経由で行い、レビューを通す
コーディング規約と同じレベルで扱い、更新責任を明確にする
CI で「AGENTS.md がある」「必須項目が書かれている」といったチェックを組み込むことも検討する

💡 ポイント ルールファイルは README 以上に読まれる文書です。README は人間が「一度読んで終わり」ですが、ルールファイルは AI が「毎回読み直す」文書だからです。この特性を踏まえて、README よりも高い頻度で更新される前提で設計します。

AGENTS.md——2025 年に登場した業界横断規約

各ツールがそれぞれ固有のルールファイル形式を持つと、複数ツールを併用するチームは同じ情報を複数箇所に書く必要が出てきます。この課題に対して、2025 年に業界横断規約として提唱されたのが AGENTS.md です。

AGENTS.md は、複数の AI 駆動開発ツールが共通で参照する、標準化されたルールファイル形式を目指しています。プロジェクトのルートに AGENTS.md を置くことで、対応するツールがこのファイルを読み込むようになります。

AGENTS.md の位置づけ

AGENTS.md は「共通の土台」を提供する規約です。各ツールが個別に持つ設定（Claude Code の CLAUDE.md、Cursor の .cursorrules、Windsurf の .windsurfrules など）と併存でき、共通事項は AGENTS.md に、ツール固有の設定は各ファイルに書く——という使い分けが自然です。

📝 補足 AGENTS.md は 2025 年に登場した比較的新しい規約で、対応ツールは順次拡大しつつあります。最新の対応状況は、AGENTS.md 提唱元のドキュメントで確認してください。本コースでは「業界横断の統一に向けた動き」として位置づけ、詳細な仕様は個別ドキュメントに譲ります。

各ツール固有ファイルの共通と差異

主要な AI 駆動開発ツールが持つルールファイルを整理します。

flowchart TB
  A[AGENTS.md<br/>業界横断規約]
  C[CLAUDE.md<br/>Claude Code]
  U[.cursorrules<br/>Cursor]
  W[.windsurfrules<br/>Windsurf]
  A --> S[共通の土台<br/>プロジェクト概要<br/>コーディング規約]
  C --> C1[Claude Code 固有<br/>Subagent 定義など]
  U --> U1[Cursor 固有<br/>Composer 挙動など]
  W --> W1[Windsurf 固有<br/>Cascade 挙動など]

CLAUDE.md（Claude Code）

Claude Code は、リポジトリのルート（あるいは各ディレクトリ）に配置された CLAUDE.md を自動読み込みします。ホームディレクトリの ~/.claude/CLAUDE.md は個人グローバル設定、リポジトリ内の CLAUDE.md はプロジェクト固有設定、というように階層で読み込まれます。

.cursorrules（Cursor）

Cursor は、リポジトリのルートに .cursorrules ファイルを配置することで、そのプロジェクトでの Cursor の振る舞いを制御できます。エディタ設定と同じ階層で扱われ、Cursor 起動時に自動読み込みされます。

.windsurfrules（Windsurf）

Windsurf も同様に、リポジトリのルートに .windsurfrules ファイルを配置することで、Cascade など Windsurf のエージェント機能の振る舞いを設定できます。

共通の内容と、ツール固有の内容

共通の内容（AGENTS.md に書く候補）：

プロジェクトの目的・概要
技術スタック（言語・フレームワーク・データベース）
コーディング規約
禁止事項（例：特定のライブラリを使わない、テストなしのコミット禁止）
テスト戦略
ディレクトリ地図

ツール固有の内容（各ツールのファイルに書く）：

Claude Code の Subagent 定義や Skills の呼び出し方
Cursor Composer の挙動指示
Windsurf Cascade の探索範囲設定

ルールファイルに書くべき内容 6 分類

具体的にルールファイルに何を書くか、実務で使える 6 分類を提示します。

1. プロジェクト概要

「このプロジェクトは何のためのものか」を 2〜4 文で書きます。ターゲットユーザー・主要機能・ビジネスコンテキストが含まれると、AI がタスクの妥当性を判断できるようになります。

2. 技術スタック

使っている言語・フレームワーク・データベース・主要ライブラリを列挙します。バージョン情報も併記すると、依存関係の古さによる失敗（レッスン 3 で扱った失敗パターン）を防げます。

3. コーディング規約

命名規則・インデント幅・エラーハンドリング方針・ログ出力形式・コメントスタイルなど。ここに書いた内容は、AI が生成するコードに直接反映されます。

4. 禁止事項

「これはやらない」を明示します。例：console.log を本番コードに残さない、特定のグローバル状態を避ける、非推奨 API を使わない、外部サービスへの直接依存を隠蔽しない、など。禁止事項は肯定形の規約と同じくらい重要です。

5. テスト戦略

どのファイルにどの粒度のテストを書くか、テスト実行コマンドは何か、テストなしのコミットは禁止か、といった方針を書きます。「関連するテストも書いてください」と AI に指示するときの土台になります。

6. ディレクトリ地図

主要ディレクトリの役割を書きます。「src/api/ は HTTP エンドポイント」「src/domain/ はビジネスロジック」「src/infra/ は外部依存」など、モデル境界が言語化されていると、AI が「新機能をどこに置くか」の判断を大きく外しません。

📖 もっと詳しく ルールファイルはコードの一部として扱う——このメッセージを、次のような具体的な形で運用します。（1）AGENTS.md／CLAUDE.md の変更は必ず PR レビューを通す。（2）大きな設計変更のたびにルールファイルの更新有無を確認する。（3）四半期に 1 回、内容の陳腐化がないか棚卸しする。

README・寄稿ガイドとの棲み分け

ルールファイルと似た役割を持つ文書に、README と寄稿ガイド（CONTRIBUTING.md）があります。3 者の役割は次のように分けられます。

文書	主な読者	内容	更新頻度
README	新規参加者・利用者	プロジェクト全体像・使い方	大きな変更時
寄稿ガイド	コントリビュータ	開発フロー・PR ルール・Issue の書き方	フロー変更時
ルールファイル	AI 駆動開発ツール	プロジェクト概要・技術スタック・規約・ディレクトリ地図・禁止事項	頻繁（週次〜月次）

3 者は内容が重なる部分もあります。特に「プロジェクト概要」「技術スタック」は複数箇所に書きたくなりますが、同じ情報を複数箇所に書くのは避けるのが原則です。ルールファイルには「AI が読むための構造化」を、README には「人間が読むための語り」を、と役割で分けます。重複するときは、片方から参照する形（「詳細は AGENTS.md を参照」）にします。

アンチパターン——避けるべき運用

ルールファイル運用で、実務でよく起きるアンチパターンを 3 つ挙げます。

アンチパターン 1：長すぎる

「あれも書いておきたい、これも書いておきたい」で、5,000 行を超えるようなルールファイルが生まれることがあります。しかし AI モデルのコンテキスト窓には限りがあり、長すぎるルールファイルはむしろ「読まれない」「重要な情報が埋もれる」結果を招きます。

目安：ルールファイルは、頑張って 500〜1,000 行以内に収めます。それを超えるときは、階層化（トップの AGENTS.md は概要、詳細は各ディレクトリの AGENTS.md）を検討します。

アンチパターン 2：更新されない

一度書いて放置され、実際のコードとルールファイルの記述が乖離するケースです。技術スタックが更新されたのに古いフレームワーク名が残っていたり、コーディング規約が緩和されたのに古い禁止事項が書かれ続けていたり——という状態です。

対策：ルールファイルの更新責任を、ラベル・オーナー・レビュー要件で組織的に担保します。「大きな設計変更 PR ではルールファイル更新の要否を必ずレビュアーが確認する」といった運用も有効です。

アンチパターン 3：複数ツール向けを 1 か所に押し込む

「Copilot 向けの指示」「Cursor 向けの指示」「Claude Code 向けの指示」を 1 つのファイルに混ぜて書くと、それぞれが本来必要としない情報まで読まされ、精度が下がります。

対策：共通事項は AGENTS.md、ツール固有事項は各ツール固有のファイルへ、と分離します。ツール固有ファイルも「そのツールが読むだけの情報」に絞ります。

⚠️ 注意 「1 ファイルにまとめたほうが管理が楽」と思いがちですが、モデルへの入力設計として見ると、分離のほうが精度が上がります。管理コストは Git 履歴と PR レビューでカバーします。

まとめ

このレッスンでは、以下のことを学びました。

ルールファイルは「モデルへのシステムプロンプト」であり、README 以上に読まれる文書として設計する必要があること
「コードの一部」として扱い、PR レビューを通し、Git 履歴を残す運用が定着の鍵であること
AGENTS.md（2025 年業界横断規約）と、各ツール固有ファイル（CLAUDE.md／.cursorrules／.windsurfrules）の共通・差異
書くべき内容 6 分類（プロジェクト概要・技術スタック・コーディング規約・禁止事項・テスト戦略・ディレクトリ地図）
README・寄稿ガイドとの棲み分け（同じ情報を複数箇所に書かない）
アンチパターン 3 つ（長すぎる・更新されない・複数ツール向けを 1 か所に押し込む）と対策

次のレッスンでは、AI 駆動開発時代のテスト戦略の再設計と、AI コードレビューツール（GitHub Copilot Code Review・CodeRabbit・Greptile・Sourcery）を扱います。「AI コードにはテストがいちばん効く、ただし AI に実装とテストを同時に書かせる循環は危険」という中核メッセージが具体化していきます。

確認クイズ

このレッスンの理解度をチェックしましょう。