工程師們寫(xiě)CLAUDE.md的姿勢(shì)，像極了寫(xiě)README——堆上技術(shù)棧、撒幾條個(gè)人偏好、補(bǔ)一句"記得寫(xiě)測(cè)試"。文件是有了，Claude也"讀"了，但寫(xiě)出來(lái)的代碼照舊跟著訓(xùn)練數(shù)據(jù)走，跟你的代碼庫(kù)沒(méi)什么關(guān)系。

問(wèn)題不在用不用心，在搞錯(cuò)了品類(lèi)。README是描述項(xiàng)目的，技術(shù)規(guī)格才是約束行為的。CLAUDE.md要生效，得按后者寫(xiě)。但大多數(shù)工程師沒(méi)給AI寫(xiě)過(guò)規(guī)格書(shū)，本能地套用了熟悉的格式。

這篇內(nèi)容聊三個(gè)維度：文件怎么搭結(jié)構(gòu)、規(guī)則怎么寫(xiě)才能被遵守、代碼庫(kù)演進(jìn)時(shí)怎么維護(hù)這份文件。

Claude Code從項(xiàng)目根目錄讀CLAUDE.md，但很多人不知道的是——它在任何子目錄工作時(shí)，也會(huì)讀該目錄下的CLAUDE.md，而且這些文件會(huì)繼承根目錄的配置。

這很關(guān)鍵，因?yàn)樯舷挛氖怯蟹较虻?。?xiě)遷移腳本時(shí)的規(guī)則，和寫(xiě)Sidekiq任務(wù)時(shí)的規(guī)則，本就不是一回事。硬塞進(jìn)一個(gè)根文件，結(jié)果要么是冗余，要么是自相矛盾。

一種可行的結(jié)構(gòu)：

project/
├── CLAUDE.md —— 全局約束、技術(shù)棧、溝通協(xié)議
├── app/
│ ├── models/CLAUDE.md —— 表結(jié)構(gòu)規(guī)則、驗(yàn)證模式、查詢約束
│ ├── jobs/CLAUDE.md —— 冪等性規(guī)則、重試邏輯、失敗處理
│ └── services/CLAUDE.md —— 何時(shí)抽取、接口契約、禁止上帝對(duì)象
└── db/
└── migrate/CLAUDE.md —— 遷移規(guī)則、索引要求、可回滾性

每個(gè)文件回答同一個(gè)問(wèn)題：在這個(gè)代碼庫(kù)的特定角落，什么樣的產(chǎn)出算好的？

根目錄管放之四海而皆準(zhǔn)的東西：鎖定版本、已敲定的架構(gòu)決策、溝通協(xié)議（先規(guī)劃再執(zhí)行、動(dòng)表結(jié)構(gòu)前先問(wèn)）。目錄文件則編碼本地經(jīng)驗(yàn)。當(dāng)Claude打開(kāi)app/jobs/，它會(huì)讀兩份，本地文件沖突時(shí)優(yōu)先。

根文件建議最后寫(xiě)。等你寫(xiě)完各目錄文件，自然能看出哪些東西在重復(fù)——那些就是該上浮到全局的。

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

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

## Stack
- Ruby 3.3.4
- Rails 7.2.1
- PostgreSQL 15
- Sidekiq 7.3
- pgvector 0.7（用于app/models/document.rb，非廣泛可用）

規(guī)則約束行為：

## Database
禁止在循環(huán)里更新記錄，用集合更新。
禁止不帶WHERE條件調(diào)用update_all。
任何觸及documents表的查詢，合并前必須有EXPLAIN ANALYZE。

工程師們習(xí)慣把這兩類(lèi)混成段落，AI對(duì)它們的權(quán)重判斷 roughly equal。分開(kāi)寫(xiě)，AI才能區(qū)分什么是背景信息、什么是必須遵守的邊界。