AI にプロジェクトを理解させる：コンテキストとルールファイル

モジュール 05 第 5 課で扱ったとおり、モデルそのものは何も覚えておらず、会話は毎回ゼロから始まります。AI コーディングツールも同じです。昨日 30 分かけて「うちのテストは make test で実行する必要があって、直接 pytest を実行してはいけない」と説明したのに、今日新しい会話を開くと、また直接 pytest を実行してしまいます。

解決策は、こうした「毎回説明し直さなければならないこと」をファイルに書き、ツールが起動のたびに自動でコンテキストに読み込むようにすることです。この課ではそのファイルの書き方を扱います。

こうしたファイルは何と呼ばれるか

ツールによって読むファイルが違います。2026 年 9 月時点で、各社の公式ドキュメントによれば次のとおりです。

AGENTS.md はオープンな形式で、今は Linux Foundation 傘下の Agentic AI Foundation が管理しており、公式サイト（agents.md）には対応するツールが二十以上並んでいます。その位置づけは単純です。README は人に向けて、AGENTS.md は AI コーディングツールに向けて書くものです。

Claude Code のドキュメントには、CLAUDE.md を読み、AGENTS.md は読まないとはっきり書いてあります。プロジェクトにすでに AGENTS.md があるなら、公式に推奨されているやり方は、CLAUDE.md を作って @AGENTS.md と 1 行書き、それを取り込むことです。そうすれば二種類のツールが同じ内容を読み、二つを保守する必要がありません。

@AGENTS.md

## 只对 Claude Code 生效的补充
改动 src/billing/ 下的代码之前，先进入计划模式。

ファイル名やルールはバージョンによって変わるので、使う前に使っているツールの最新のドキュメントに目を通してください。以下で扱う書き方は、この種のファイルすべてに当てはまります。

どこに置くか、どれが優先されるか

この種のファイルはふつう、いくつかの階層に置けます。

• 個人のグローバル：たとえば ~/.codex/AGENTS.md や ~/.claude/CLAUDE.md で、すべてのプロジェクトに共通するあなた個人の好みを書きます。
• プロジェクトのルートディレクトリ：git にコミットし、チーム全体で共有します。
• サブディレクトリ：大きなリポジトリでは、あるサブプロジェクトが専用のファイルを持つことができ、そのディレクトリのファイルを扱うときだけ効きます。

複数のファイルが同時にあるとき、一般的なルールは今作業しているファイルに近いほど優先されるです。AGENTS.md の公式サイトの原文は「The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything」で、編集しているファイルに最も近いものが効き、あなたが会話の中で直接言ったことが最も優先される、ということです。Codex と Claude Code は、ルートディレクトリから今のディレクトリまでの各階層のファイルを順につなげ、今のディレクトリに近いものほど後ろに来るので、後ろの内容が自然と前の内容を上書きします。

何を書くか

一つの問いで判断します。これは、毎回 AI に説明し直さなければならないことか？

書く価値があるのは、たいてい次のようなものです。

ビルド、テスト、チェックの方法。これが最も重要な項目です。AI がコードを変えたら、自分で確かめられる必要があります。具体的なコマンドをはっきり書きます。

## 命令
- 安装依赖：`uv sync`
- 运行全部测试：`uv run pytest -q`
- 只跑一个文件：`uv run pytest tests/test_retrieval.py -q`
- 代码检查：`uv run ruff check .`

プロジェクトの構成。どのコードがどのディレクトリにあるか、エントリーポイントはどこか。AI がファイル名から読み取れない部分だけを書きます。

このプロジェクト特有の決まり。一般的なやり方と違うところが、最も書く価値があります。

## 约定
- 所有调用大模型的代码都通过 `llm.py` 里的函数，不要直接 new 一个 OpenAI 客户端。
- 价格表在 `llm.PRICES`，改价格只改这一处。
- 用户能看到的文字一律用中文。

踏んだ落とし穴。AI が一度犯した誤りを書き留め、再発を防ぎます。

## 注意
- 检索器里调用本地模型必须持有 `_MODEL_LOCK`，多线程同时调用会互相争抢到几乎卡死。
- `data/httpx-docs/` 是第三方文档的副本，不要修改里面的文件。

何を書かないか

• AI がコードを見ればわかること。ディレクトリにどんなファイルがあるか、どんな依存パッケージを使っているかは、自分で見ます。書いてもコンテキストの無駄になるだけです。
• 漠然とした原則。「質の高いコードを書く」「セキュリティに気をつける」には、チェックできる中身が何もなく、書かないのと同じです。
• とても長い手順。ある種のタスクでしか必要ない長い手順は、毎回読むファイルには向いていません。必要なときだけ読み込む専用の仕組みを持つツールもあります（Claude Code の skills、Cursor の条件つきで効くルールなど）。
• 秘密。キー、パスワード、社内のアドレスは、一切書かないでください。このファイルは git にコミットされ、モデルのコンテキストにも入ります。

Claude Code のドキュメントは、CLAUDE.md を 200 行以内に収めることを勧めています。理由は単純です。このファイルは毎回丸ごとコンテキストに読み込まれるので、長いほど場所を取り、しかもルールが多いほどモデルがすべてを守るのが難しくなります。

