CLAUDE.md配置指南：六段式结构写好项目说明书

什么是 CLAUDE.md？

CLAUDE.md 是一个放在项目根目录下的 Markdown 文件。每次打开 Claude Code，它会自动读取这个文件，按照你写的内容来理解整个项目。

它不是配置文件，也不是代码，更不是一份文档——它是一份精炼的项目说明书，告诉 Claude 你的项目是什么、怎么做、有什么规矩。

关键点在于：每一次 Claude Code 向大模型发出请求时，上下文里都会携带 CLAUDE.md 的全部内容。要理解这背后的原因，需要了解大语言模型的「上下文窗口」（Context Window）机制——模型每次只能「看到」当前请求携带的所有文本，包括系统提示、对话历史、代码文件以及 CLAUDE.md 的内容。Token 是大模型处理文本的基本计量单位，大约每 750 个英文单词或 500 个中文字符对应 1000 个 Token，上下文窗口有总量上限，Token 消耗越多，推理成本越高、响应速度越慢。正因如此，Anthropic 官方建议这个文件不要超过 200 行，在信息完整性与 Token 效率之间取得平衡，尽量精炼，只写必要信息。

为什么需要 CLAUDE.md？

CLAUDE.md 本质上是一种结构化的「系统提示」（System Prompt）实践。系统提示是提示工程（Prompt Engineering）中的核心概念，指在对话开始前预先注入的背景指令，用于约束模型的行为边界、角色定位和输出风格。与普通对话提示不同，系统提示具有持久性——它在整个会话周期内始终生效。CLAUDE.md 将这一机制固化到文件层面，使得每个项目都拥有专属的「系统提示模板」，与软件工程中「约定优于配置」（Convention over Configuration）的设计哲学高度吻合。

在实际的软件工程中，有许多和业务功能无关、但又非常重要的项目知识，比如：

Git 分支命名规则：用 feature/、release/ 还是 dev/？
函数命名风格：驼峰命名还是下划线？
表名规范：用 t_ 前缀还是直接命名？
版本迭代的数字规律是怎样的？
代码架构的分层又是怎样的？

这些规则如果不提前统一整合，在用 Claude Code 开发的过程中就会花很多额外精力去纠正和统一。比如开发完成后，每次都要让它重新一个个去改正命名、调整结构，效率大打折扣。

Anthropic 正是为了解决这个问题，设计了 CLAUDE.md 机制——把规则提前定制好，减少摩擦消耗，提升开发效率。

CLAUDE.md 的六段式结构

一个完整的 CLAUDE.md 可以归纳为三句话：你要做什么、用什么做、怎么做。具体展开为以下六个段落：

第一段：项目概述

写项目名，加上一句话说清楚这个项目是干什么的。Claude Code 读完之后就知道它是要做一个网页，而不是后端服务。简洁明了，一两行足矣。

项目概述示例

第二段：功能要求

用短线列出功能点，每一条写清楚用户能做什么。这是 CLAUDE.md 里最重要的一段，因为你的产品想法、功能需求全部都在这里。Claude Code 读完这一段，生成代码时会主动检查有没有漏掉关键功能。

当产品迭代到功能要求很多的时候，可以把详细版单独放一个文件，比如 docs/需求文档.md 或 docs/prd.md，然后用 @ 引用的方式渐进式引入：

## 功能要求
@docs/prd.md

这种 @ 引用语法是一种「渐进式上下文加载」策略，类似于编程语言中的模块导入机制。其设计思路与 RAG（检索增强生成）技术的核心理念相通——不是把所有知识塞给模型，而是在正确的时机提供正确的信息，从而在保持模型响应质量的同时控制 Token 消耗。在 CLAUDE.md 里只保留最核心的三五条功能要点即可。

第三段：技术栈

告诉大模型用什么工具。干货原则：只写用什么，不写为什么用。 如果不写这一段，大模型会自动选择它训练数据中出现概率最高的技术组合——由于模型在训练阶段从 GitHub 等海量代码库中学习，对「主流写法」有强烈的统计偏好，这往往不是你想要的特定技术选型。

技术栈配置示例

第四段：项目目录结构

告诉大模型文件放在哪里，每个文件夹管什么。清晰的目录结构能让 Claude Code 在生成新文件时自动放到正确的位置，避免项目结构混乱。

第五段：代码规范

告诉大模型怎么写代码，写你的个人偏好和默认习惯即可。例如：

所有变量用 const，需要改动的用 let，禁用 var
函数名用驼峰命名而非下划线，描述动作，如 addTask

这里有一个重要原则：Claude 本身已经是一个合格的代码开发者，你只需要告诉它你最在乎的那几条。不需要把所有代码规范都列出来，因为它懂基本的代码规范。代码规范段落的核心价值在于「纠偏」——大语言模型对训练数据中的主流写法有统计偏好，当你的项目有非主流偏好（如特定的命名前缀、非标准的文件组织方式）时，必须在此显式声明，否则模型会用「多数派」写法覆盖你的习惯。你要写的是你的特殊偏好——比如不喜欢在命名中使用某个词，或者有特定的注释风格要求。

代码规范示例

第六段：约束条件

告诉大模型在生成代码时不能用什么、可以用什么，以及硬性限制。比如：

单文件 index.html 不能超过 300 行
禁止使用某些第三方库
必须兼容特定浏览器版本

实际效果与最佳实践

按照上述六段式结构写出来的 CLAUDE.md，总共大约只有 38 行，非常精炼。

整个文件的核心逻辑可以浓缩为三句话：

维度	对应段落	核心问题
你要做什么	项目概述 + 功能要求	产品定义
用什么做	技术栈 + 目录结构	技术选型
怎么做	代码规范 + 约束条件	执行标准

写好 CLAUDE.md 之后，Claude Code 会从一个通用助手变成一个按照你的规矩、按照你的习惯干活的专用助手。它理解你的项目背景，遵循你的编码风格，知道文件该放哪里、代码该怎么写。

总结

CLAUDE.md 是使用 Claude Code 进行项目开发时的「地基」文件。它的价值不在于写得多详细，而在于写得多精准。200 行以内，六个段落，把项目最核心的约定讲清楚，就能显著减少开发过程中的沟通成本和返工次数。

对于刚开始使用 Claude Code 的开发者，建议从这个六段式模板开始，在实际使用中根据项目需要逐步调整和优化。记住：CLAUDE.md 不是写给人看的文档，而是写给 AI 看的项目说明书，用最少的文字传递最关键的信息。

核心要点

CLAUDE.md 是放在项目根目录的说明书文件，每次 Claude Code 请求时都会携带其全部内容，官方建议不超过 200 行
六段式结构：项目概述、功能要求、技术栈、目录结构、代码规范、约束条件，核心逻辑是「做什么、用什么做、怎么做」
功能要求是最重要的段落，当需求增多时可通过 @ 引用外部文档实现渐进式上下文加载，控制 Token 消耗
代码规范只需写个人偏好和特殊要求，核心作用是「纠偏」——覆盖模型对训练数据主流写法的统计偏好
写好 CLAUDE.md 能将 Claude Code 从通用助手转变为遵循项目规则的专用助手，显著减少返工成本