041、CLAUDE.md 设计：项目级指令的自定义最佳实践

041、CLAUDE.md 设计：项目级指令的自定义最佳实践

上周五凌晨两点，我在排查一个微服务调用链的诡异超时问题。Claude Code 帮我分析了三遍日志，每次给出的修复建议都指向同一个方向——但那个方向是错的。问题出在哪？不是 Claude 不行，是我忘了在项目根目录放一个 CLAUDE.md。

那之后我花了整整两天重构了团队六个仓库的 CLAUDE.md 配置，今天把这些血泪教训写下来。

为什么 CLAUDE.md 不是可选项

很多人把 CLAUDE.md 当成一个“高级玩法”，觉得默认的 Claude Code 行为够用了。这个想法在单文件脚本项目里勉强成立，一旦进入多模块、多语言、有复杂构建流程的工程化项目，没有 CLAUDE.md 的 Claude Code 就像没有地图的导航——它能开车，但大概率把你带沟里。

我见过最典型的翻车现场：Claude 自动识别项目为 Node.js 项目，然后对着 Java 代码库建议用 npm install 修复依赖。这不是 AI 蠢，是它缺少上下文。

CLAUDE.md 本质上是一个项目级系统提示，它告诉 Claude：“别猜了，我告诉你这个项目怎么玩。”

文件放哪、叫什么

根目录，就根目录。别放 docs/ 下面，别放 .config/ 里面。Claude Code 默认从工作目录向上查找 CLAUDE.md，找到第一个就停。如果你在子目录启动 Claude