具体的に書いてこそ守られる

二つの書き方を比べてください。

具体的な書き方には共通点があります。チェックできることです。AI ができたかどうかは、見ればすぐにわかります。あいまいな書き方だと、AI は自分ではもうできていると思ってしまいます。

ルールどうしが矛盾してはいけません。ルートディレクトリのファイルが「インデントは空白 2 つ」と言い、サブディレクトリのファイルが「空白 4 つ」と言えば、モデルはどちらかを適当に選ぶかもしれません。定期的にこうしたファイルを読み返し、古くなったものや互いに矛盾するものを削除しましょう。

ルールファイルはコンテキストであって、強制ではない

この点はとても重要で、最も誤解されやすいところでもあります。

Claude Code の公式ドキュメントははっきり書いています。CLAUDE.md はコンテキストとしてモデルに渡され、モデルはできるだけ守ろうとしますが、厳密に守ることは保証されない。強制的に実行されるルールではないのです。ファイルに「.env ファイルを変更しない」と書けば、モデルはたいていそのとおりにしますが、必ず例外があります。

モジュール 05 第 8 課の実験がよい対比になります。プロンプトにはっきり書いたセキュリティのルールでも、強いほうのモデルは 5 回中 4 回違反しました。ルールファイルとプロンプトは本質的に同じものです。

ですから、本当に触れてはいけないものは、ルールファイルに書いてモデルの自覚に期待するのではなく、ツールが用意している強制の仕組みで制限すべきです。

• 権限の設定：ほとんどのツールでは、どのコマンド、どのファイルにあなたの確認が必要で、どれを直接禁止するかを設定できます。たとえば Claude Code は設定に禁止ルールを書け、Codex は読み取り専用や作業ディレクトリの中にしか書き込めないサンドボックスを選べます。
• フック：特定のタイミングであなたのスクリプトを自動で実行できるツールもあります。たとえばファイルを変更するたびに自動で整形を実行する、コマンドを実行する前にそれが危険なコマンドでないかチェックする、など。フックはプログラムが実行するもので、モデルの判断に頼りません。
• git とコードレビュー：AI の変更はすべて git でコミットし、マージする前にあなたが目を通します。これが最後の、そして最も信頼できる関門です。

一言でいえば、ルールファイルは AI に「どうすればよりよいか」を伝えるためのもので、強制の仕組みは「絶対にしてはいけないこと」を保証するためのものです。

空のファイルから始める

最初から大がかりで網羅的なルールファイルを書こうとしないでください。よりよいやり方はこうです。

1. ツールに付属する初期化コマンドで草稿を作る。Claude Code と Codex にはどちらも /init コマンドがあり、プロジェクトを分析して、ビルドのコマンドやディレクトリ構成といった基本的な情報を書いてくれます。
2. AI がコードを見ればわかる内容を削り、AI が知らないことを補う。チームの決まり、踏んだ落とし穴です。
3. その後、AI が同じ誤りを 2 回犯すたびに、あるいは自分が会話の中でまた同じことを説明し直していると気づくたびに、ファイルに一行加える。

ルールファイルは評価セットと同じで、使いながら少しずつ育っていくものです。

練習問題

1. 自分のプロジェクトの一つのために AGENTS.md（または CLAUDE.md）を 50 行以内で書いてください。書き終えたら、この課の「何を書かないか」の節と照らし合わせて一通り削ってください。
2. AI に厳密に守らせたいルールを一つ選び（たとえば「migrations ディレクトリを変更してはいけない」）、使っている AI コーディングツールに、それをルールファイルに書くだけでなく強制的な制限にする方法があるか調べてください。
3. このコースの RepoBot v4 のために AGENTS.md を書いてください。考えてみましょう。このプロジェクトを初めて開く AI コーディングツールが、最も知る必要があるのはどんなことでしょうか。

確認テスト

1. プロジェクトにすでに AGENTS.md があり、Claude Code にも同じ内容を読ませたいとき、どうしますか？

Claude Code は CLAUDE.md を読み、AGENTS.md は読みません。公式ドキュメントに従い、CLAUDE.md を作って @AGENTS.md と 1 行書いて取り込み、その下に Claude Code だけ向けの内容を追記することもできます。追加の内容が要らなければ、AGENTS.md を指すシンボリックリンクを作ってもかまいません。

2. ルールファイルに「.env ファイルを変更しない」と書けば、AI が変更しないことを保証できますか？

できません。ルールファイルはコンテキストとしてモデルに渡され、モデルはできるだけ守ろうとしますが、保証はされません。本当に触れてはいけないものは、ツールの権限の設定やフックのような強制の仕組みで制限し、git で一つ一つの変更をレビューすべきです。

3. ルールファイルに最も書く価値があるのは何ですか？最も書くべきでないのは何ですか？

最も書く価値があるのは、AI が自分では読み取れず、しかも毎回必要な情報です。ビルドとテストの方法（具体的なコマンド）、プロジェクト特有の決まり、踏んだ落とし穴。最も書くべきでないのは、AI がコードを見ればわかること、チェックできない漠然とした原則、そしてあらゆるキーやパスワードです。