CLAUDE.md规约文档：AI编程时代的项目开发规范新范式

从传统开发规范到AI规约文档

在传统软件开发中，团队通常会在项目启动前制定一套开发规范文档，涵盖命名规范、代码风格、架构约定等内容。开发人员按照文档要求进行编码，以保证项目的一致性和可维护性。

然而，当AI编程工具（如Claude Code）介入开发流程后，这套规范需要以一种新的形式存在——那就是放置在项目根目录下的CLAUDE.md文件。这个文件不仅是给人看的，更重要的是给AI看的。Claude Code在编程时会自动读取这个规范文件，从而按照项目约定生成符合标准的代码。

Claude Code是Anthropic推出的命令行AI编程助手，它与传统的代码补全工具（如GitHub Copilot）不同，能够理解整个项目上下文并执行复杂的多文件编辑任务。CLAUDE.md的设计灵感来源于类似.editorconfig、.eslintrc等项目级配置文件的理念——通过一个约定位置的文件来声明项目规则。不同的是，CLAUDE.md使用自然语言编写，AI能够理解语义层面的约束，而不仅仅是格式化规则。这种机制本质上是Prompt Engineering在工程化场景中的落地实践，将零散的提示词固化为可版本控制的项目资产。

CLAUDE.md的核心内容结构

一个完整的CLAUDE.md规约文档通常包含以下几个核心模块：

技术栈声明

首先需要明确告诉AI当前项目使用的技术栈。以该全栈开发平台为例：

• 后端：Java + Spring Boot + MyBatis + Redis + MyBatis Plus
• 管理后台：Ant Design Pro + React 18 + TypeScript
• 移动端：uni-app
• 接口规范：RESTful API

这相当于给AI一个技术架构的全局视角，让它在生成代码时不会偏离技术选型。

技术栈声明看似简单，实际上解决了大语言模型的一个核心问题——多解歧义。以Java Web开发为例，AI可能在Spring Boot、Quarkus、Micronaut之间摇摆，在MyBatis和JPA之间犹豫。明确声明技术栈后，AI的代码生成会锁定在特定的API风格和设计模式上。例如声明使用MyBatis Plus后，AI就会使用其提供的BaseMapper、LambdaQueryWrapper等特性，而不会生成原生JDBC或JPA风格的代码。这种约束将AI的搜索空间从指数级缩小到线性级，显著提升生成代码的准确性。

后端开发规范

后端规范是CLAUDE.md文档中最细致的部分，包括：

目录规划：

• base.command：存放常用的顶级类、工具类和常量
• base.framework：安全配置、全局处理等框架级代码
• model.system：业务模块代码

代码分层约定：

• 按模块划分文件夹，每个层次采用特定后缀
• 使用公司域名作为包名前缀

核心约定：

• 接口统一返回格式
• 权限控制使用特定注解
• 持久化方式和数据库字典定义
• 异常处理规范
• 审计日志强制要求（所有接口必须加@AuditLog注解）

前端开发规范

Web端（Ant Design Pro）：

• 类型定义规范
• 权限控制方式
• 统一请求入口组件
• 弹窗组件使用规范
• 已知Bug的修复方法（这点特别重要，可以避免AI重复生成有问题的代码）

将已知Bug和修复方案写入CLAUDE.md是一种针对AI的防御性编程策略。大语言模型的训练数据存在时间截止点，对于框架的最新版本Bug、特定版本组合的兼容性问题，AI可能缺乏认知。例如Ant Design Pro某版本的ProTable组件在特定条件下存在分页状态丢失的问题，如果不在文档中标注，AI每次生成表格代码时都可能触发这个Bug。这种做法类似于传统开发中的"踩坑记录"，但面向的读者从人类变成了AI，需要用更精确的语言描述触发条件和修复方案。

移动端（uni-app）：

• UI框架选择
• 单位定义规范
• 推荐布局方式

数据库设计规范

• 每张表必须包含：id、create_time、update_time、is_deleted字段
• 基于RBAC权限模型的表结构设计
• 数据库引擎选择
• 数据字典的存储规范（指定字典表结构）

