AI 工具与出海建站的账本。

首页 / 工作流与 MCP / CLAUDE.md 该怎么写:把项目常识交给模型

CLAUDE.md 该怎么写:把项目常识交给模型

它不是文档,是一份"每次对话都会重新读一遍的上下文"。写太长等于没写。

2026年10月3日 6 分钟读完 naket.top 更新 2026-10-09
CLAUDE.md 该怎么写:把项目常识交给模型

CLAUDE.md 会在每次会话开始时被读进上下文。这意味着它的每一行都在消耗 token,也意味着写得越啰嗦,真正重要的规则越容易被忽略。

只写四类内容

  1. 怎么跑:启动命令、测试命令、端口
  2. 不能碰什么:禁改的目录、必须保留的文件
  3. 约定:命名、提交格式、代码风格里"不写会错"的部分
  4. 已知的坑:那两三个"看起来能改其实会坏"的地方

其余内容(架构说明、设计理念)写进 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 里的路径写绝对路径。相对路径依赖当前工作目录,模型一旦在子目录里执行就找不到文件,然后开始瞎猜。

CLAUDE.md上下文工程习惯

延伸阅读

Claude Code 文档 ↗