CLAUDE.md 会在每次会话开始时被读进上下文。这意味着它的每一行都在消耗 token,也意味着写得越啰嗦,真正重要的规则越容易被忽略。
只写四类内容
- 怎么跑:启动命令、测试命令、端口
- 不能碰什么:禁改的目录、必须保留的文件
- 约定:命名、提交格式、代码风格里"不写会错"的部分
- 已知的坑:那两三个"看起来能改其实会坏"的地方
其余内容(架构说明、设计理念)写进 README,别塞进来。
长度控制在 100 行内
超过 100 行,模型开始丢失后半部分。我的实际文件在 40–60 行之间,全部是短句和命令。
一个可用的骨架
# 项目
PHP 8.5,无 Composer。入口 index.php,路由在 router.php。
# 跑起来
php -S 127.0.0.1:8090 router.php
改模板后必须 php bin/cache-clear.php
# 不要改
- content/ 下的 md 是内容,不要为了"优化"重写
- .htaccess 与 nginx.conf.example 保持同步
# 约定
- 视图里不写业务逻辑
- 新增分类要同时改 config 与 locales
# 已知的坑
- localhost:8090 会命中 Docker,必须用 127.0.0.1
- 缓存不清会看到旧页面
写"禁令"比写"建议"有效
"建议使用 PSR-12"这种话模型会忽略;"视图里不写业务逻辑"这种禁令它会遵守。原因是前者没有明确的判定标准。
把每条规则写成"可以判断对错"的句子:能验证,才会被执行。
一个维护习惯
每次模型犯了同一个错两次,就把那条规则补进去。CLAUDE.md 是长出来的,不是一次写完的。
为什么"写禁令"有效
模型对"建议"没有判定标准,对"禁令"有:不要改 content/ 是可判定的,保持代码整洁 不是。写规则时问自己一句:这条能被机器验证吗?
三个反面例子
- "注意性能"——没法验证,等于没写
- "遵循最佳实践"——模型会各自理解
- "代码要优雅"——主观词
换成:"单次查询不超过 3 次 DB 往返"、"新接口必须带超时"、"视图里不写 SQL"。
更新节奏
CLAUDE.md 不是文档,是增量补丁。每次模型犯同一个错,加一行。写了三个月后它自然收敛到几十行,全是真踩过的坑。
一句总结
写给别人看的文档求全,写给模型看的上下文求准。少而准,胜过全而糊。
再补一条经验:CLAUDE.md 里的路径写绝对路径。相对路径依赖当前工作目录,模型一旦在子目录里执行就找不到文件,然后开始瞎猜。