RBAC（Role-Based Access Control，基于角色的访问控制）是企业级应用中最常见的权限管理模型。其核心思想是将权限分配给角色，再将角色分配给用户，形成用户-角色-权限的三层结构。典型的RBAC表结构包括：sys_user（用户表）、sys_role（角色表）、sys_permission（权限表）、sys_user_role（用户角色关联表）、sys_role_permission（角色权限关联表）。在CLAUDE.md中声明这一模型后，AI在生成权限相关代码时会自动遵循这套表结构和查询逻辑，避免生成扁平化的权限硬编码方案。而is_deleted字段的强制要求则体现了逻辑删除的设计理念，确保AI不会生成物理删除的SQL语句，保障数据可追溯性。

交互指令与初始化序列

文档还包含一些交互指令的描述，例如安全检查（SQL注入检测）、配置验证等自动化流程。

CLAUDE.md的五大核心价值

1. 统一AI代码生成规范

人类开发者需要规范，AI同样需要。没有明确规范的情况下，AI生成代码的随意性很大，可能每次生成的风格都不一致。有了CLAUDE.md，AI编程助手就有了明确的"行为准则"，输出的代码风格和质量更加稳定。

2. 沉淀项目核心文档

以往项目文档零散分布在各处，交付时需要重新整理。CLAUDE.md将核心规范集中在一个文件中，既是AI的指导文件，也是项目的核心技术文档，一举两得。

3. 明确AI的上下文边界

这是CLAUDE.md最关键的作用——告诉AI：我们用什么技术、需要符合哪些规范、遇到特定Bug如何修复。这大大减少了AI"猜测"的空间，提高了代码生成的准确性和可用性。

4. 设定业务边界和禁止项

文档中可以明确写出"禁止做的事情"，AI读取后就不会朝那个方向发展。这相当于给AI划定了一个安全的操作范围，避免生成不符合业务要求的代码。

5. 降低上手成本与提升工程效率

新成员加入项目时，通过阅读CLAUDE.md可以快速了解项目架构和技术约定。同时，配合Claude Code可以一键生成符合规范的接口、实体等代码，大幅提升开发效率。

CLAUDE.md编写实践建议

如果你也在使用Claude Code或类似的AI编程工具，以下是编写规约文档的实践建议：

1. 尽早建立CLAUDE.md：在项目初始化阶段就创建，而不是事后补充
2. 持续迭代更新：随着项目演进，不断补充新的规范和已知问题的解决方案
3. 包含具体代码示例：不仅写规则，还要写示例代码，AI理解起来更准确
4. 记录Bug修复方案：将AI容易犯的错误和修复方法写入文档，避免重复踩坑
5. 明确禁止项：清晰列出不允许的做法，比模糊的"建议"更有效

CLAUDE.md的本质是将Prompt Engineering从一次性的对话行为转变为可持续维护的工程实践。传统的AI提示词存在于聊天窗口中，无法复用、无法协作、无法追溯变更历史。而CLAUDE.md作为项目文件，天然纳入Git版本控制体系，团队成员可以通过Pull Request来审查和迭代规约内容。这意味着AI的"行为配置"获得了与业务代码同等的工程化管理能力，包括变更追踪、分支管理、代码审查和回滚机制。当团队发现AI在某个场景下反复生成不理想的代码时，可以像修复Bug一样提交一个规约补丁，所有后续的AI交互都会立即受益。

总结

CLAUDE.md本质上是传统开发规范文档在AI编程时代的进化形态。它不仅服务于人类开发者，更重要的是作为AI编程助手的"行为指南"。通过一份结构清晰、内容完整的规约文档，可以让Claude Code等AI工具生成的代码更加规范、一致，真正实现人机协作的高效开发模式。

核心要点

• CLAUDE.md是AI编程时代的项目规约文档，放置在项目根目录供Claude Code自动读取
• 文档涵盖技术栈声明、前后端开发规范、数据库设计规范、交互指令等核心模块
• 其核心价值在于统一AI生成代码的规范、明确上下文、设定业务边界和禁止项
• 将已知Bug修复方案写入文档可避免AI重复生成有问题的代码
• CLAUDE.md同时服务于AI和人类开发者，既是编程指南也是项目文档沉淀