讓 AI 讀懂你的專案：上下文和規則檔案

第 05 模組第 5 課講過：模型本身不記得任何東西，每次對話都從零開始。AI 程式設計工具也一樣。你昨天花了半小時跟它解釋"我們的測試要用 make test 跑，不能直接 pytest"，今天開啟一個新對話，它又直接跑了 pytest。

解決辦法是把這些"每次都要重新解釋的事情"寫進一個檔案，讓工具每次啟動時自動讀進上下文。這一課講這個檔案怎麼寫。

這些檔案叫什麼

不同的工具，讀的檔案不一樣。截至 2026 年 9 月，各家官方文件的說法是：

AGENTS.md 是一個開放的格式，現在由 Linux 基金會下的 Agentic AI Foundation 維護，它的官網（agents.md）列出了二十多個支援它的工具。它的定位很簡單：README 是寫給人看的，AGENTS.md 是寫給 AI 程式設計工具看的。

Claude Code 的文件明確寫著它讀 CLAUDE.md 而不讀 AGENTS.md。如果你的專案已經有了 AGENTS.md，官方推薦的做法是建一個 CLAUDE.md，裡面寫一行 @AGENTS.md 把它引進來，這樣兩類工具讀到的是同一份內容，不用維護兩份：

@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 自己看程式碼就能知道的內容，補上它不知道的：團隊約定、踩過的坑。
3. 以後每當 AI 犯了第二次同樣的錯誤，或者你發現自己又在對話裡重複解釋同一件事，就往檔案里加一條。

規則檔案和評估集一樣，是在使用中一點點長出來的。

練習

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 把它引入，下面還可以追加只針對 Claude Code 的內容；如果不需要額外內容，也可以建一個指向 AGENTS.md 的符號連結。

2. 在規則檔案裡寫了"不要修改 .env 檔案"，能保證 AI 不會改嗎？

不能。規則檔案是作為上下文交給模型的，模型會盡量遵守，但不保證。真正不能碰的東西，要用工具的許可權設定、鉤子這類強制機制來限制，並且通過 git 審查每一次改動。

3. 規則檔案裡最值得寫的是什麼？最不應該寫的是什麼？

最值得寫的是 AI 自己看不出來、又每次都需要的資訊：怎麼構建和測試（具體命令）、專案特有的約定、踩過的坑。最不應該寫的是 AI 看程式碼就能知道的東西、沒法檢查的泛泛原則，以及任何金鑰和密碼。