大多數(shù)工程師把CLAUDE.md寫成README。他們堆上技術(shù)棧、幾點偏好、再備注下測試要求。AI代理讀了，禮貌點頭，然后繼續(xù)按訓(xùn)練數(shù)據(jù)寫代碼，而不是按你的代碼庫寫。

文件存在，但沒什么用。

問題不在努力程度，在文件類型。README描述項目，規(guī)范約束行為。CLAUDE.md只有作為后者才有效，但大多數(shù)工程師從沒給代理寫過規(guī)范，于是順手用了熟悉的格式。

本文從三個維度講清楚：文件怎么組織、規(guī)則怎么寫代理才會遵守、代碼庫演進時怎么保持文件更新。

Claude Code從項目根目錄讀取CLAUDE.md。大多數(shù)人不知道的是，它也會從正在工作的任何子目錄讀取CLAUDE.md，而且這些文件會繼承根目錄的配置。

這很重要，因為上下文是有方向的。代理寫遷移時的規(guī)則，和寫Sidekiq任務(wù)時的規(guī)則不一樣。單個根文件試圖同時編碼兩者，結(jié)果要么是冗余，要么是矛盾。

有效的結(jié)構(gòu)長這樣：

project/

├── CLAUDE.md（全局約束、技術(shù)棧、溝通協(xié)議）

├── app/

│ ├── models/CLAUDE.md（數(shù)據(jù)庫模式規(guī)則、驗證模式、查詢約束）

│ ├── jobs/CLAUDE.md（冪等性規(guī)則、重試邏輯、失敗處理）

│ └── services/CLAUDE.md（何時抽取、接口契約、禁止上帝對象）

└── db/

└── migrate/CLAUDE.md（遷移規(guī)則、索引要求、可回滾性）

每個文件回答：在這個代碼庫的特定部分，好的工作長什么樣？

根文件處理全局通用的事：固定版本、已確定的架構(gòu)決策、溝通協(xié)議（執(zhí)行前計劃、動數(shù)據(jù)庫模式前先問）。目錄文件編碼本地專業(yè)知識。代理打開app/jobs/時，會讀兩個文件，本地文件在沖突時優(yōu)先。

根文件最后寫。寫完目錄文件后，你會知道什么在重復(fù)出現(xiàn)，那才屬于根文件。

在任何CLAUDE.md內(nèi)部，兩類內(nèi)容與代理決策的距離不同。

事實描述環(huán)境：

技術(shù)棧：Ruby 3.3.4、Rails 7.2.1、PostgreSQL 15、Sidekiq 7.3、pgvector 0.7（用于app/models/document.rb，非廣泛可用）

規(guī)則約束行為：

數(shù)據(jù)庫規(guī)則：禁止在循環(huán)中更新記錄，使用基于集合的更新；禁止不帶WHERE條件調(diào)用update_all；每個觸及documents表的查詢合并前需要EXPLAIN ANALYZE。

工程師把這兩類混成段落，代理對它們大致同等對待。