如何写好 CLAUDE.md
2026/7/12 23:06:45 · 更新于 2026/7/12 23:07:06
本文指导开发者如何通过撰写高质量的 CLAUDE.md 文件，为 Claude Code 等 AI 助手提供清晰的项目上下文、技术栈规范与行为边界，从而大幅提升 AI 辅助开发的准确度与效率。
CLAUDE.md 是什么
CLAUDE.md 可以理解成 Claude Code 的项目记忆文件。
它会告诉 Claude：
- 这个项目是干什么的
- 代码怎么组织
- 团队有哪些规范
- 哪些命令最常用
- 哪些事情不能做
写得好的 CLAUDE.md，会显著提升 Claude Code 的稳定性。
为什么它这么重要
因为很多“AI 不听话”的问题，根本不是模型不够聪明，而是系统没有拿到清晰的项目约束。
最推荐写进去的内容
1. 项目基本信息
- 技术栈
- 目录结构
- 关键模块
2. 开发规范
- 命名规则
- 组件风格
- 是否允许引入新依赖
3. 常用命令
- 安装命令
- 开发命令
- 构建命令
- 测试命令
4. 特别约束
- 哪些目录不要动
- 哪些文件修改要谨慎
- 提交信息风格
一个新手可直接用的模板
# 项目说明
- 这是一个 Next.js + TypeScript 项目
- 样式使用 Tailwind CSS
- 页面放在 app/ 目录
- 公共组件放在 components/ 目录
# 开发规范
- 优先复用已有组件
- 不要随意新增依赖
- 变量命名使用 camelCase
- 修改后运行 build 检查
# 常用命令
- 安装依赖：npm install
- 本地开发：npm run dev
- 生产构建：npm run build
# 注意事项
- 不要修改 legacy/ 目录
- 涉及支付逻辑时先给方案，不要直接改
写 CLAUDE.md 的一个原则
不要写废话，要写真正会影响行为的内容。
差的写法：
- 这是一个很棒的项目
- 请认真写代码
好的写法：
- 修改后必须运行
npm run build - 不允许新增依赖，除非先说明理由
- 表单组件统一复用
components/forms
小结
一句话总结：
CLAUDE.md写的不是介绍词，而是 Claude Code 在这个项目里的长期工作说明书。
写得越具体、越贴近真实约束，Claude Code 的表现就越稳定
学习地图
阶段 1：理解 CLAUDE.md 的核心价值
- 掌握核心定义：理解为什么 CLAUDE.md 是 Claude Code 的“长期项目记忆”，而非简单的项目介绍。
- 对比优劣写法：学习如何摒弃模糊的描述（如“请认真写代码”），改用具体的指令（如“修改后必须运行 npm run build”）。
阶段 2：基础框架搭建
- 梳理项目技术栈：明确列出框架（如 Next.js）、语言（TypeScript）、样式库等关键技术栈。
- 整理常用开发命令：归纳安装、本地启动、构建、测试等常用 CLI 命令，方便 AI 自主执行。
阶段 3：规则细化与边界防御
- 设定团队编码规范：说明变量命名、组件复用逻辑、以及是否允许擅自引入新依赖。
- 划定行为红线：指明哪些核心支付逻辑、遗留目录绝对不可在未经人工确认前修改。
阶段 4：动态演进与反馈微调
- 联调与日志更新：在 Claude Code 实际运行遇到瓶颈或犯错时，及时补充和修正 CLAUDE.md 中的规则，使其与项目一同成长。
动手实践——分步指南
-
初始化配置文件： 在你的项目根目录下创建一个名为
CLAUDE.md的文件。 -
配置项目技术栈与目录架构： 在文件顶部添加项目简述及目录结构，例如：
# 项目说明 - 技术栈：Next.js + Tailwind CSS + Prisma - 核心目录：页面在 `app/`，公共组件在 `components/` -
提供关键运行命令： 添加完整的指令列表，让 AI 能够自主执行环境检查与测试：
# 常用命令 - 安装：npm install - 启动：npm run dev - 测试：npm run test -
制定编码约束与红线规则： 写入具体的行为守则，约束 AI 的修改范围与代码风格：
# 开发规范 & 注意事项 - 变量与函数命名一律采用 camelCase。 - 严禁修改 `legacy/` 目录下的任何代码。 - 每次修改后，必须运行 `npm run build` 确保无编译错误。 -
启动 Claude Code 并验证效果： 在终端运行
claude命令。尝试让它修改一段代码，观察它是否能够自动读取并遵守你在CLAUDE.md中设定的规范和检查步骤，并根据实际表现不断迭代优化该文件。
三大推荐资源
- 1Anthropic Claude Code Documentation
官方关于 Claude Code 工具的完整指南，包含如何配置和使用项目上下文文件。
https://docs.anthropic.com/en/docs/agents-and-tools/claude-code
- 2GitHub - anthropics/claude-code
Claude Code 的官方 GitHub 仓库，用于获取最新发布信息与社区最佳实践。
https://github.com/anthropics/claude-code
- 3Anthropic Prompt Engineering Guide
官方提示词工程指南，深入理解如何给 Claude 制定清晰的系统提示与约束规则。
https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering
链接由 AI 推荐——使用前建议快速核实。