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

文件存在，但沒什么用。

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

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

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

這很重要，因?yàn)樯舷挛氖怯蟹较虻?。代理寫遷移時(shí)的規(guī)則，和寫Sidekiq任務(wù)時(shí)的規(guī)則不一樣。單個(gè)根文件試圖同時(shí)編碼兩者，結(jié)果要么是冗余，要么是矛盾。

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

project/

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

├── app/

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

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

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

└── db/

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

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

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

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

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

事實(shí)描述環(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；每個(gè)觸及documents表的查詢合并前需要EXPLAIN ANALYZE。

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