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

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

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

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

這很關(guān)鍵，因?yàn)樯舷挛氖怯蟹较虻摹戇w移腳本時(shí)的規(guī)則，和寫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è)問題：在這個(gè)代碼庫的特定角落，什么樣的產(chǎn)出算好的？

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

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

在任何CLAUDE.md內(nè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í)慣把這兩類混成段落，AI對(duì)它們的權(quán)重判斷 roughly equal。分開寫，AI才能區(qū)分什么是背景信息、什么是必須遵守的邊界。