让 Claude 精准适配你的项目
CLAUDE.md是 Claude Code 的项目专属配置文档，核心要做到少而精、控长度、分结构，让AI精准遵循你的项目规则。
一、控制长度与定位：精简核心，拒绝冗余
- 严守长度红线
- 优先将文档控制在 100-200 行，最多不超过 300 行，每一行都必须是关键指令，删掉就可能导致 AI 出错。
- 核心定位是项目的“记忆备忘录”，只记录 AI 无法自行推测的项目特有规则，而非完整文档。
- 明确内容取舍
必须写的内容
- 常用命令：启动、构建、测试、部署等高频操作，比如
make build、npm run test。
- 目录结构：核心源码、配置、资源的存放位置，例如
src/core/存放核心模块。
- 项目特有规范：分支命名、提交格式、特殊依赖规则等。
- 踩坑与禁忌：
比如“禁止修改 config/local.yaml”“优先用构造器注入”。
- 环境适配信息：
比如“基于 Linux 4.4 + GCC 4.8.4 开发，需兼容C++11”。
不该写的内容
通用编程规范，交给 ESLint、Checkstyle 等工具即可，AI 本身熟知。
通用语法和标准，比如 C++11 基础用法、Linux基础命令。
过时信息，要定期清理，避免误导 AI。
二、优化结构与格式：清晰易读，突出重点
遵循结构逻辑（按优先级排序）
项目概览：说明技术栈、核心依赖和核心功能。
常用命令：高频操作放前面，分模块罗列。
目录结构：用列表清晰呈现核心路径。
开发规范：分支、提交、测试等项目特有的规则。
禁忌与注意事项：标注高危操作和特殊限制。
规范格式用法（极简Markdown）
标题层级：用
一级标题（项目名）、二级标题（模块）、`` 三级标题（子项）。列表优先：用无序列表
-罗列命令和规
则，有序列表1.梳理流程，避免长段落。代码块：用
bash、cpp等标注语言，包裹命令和代码，提升可读性。重点强调：对关键命令、路径、规则加粗，突出核心信息。
引用拆分：用
@文件名.md引用长文档，实现“渐进式披露”，比如@docs/api规范.md。
三、实战模板：直接套用，快速落地
C++ 项目 CLAUDE.md 模板
项目名称 - CLAUDE.md
核心环境
- 系统：Linux 4.4
- 编译器：GCC4.8.4
- 标准：C++11
- 核心依赖：[如 Boost、OpenCV版本]
常用命令
构建
- `make build` - 构建项目（兼容 GCC 4.8.4）
- `make clean` - 清理编译产物
运行
- `./bin/app` - 启动主程序
- `bashrun.sh` - 快速运行示例
目录结构
- `src/core/` - 核心业务模块（需兼容 C++11 特性）
- `src/utils/` - 工具类函数
- `config/` - 配置文件（禁止修改 `config/local.yaml`）
开发规范
- 分支命名：`feature/xxx`、`fix/xxx`
- 提交格式：`[模块] 简短描述`（如 `[core] 优化内存管理`）
- 代码风格：4 空格缩进，函数注释需包含入参和出参说明
禁忌事项
- 禁止修改 `src/const.h` 中的常量定义
- 禁止使用 C++11 以上特性（如 `std::thread` 需用底层线程库替代）
四、进阶技巧：提升管理效率
- 多文件拆分：子目录可单独存放 CLAUDE.md，按目录分层管理，遵循“就近原则”生效。
- 全局配置：个人通用偏好，比如回复风格、工具偏好，放在
~/.claude/CLAUDE.md，不影响团队协作。
- 定期维护：及时删除过期规则，更新环境和命令，保证文档时效性。
- 初始化辅助：用
/init命令让 AI 自动扫描项目，生成基础 CLAUDE.md，再按需优化调整。
五、通用补充：提升 Claude 理解质量的关键
- 明确文件用途：先区分是给 Claude 提供背景知识，还是作为提示词模板，知识库侧重静态事实，提示词侧重动态指令。
- 结构清晰简洁：合理用 Markdown 层级和分隔符，每个段落聚焦一个观点，句子简短，节省 tokens，让 Claude 抓住重点。
- 植入关键术语：围绕任务核心植入高频词汇，比如Python规范就多提 PEP 8、类型注解，帮助 Claude 快速定位上下文。
- 加入具体示例：用代码或流程示例辅助说明，Claude 擅长模仿参考，示例能大幅提升输出准确率。
- 语言精准明确：避免模糊表述，把要求量化、具体化，比如把“考虑性能”改成“确保查询响应时间 < 200ms”。
- 善用标签索引：可选XML标签标记任务、约束和示例，便于 Claude 快速提取核心信息。
- 适配知识库场景：文件名带核心关键词，开头加摘要，所有关键信息用文字表述，避免纯图片。
- 拆分长文档：若文档过长，拆分成多个聚焦主题的文件，开头加目录，用关键词索引替代全文堆砌。
- 测试迭代优化：写完后让 Claude 总结文档核心规则，根据反馈调整内容，确保文档易读、易被准确提取。
遵循这些技巧，既能让 Claude Code 精准适配你的项目，又能避免 token 浪费，大幅提升协作效率。
