1. 项目概述Claude.md 到底是什么如果你最近在折腾 AI 编程助手比如 Cursor、Claude Code 或者 Codeium那你大概率已经不止一次在社区里看到过Claude.md或者.cursorrules这类文件的名字了。它们被传得神乎其神仿佛有了它你的 AI 助手就能从“人工智障”秒变“贴心导师”写出来的代码质量直线上升。但说真的我第一次看到Claude.md这个名字时也是一头雾水这玩意儿到底是啥一个 Markdown 文件能有这么大魔力简单来说Claude.md是一个语义配置文件。你可以把它理解为你和 AI 助手之间的一份“入职培训手册”或者“项目背景说明书”。在没有这份文件之前AI 助手就像一个刚入职的新人对你的项目背景、技术栈、编码风格、甚至是你的个人偏好都一无所知。它只能基于它那庞大的、通用的训练数据来生成代码结果就是它可能会用你不喜欢的代码风格、引入你项目里不用的库、或者写出完全不符合你业务逻辑的“教科书式”代码。而Claude.md的作用就是把这些信息“喂”给 AI。通过在这个纯文本文件里清晰地定义规则、约束、上下文和偏好你相当于给 AI 助手划定了工作范围和行事准则。它不再是漫无目的地“自由发挥”而是变成了一个深度理解你项目需求的“定制化协作者”。所以说它能“让你的 AI 助手乖乖听你的话”一点也不夸张。这本质上是一种提示工程Prompt Engineering的工程化实践把零散、临时的对话指令沉淀为一份可维护、可复用的核心配置文件。2. 核心需求解析我们为什么需要 Claude.md你可能会想我在聊天框里直接告诉 AI 我的要求不就行了何必多此一举搞个文件在实际高强度使用 AI 编程几个月后我发现了几个必须用配置文件解决的痛点2.1 解决“上下文失忆”问题AI 助手的对话上下文是有限的。无论是 Claude 的 200K 上下文还是 GPT-4 的 128K在复杂的、多文件的项目中你很难在每次提问时都把相关的项目结构、依赖关系、历史决策重新描述一遍。Claude.md作为一个被优先读取的“永久上下文”确保了 AI 在回答每一个问题时都建立在对你项目的基础认知之上不会出现“五分钟前刚说过现在就忘了”的尴尬。2.2 统一与固化最佳实践每个人、每个团队都有自己偏好的代码风格如命名规范、缩进、注释习惯、架构模式如目录结构、分层设计和规避的“坏味道”如禁止使用某些已废弃的 API。通过Claude.md你可以将这些团队共识或个人经验固化下来。AI 生成的每一行代码都会自动遵循这些规则极大地减少了后续人工 review 和调整的时间保证了代码库风格的一致性。2.3 提升复杂任务的完成度对于一些需要深度理解项目背景的复杂任务比如“在现有用户服务中添加一个通过手机号验证码登录的功能”AI 需要知道你的项目是 Spring Boot 还是 Django用户模型定义在哪里数据库用的是 MySQL 还是 MongoDB有没有现成的短信服务接口验证码是存 Redis 吗这些信息如果每次都要你口述效率极低。而一个配置完善的Claude.md能在任务开始前就提供这些关键上下文让 AI 直接产出可用的、贴合现有架构的代码甚至能主动提醒你“根据配置我们项目的验证码通常存储在 Redis 中键名格式是captcha:{phone}过期时间是 300 秒需要我为你生成相应的服务层代码吗”2.4 实现配置的复用与共享对于团队协作Claude.md可以提交到代码仓库中。新成员配置好 AI 助手后立刻就能获得与团队一致的 AI 协作体验快速上手项目规范。对于个人开发者你也可以为不同类型的项目如前端 React 项目、后端 Go 微服务、数据分析 Python 脚本创建不同的配置模板切换项目时无需重新调教 AI。3. 核心细节解析Claude.md 里到底写什么Claude.md没有官方的、严格的格式标准这既是它的灵活性所在也是初学者感到困惑的地方。根据社区实践和我的使用经验一份高效的Claude.md通常包含以下几个核心模块你可以把它们看作一份“说明书”的目录。3.1 项目元信息与全局设定这部分是 AI 理解你项目的“第一印象”。它应该简明扼要地定义项目最基础的信息。# 项目配置Claude.md ## 项目概述 - **项目名称**电商平台后端服务 - **核心描述**这是一个基于 Spring Boot 3.x 和 Vue 3 的前后端分离电商系统包含用户、商品、订单、支付等模块。 - **主要技术栈** - 后端Java 17, Spring Boot 3.1.5, MyBatis-Plus, MySQL 8.0, Redis 7, RabbitMQ - 前端Vue 3.3, TypeScript, Element Plus, Vite - **代码仓库结构简述**/src/main/java/com/ecommerce/ ├── controller/ # RESTful API 接口层 ├── service/ # 业务逻辑层 ├── mapper/ # 数据访问层MyBatis └── model/ # 数据实体层 /src/main/resources/ ├── application.yml # 主配置文件 └── mapper/ # MyBatis XML 文件为什么这么写明确的名称和描述让 AI 对项目有个定性认识。列出技术栈能防止 AI 推荐或使用错误的技术比如在 Spring Boot 项目里写 Django 的代码。简述结构帮助 AI 在生成代码时能准确地将文件放到正确的目录下。3.2 代码风格与规范约束这是让 AI 产出代码“像你写的一样”的关键。你需要把那些你会在 Code Review 里反复强调的规则写进去。## 代码风格与规范 ### 通用原则 1. **KISS DRY**保持简单避免重复。如果发现重复逻辑优先考虑提取为公共方法或工具类。 2. **防御式编程**对输入参数进行有效性校验特别是 Controller 层使用 Objects.requireNonNull 或自定义断言。 3. **优先使用现代 Java 特性**如 Records 表示纯数据类Stream API 进行集合操作Optional 避免空指针。 ### 格式与命名 - **缩进**使用 4 个空格严禁使用 Tab。 - **命名规范** - 类名大驼峰如 UserService - 方法/变量名小驼峰如 getUserById - 常量全大写下划线如 MAX_RETRY_COUNT - 包名全小写使用公司域名倒序如 com.ecommerce.user - **注释要求** - 公共 APIController、Service 接口必须使用 Javadoc。 - 复杂的业务逻辑需添加行内注释解释“为什么这么做”而不是“做了什么”。 - **禁止**无意义的注释如 // 获取用户 放在 getUser() 方法上。 ### 项目特定约定 - **API 响应**统一使用 CommonResultT 包装类包含 code, message, data 字段。 - **异常处理**业务异常使用 BusinessException 抛出在全局异常处理器 GlobalExceptionHandler 中捕获并转换为 CommonResult。 - **数据库实体**所有实体类必须继承 BaseEntity包含 id, createTime, updateTime 字段。 - **日志记录**使用 Slf4j 注解在关键业务步骤、异常捕获处记录 INFO 或 ERROR 级别日志。实操心得这部分规则不是一蹴而就的。我的建议是在最初期你可以只写几条你最在意的规则比如命名规范、API响应格式。然后在接下来的几天里每当 AI 生成的代码有不符合你习惯的地方你就把这条规则补充到Claude.md里。几周下来这份配置就会变得非常强大和个性化。3.3 架构模式与设计模式指引对于稍具规模的项目让 AI 理解你的架构决策至关重要这能保证新代码与旧系统和谐共处。## 架构与设计模式 ### 分层架构 本项目严格遵循 Controller-Service-Mapper 三层架构。 - **Controller 层**只负责接收请求、参数校验、调用 Service、返回封装结果。**禁止**在 Controller 中包含任何业务逻辑。 - **Service 层**核心业务逻辑所在地。接口定义在 XxxService实现在 XxxServiceImpl。 - **Mapper 层**仅负责数据库 CRUD 操作。使用 MyBatis-Plus 提供的 BaseMapper简单查询直接使用其方法复杂查询在 XML 中编写。 ### 常用设计模式场景 - **策略模式**用于不同的支付方式支付宝、微信支付。 - **工厂模式**用于根据商品类型创建不同的运费计算器。 - **观察者模式**用于订单状态变更时通知库存、物流、用户积分等模块。 ### 依赖注入 - 统一使用 Autowired 进行构造器注入以保证依赖不可变和便于测试。 - **示例** java Service public class UserServiceImpl implements UserService { private final UserMapper userMapper; Autowired public UserServiceImpl(UserMapper userMapper) { this.userMapper userMapper; } }### 3.4 外部依赖与工具库说明 告诉 AI 你项目中已经存在哪些“轮子”避免它重复造轮子或引入不兼容的库。 markdown ## 依赖与工具库 ### 核心依赖 - **数据访问**mybatis-plus-boot-starter (版本 3.5.4)。**注意**已配置逻辑删除TableLogic和自动填充MetaObjectHandler。 - **缓存**使用 spring-boot-starter-data-redis键名统一使用冒号分隔如 user:info:{userId}。 - **JSON 处理**使用 Jackson已在配置中设置日期格式为 yyyy-MM-dd HH:mm:ss。 ### 工具类 - **验证**使用 org.springframework.util.Assert 进行参数断言。 - **集合操作**优先使用 com.google.common.collect.Lists/Maps (Guava)。 - **对象转换**使用 org.mapstruct.Mapper 进行 DTO/Entity 转换而非手动 set/get。 - **已禁用**本项目不使用 Apache Commons Lang3 的 StringUtils请使用 org.springframework.util.StringUtils。注意明确“已禁用”的库非常重要。我曾遇到过 AI 在工具方法中引入了Apache Commons而我们的项目用的是 Guava导致不必要的依赖冲突清理起来很麻烦。3.5 提示词模板与交互偏好这是高阶用法用于定义你希望 AI 以何种“性格”或“流程”与你协作。## 交互与协作偏好 ### 角色设定 请你扮演一个经验丰富的 Java 后端架构师同时也是这个项目的核心开发成员。你深刻理解上述所有规范并致力于产出生产级可用的代码。 ### 响应格式偏好 1. **先思考后输出**对于复杂任务可以先给出一个简要的实现思路或步骤经我确认后再生成具体代码。 2. **代码优先**响应应以代码块为主解释性文字尽量精简放在代码块之前或之后。 3. **保持原子性**每次聚焦于一个明确的、可完成的小功能或修改。如果任务很大请主动将其拆解为多个步骤。 ### 安全检查 - 在生成任何涉及数据库查询的代码时请主动考虑 SQL 注入风险并使用 QueryWrapper 或 XML 中带 #{} 的参数绑定。 - 在生成文件操作、网络请求代码时请提醒我添加必要的异常处理和资源关闭逻辑。4. 实操过程如何创建并应用你的 Claude.md理论说了这么多我们来点实际的。下面我将以在 VSCode 中使用 Claude Code 插件为例展示从零开始创建和应用Claude.md的完整流程。4.1 环境准备与插件安装首先你需要在你的 IDE 中安装一个支持读取配置文件的 AI 编程助手插件。目前主流的有Claude CodeAnthropic 官方插件对Claude.md支持最原生。Cursor内置了 Claude 模型使用.cursorrules文件与Claude.md作用相同语法类似。Codeium、Bito等部分支持类似功能。这里以 Claude Code 为例打开 VSCode进入扩展市场 (CtrlShiftX)。搜索 “Claude Code” 并安装。安装后侧边栏会出现 Claude 的图标。你需要登录你的 Claude 账户通常需要国际网络环境请注意合规使用。确保插件已激活。你可以通过快捷键CmdK(Mac) 或CtrlK(Windows/Linux) 唤出 Claude 的聊天界面进行测试。4.2 创建并编写 Claude.md 文件定位文件在你的项目根目录下创建一个名为Claude.md的纯文本文件。是的名字就是Claude.md注意大小写。对于 Cursor文件名叫.cursorrules。初始内容不要试图一次性写完美。从一个最简单的版本开始。打开Claude.md先写入项目最核心的元信息和一两条你最在乎的代码规范。# 项目配置Claude.md ## 项目概述 - **项目名称**我的个人博客系统 - **技术栈**Node.js, Express, MongoDB, React (Next.js) ## 核心编码规范 - 使用 ES6 语法优先使用 const 和 let避免 var。 - API 路由遵循 RESTful 风格使用复数名词如 /api/articles。渐进式完善接下来的一周在以下场景中补充你的Claude.md场景AAI 生成的函数命名是get_data但你想要小驼峰getData。将这条命名规则加入配置文件。场景BAI 在 Express 路由里写了回调函数但你的项目全部使用async/await。将这条异步处理规范加入配置文件。场景CAI 建议安装axios发请求但你一直在用fetch。在配置文件中注明“前端请求统一使用原生fetch无需axios”。场景D你发现 AI 总是忘记校验用户输入。在配置文件的“通用原则”里加上“所有 API 端点必须对输入参数进行有效性校验”。4.3 验证配置是否生效编写完配置文件后最关键的一步是验证它是否被 AI 正确读取和理解。直接提问测试在 Claude Code 的聊天框中问一个与配置相关的问题。例如如果你的配置里强调了“使用const/let”你可以问“请帮我写一个遍历数组并打印的示例。” 观察生成的代码是否使用了const或let而不是var。上下文关联测试问一个需要结合项目背景的问题。例如根据上面的博客配置你可以问“我想新增一个‘文章评论’的功能后端需要怎么设计” 一个生效的配置应该能让 AI 的回答包含“根据您的技术栈我们需要在 Express 中创建一个新的路由文件commentRoutes.js连接到 MongoDB 的comments集合并遵循 RESTful 风格设计 POST/api/comments和 GET/api/articles/:id/comments等接口。”观察系统提示一些高级的 AI 助手会在你打开项目时在后台信息或日志里显示“已加载配置文件Claude.md”之类的提示。留意这些信息。我的踩坑经验配置文件不生效最常见的原因有两个。一是文件不在项目根目录二是文件名称拼写错误比如写成了claude.md或Claude.MD。请务必检查这两点。另外有些插件可能需要重启 IDE 或重新加载窗口才能识别新创建的配置文件。5. 高级技巧与场景化配置当你掌握了基础配置后可以尝试一些更高级的用法让Claude.md的威力倍增。5.1 模块化配置为子目录定制规则大型项目往往包含多个模块每个模块可能有细微的规范差异。你可以在子目录下创建额外的Claude.md文件其规则会覆盖或补充根目录的配置。/my-project ├── Claude.md # 全局配置 ├── /backend │ ├── Claude.md # 后端专用配置强调 Java 规范、Spring 注解 │ └── /src └── /frontend ├── Claude.md # 前端专用配置强调 React Hooks 使用、CSS-in-JS 方案 └── /src在/backend/Claude.md中你可以写# 后端模块配置 **此配置继承并覆盖根目录配置。** - 本模块所有代码文件必须包含 author 标签的类级别 Javadoc。 - 单元测试使用 JUnit 5 和 Mockito测试类命名格式为 *Test。 - 配置文件统一使用 application-{env}.yml 格式。这样当你在backend目录下工作时AI 会同时应用全局和本地的规则。5.2 动态上下文注入链接到重要文档Claude.md本身不宜过长否则会影响 AI 处理主要任务的上下文窗口。对于非常详细的 API 文档、架构设计图、协议说明等你可以采用“链接”的方式。## 重要参考文档 在回答涉及以下领域的问题时请务必参考对应文档 - **数据库设计**详见 /docs/database-schema.md - **第三方支付接口协议**详见 /docs/payment-api-v2.md - **微服务间通信规范**详见 /docs/service-communication.md虽然目前的 AI 插件不一定能主动读取这些链接文件但当你提出相关问题时你可以手动将这些文件内容粘贴到对话中并提醒 AI“这是我们的数据库设计文档请基于此为我生成实体类。” 而Claude.md的作用是提醒你——也间接提醒 AI——这些关键资源的存在。5.3 针对不同任务的“技能”配置你可以创建多个“技能”片段在需要时快速激活。例如在Claude.md末尾添加## 技能片段 ### [代码审查模式] 当我要求进行代码审查时请按以下维度分析 1. **代码风格**是否符合本项目命名、格式规范 2. **潜在缺陷**有无空指针、资源未关闭、线程安全、SQL 注入风险 3. **性能**有无低效循环、重复查询、内存泄漏可能 4. **可读性**逻辑是否清晰注释是否恰当 5. **改进建议**提供具体的、可选的优化方案。 ### [编写单元测试模式] 当需要编写单元测试时请遵循 1. 测试类名被测试类名 Test 2. 使用 Given-When-Then 结构。 3. 覆盖正常流程和主要异常分支。 4. Mock 对象行为设置清晰。当你想让 AI 切换模式时只需在聊天中说“请切换到「代码审查模式」帮我看看这段代码。” 然后粘贴代码即可。6. 常见问题与排查技巧实录在实际使用中你肯定会遇到各种问题。下面是我和社区里总结的一些常见坑点及解决方案。6.1 配置文件不生效或部分不生效症状AI 生成的代码完全无视Claude.md中的规则。排查步骤检查文件位置与名称确保文件在项目根目录且名称完全正确Claude.md。检查插件状态确认 Claude Code 或 Cursor 插件已正确安装、登录并激活。尝试在 IDE 内重启插件或重新加载窗口。简化测试创建一个全新的、极简的Claude.md只写一条非常独特的规则例如“所有变量名必须包含前缀my_”然后让 AI 生成一个简单变量看是否遵守。查看插件日志有些插件有输出通道Output Channel里面可能有加载配置文件的日志或错误信息。6.2 AI 似乎“理解”了配置但执行有偏差症状AI 在对话中承认看到了你的配置但生成的代码还是不符合要求。原因与解决规则冲突或模糊你的规则可能和其他隐含规则冲突或者表述不够精确。例如“使用清晰的命名”就不如“方法名必须使用动词开头如getUser,calculateTotal”明确。上下文优先级有时你当前打开的单个文件内容或最近的对话历史会对 AI 产生比Claude.md更强的即时影响。尝试开启一个新的聊天会话并首先提问“请先阅读项目根目录下的Claude.md配置文件然后我们再开始。”模型限制不同的 AI 模型对指令的遵循能力不同。Claude 3.5 Sonnet 通常比 Claude 3 Haiku 表现更好。确保你在插件设置中选择了能力更强的模型。6.3 如何平衡配置文件的详细程度问题写得太简略没效果写得太详细又怕占用太多上下文影响 AI 处理主要任务。我的经验核心优先优先编写那些一旦违反就需要大量返工的规则如项目结构、核心依赖、API 响应格式、全局异常处理。渐进式细化从 10 条最重要的规则开始随着合作中发现问题再添加。一个 50-100 行、重点突出的配置文件远比一个 500 行面面俱到的文件有效。使用注释在配置文件中用!-- 注释 --或# 注释来分隔模块和解释复杂规则这不会增加 AI 的理解负担但能让你自己维护起来更清晰。定期回顾每隔一段时间回顾一下配置文件将那些 AI 已经很好掌握的规则适当简化或者将很少触发的规则移到次要位置。6.4 团队协作时如何管理统一的 Claude.md挑战团队成员各有偏好如何形成一份公认的配置解决方案建立基线由技术负责人或架构师起草一份最基础的、关于技术栈和核心架构的配置作为不可争议的基线。代码风格自动化将诸如缩进、命名、导入排序等风格问题交给Prettier、ESLint、Checkstyle等工具自动化处理。在Claude.md中只需写明“代码格式已由 Prettier 统一管理生成代码后请运行格式化命令。”流程化将Claude.md纳入代码仓库管理。任何修改都需要通过 Pull Request 和团队其他成员 review确保变更合理且被广泛接受。个性化扩展允许开发者在自己的本地或项目子目录下创建个人扩展配置如.claude.local.md用于存放个人偏好的代码片段或提示词但该文件不应提交到仓库且其规则不能与团队主配置冲突。经过几个月的实践我个人的体会是Claude.md的价值不在于一蹴而就的完美而在于它是一个持续演进的、人与 AI 之间的协作契约。它开始可能只有寥寥数行但每当你发现一个可以固化下来的经验或规避一个重复的解释它就增长一点。最终它会成为你项目知识库中一个极具价值的资产让 AI 助手真正变成一个深度理解你工作习惯和项目背景的“老搭档”。花点时间配置它绝对是一笔回报率超高的投资。
AI编程助手配置指南：Claude.md文件的作用与实战应用
1. 项目概述Claude.md 到底是什么如果你最近在折腾 AI 编程助手比如 Cursor、Claude Code 或者 Codeium那你大概率已经不止一次在社区里看到过Claude.md或者.cursorrules这类文件的名字了。它们被传得神乎其神仿佛有了它你的 AI 助手就能从“人工智障”秒变“贴心导师”写出来的代码质量直线上升。但说真的我第一次看到Claude.md这个名字时也是一头雾水这玩意儿到底是啥一个 Markdown 文件能有这么大魔力简单来说Claude.md是一个语义配置文件。你可以把它理解为你和 AI 助手之间的一份“入职培训手册”或者“项目背景说明书”。在没有这份文件之前AI 助手就像一个刚入职的新人对你的项目背景、技术栈、编码风格、甚至是你的个人偏好都一无所知。它只能基于它那庞大的、通用的训练数据来生成代码结果就是它可能会用你不喜欢的代码风格、引入你项目里不用的库、或者写出完全不符合你业务逻辑的“教科书式”代码。而Claude.md的作用就是把这些信息“喂”给 AI。通过在这个纯文本文件里清晰地定义规则、约束、上下文和偏好你相当于给 AI 助手划定了工作范围和行事准则。它不再是漫无目的地“自由发挥”而是变成了一个深度理解你项目需求的“定制化协作者”。所以说它能“让你的 AI 助手乖乖听你的话”一点也不夸张。这本质上是一种提示工程Prompt Engineering的工程化实践把零散、临时的对话指令沉淀为一份可维护、可复用的核心配置文件。2. 核心需求解析我们为什么需要 Claude.md你可能会想我在聊天框里直接告诉 AI 我的要求不就行了何必多此一举搞个文件在实际高强度使用 AI 编程几个月后我发现了几个必须用配置文件解决的痛点2.1 解决“上下文失忆”问题AI 助手的对话上下文是有限的。无论是 Claude 的 200K 上下文还是 GPT-4 的 128K在复杂的、多文件的项目中你很难在每次提问时都把相关的项目结构、依赖关系、历史决策重新描述一遍。Claude.md作为一个被优先读取的“永久上下文”确保了 AI 在回答每一个问题时都建立在对你项目的基础认知之上不会出现“五分钟前刚说过现在就忘了”的尴尬。2.2 统一与固化最佳实践每个人、每个团队都有自己偏好的代码风格如命名规范、缩进、注释习惯、架构模式如目录结构、分层设计和规避的“坏味道”如禁止使用某些已废弃的 API。通过Claude.md你可以将这些团队共识或个人经验固化下来。AI 生成的每一行代码都会自动遵循这些规则极大地减少了后续人工 review 和调整的时间保证了代码库风格的一致性。2.3 提升复杂任务的完成度对于一些需要深度理解项目背景的复杂任务比如“在现有用户服务中添加一个通过手机号验证码登录的功能”AI 需要知道你的项目是 Spring Boot 还是 Django用户模型定义在哪里数据库用的是 MySQL 还是 MongoDB有没有现成的短信服务接口验证码是存 Redis 吗这些信息如果每次都要你口述效率极低。而一个配置完善的Claude.md能在任务开始前就提供这些关键上下文让 AI 直接产出可用的、贴合现有架构的代码甚至能主动提醒你“根据配置我们项目的验证码通常存储在 Redis 中键名格式是captcha:{phone}过期时间是 300 秒需要我为你生成相应的服务层代码吗”2.4 实现配置的复用与共享对于团队协作Claude.md可以提交到代码仓库中。新成员配置好 AI 助手后立刻就能获得与团队一致的 AI 协作体验快速上手项目规范。对于个人开发者你也可以为不同类型的项目如前端 React 项目、后端 Go 微服务、数据分析 Python 脚本创建不同的配置模板切换项目时无需重新调教 AI。3. 核心细节解析Claude.md 里到底写什么Claude.md没有官方的、严格的格式标准这既是它的灵活性所在也是初学者感到困惑的地方。根据社区实践和我的使用经验一份高效的Claude.md通常包含以下几个核心模块你可以把它们看作一份“说明书”的目录。3.1 项目元信息与全局设定这部分是 AI 理解你项目的“第一印象”。它应该简明扼要地定义项目最基础的信息。# 项目配置Claude.md ## 项目概述 - **项目名称**电商平台后端服务 - **核心描述**这是一个基于 Spring Boot 3.x 和 Vue 3 的前后端分离电商系统包含用户、商品、订单、支付等模块。 - **主要技术栈** - 后端Java 17, Spring Boot 3.1.5, MyBatis-Plus, MySQL 8.0, Redis 7, RabbitMQ - 前端Vue 3.3, TypeScript, Element Plus, Vite - **代码仓库结构简述**/src/main/java/com/ecommerce/ ├── controller/ # RESTful API 接口层 ├── service/ # 业务逻辑层 ├── mapper/ # 数据访问层MyBatis └── model/ # 数据实体层 /src/main/resources/ ├── application.yml # 主配置文件 └── mapper/ # MyBatis XML 文件为什么这么写明确的名称和描述让 AI 对项目有个定性认识。列出技术栈能防止 AI 推荐或使用错误的技术比如在 Spring Boot 项目里写 Django 的代码。简述结构帮助 AI 在生成代码时能准确地将文件放到正确的目录下。3.2 代码风格与规范约束这是让 AI 产出代码“像你写的一样”的关键。你需要把那些你会在 Code Review 里反复强调的规则写进去。## 代码风格与规范 ### 通用原则 1. **KISS DRY**保持简单避免重复。如果发现重复逻辑优先考虑提取为公共方法或工具类。 2. **防御式编程**对输入参数进行有效性校验特别是 Controller 层使用 Objects.requireNonNull 或自定义断言。 3. **优先使用现代 Java 特性**如 Records 表示纯数据类Stream API 进行集合操作Optional 避免空指针。 ### 格式与命名 - **缩进**使用 4 个空格严禁使用 Tab。 - **命名规范** - 类名大驼峰如 UserService - 方法/变量名小驼峰如 getUserById - 常量全大写下划线如 MAX_RETRY_COUNT - 包名全小写使用公司域名倒序如 com.ecommerce.user - **注释要求** - 公共 APIController、Service 接口必须使用 Javadoc。 - 复杂的业务逻辑需添加行内注释解释“为什么这么做”而不是“做了什么”。 - **禁止**无意义的注释如 // 获取用户 放在 getUser() 方法上。 ### 项目特定约定 - **API 响应**统一使用 CommonResultT 包装类包含 code, message, data 字段。 - **异常处理**业务异常使用 BusinessException 抛出在全局异常处理器 GlobalExceptionHandler 中捕获并转换为 CommonResult。 - **数据库实体**所有实体类必须继承 BaseEntity包含 id, createTime, updateTime 字段。 - **日志记录**使用 Slf4j 注解在关键业务步骤、异常捕获处记录 INFO 或 ERROR 级别日志。实操心得这部分规则不是一蹴而就的。我的建议是在最初期你可以只写几条你最在意的规则比如命名规范、API响应格式。然后在接下来的几天里每当 AI 生成的代码有不符合你习惯的地方你就把这条规则补充到Claude.md里。几周下来这份配置就会变得非常强大和个性化。3.3 架构模式与设计模式指引对于稍具规模的项目让 AI 理解你的架构决策至关重要这能保证新代码与旧系统和谐共处。## 架构与设计模式 ### 分层架构 本项目严格遵循 Controller-Service-Mapper 三层架构。 - **Controller 层**只负责接收请求、参数校验、调用 Service、返回封装结果。**禁止**在 Controller 中包含任何业务逻辑。 - **Service 层**核心业务逻辑所在地。接口定义在 XxxService实现在 XxxServiceImpl。 - **Mapper 层**仅负责数据库 CRUD 操作。使用 MyBatis-Plus 提供的 BaseMapper简单查询直接使用其方法复杂查询在 XML 中编写。 ### 常用设计模式场景 - **策略模式**用于不同的支付方式支付宝、微信支付。 - **工厂模式**用于根据商品类型创建不同的运费计算器。 - **观察者模式**用于订单状态变更时通知库存、物流、用户积分等模块。 ### 依赖注入 - 统一使用 Autowired 进行构造器注入以保证依赖不可变和便于测试。 - **示例** java Service public class UserServiceImpl implements UserService { private final UserMapper userMapper; Autowired public UserServiceImpl(UserMapper userMapper) { this.userMapper userMapper; } }### 3.4 外部依赖与工具库说明 告诉 AI 你项目中已经存在哪些“轮子”避免它重复造轮子或引入不兼容的库。 markdown ## 依赖与工具库 ### 核心依赖 - **数据访问**mybatis-plus-boot-starter (版本 3.5.4)。**注意**已配置逻辑删除TableLogic和自动填充MetaObjectHandler。 - **缓存**使用 spring-boot-starter-data-redis键名统一使用冒号分隔如 user:info:{userId}。 - **JSON 处理**使用 Jackson已在配置中设置日期格式为 yyyy-MM-dd HH:mm:ss。 ### 工具类 - **验证**使用 org.springframework.util.Assert 进行参数断言。 - **集合操作**优先使用 com.google.common.collect.Lists/Maps (Guava)。 - **对象转换**使用 org.mapstruct.Mapper 进行 DTO/Entity 转换而非手动 set/get。 - **已禁用**本项目不使用 Apache Commons Lang3 的 StringUtils请使用 org.springframework.util.StringUtils。注意明确“已禁用”的库非常重要。我曾遇到过 AI 在工具方法中引入了Apache Commons而我们的项目用的是 Guava导致不必要的依赖冲突清理起来很麻烦。3.5 提示词模板与交互偏好这是高阶用法用于定义你希望 AI 以何种“性格”或“流程”与你协作。## 交互与协作偏好 ### 角色设定 请你扮演一个经验丰富的 Java 后端架构师同时也是这个项目的核心开发成员。你深刻理解上述所有规范并致力于产出生产级可用的代码。 ### 响应格式偏好 1. **先思考后输出**对于复杂任务可以先给出一个简要的实现思路或步骤经我确认后再生成具体代码。 2. **代码优先**响应应以代码块为主解释性文字尽量精简放在代码块之前或之后。 3. **保持原子性**每次聚焦于一个明确的、可完成的小功能或修改。如果任务很大请主动将其拆解为多个步骤。 ### 安全检查 - 在生成任何涉及数据库查询的代码时请主动考虑 SQL 注入风险并使用 QueryWrapper 或 XML 中带 #{} 的参数绑定。 - 在生成文件操作、网络请求代码时请提醒我添加必要的异常处理和资源关闭逻辑。4. 实操过程如何创建并应用你的 Claude.md理论说了这么多我们来点实际的。下面我将以在 VSCode 中使用 Claude Code 插件为例展示从零开始创建和应用Claude.md的完整流程。4.1 环境准备与插件安装首先你需要在你的 IDE 中安装一个支持读取配置文件的 AI 编程助手插件。目前主流的有Claude CodeAnthropic 官方插件对Claude.md支持最原生。Cursor内置了 Claude 模型使用.cursorrules文件与Claude.md作用相同语法类似。Codeium、Bito等部分支持类似功能。这里以 Claude Code 为例打开 VSCode进入扩展市场 (CtrlShiftX)。搜索 “Claude Code” 并安装。安装后侧边栏会出现 Claude 的图标。你需要登录你的 Claude 账户通常需要国际网络环境请注意合规使用。确保插件已激活。你可以通过快捷键CmdK(Mac) 或CtrlK(Windows/Linux) 唤出 Claude 的聊天界面进行测试。4.2 创建并编写 Claude.md 文件定位文件在你的项目根目录下创建一个名为Claude.md的纯文本文件。是的名字就是Claude.md注意大小写。对于 Cursor文件名叫.cursorrules。初始内容不要试图一次性写完美。从一个最简单的版本开始。打开Claude.md先写入项目最核心的元信息和一两条你最在乎的代码规范。# 项目配置Claude.md ## 项目概述 - **项目名称**我的个人博客系统 - **技术栈**Node.js, Express, MongoDB, React (Next.js) ## 核心编码规范 - 使用 ES6 语法优先使用 const 和 let避免 var。 - API 路由遵循 RESTful 风格使用复数名词如 /api/articles。渐进式完善接下来的一周在以下场景中补充你的Claude.md场景AAI 生成的函数命名是get_data但你想要小驼峰getData。将这条命名规则加入配置文件。场景BAI 在 Express 路由里写了回调函数但你的项目全部使用async/await。将这条异步处理规范加入配置文件。场景CAI 建议安装axios发请求但你一直在用fetch。在配置文件中注明“前端请求统一使用原生fetch无需axios”。场景D你发现 AI 总是忘记校验用户输入。在配置文件的“通用原则”里加上“所有 API 端点必须对输入参数进行有效性校验”。4.3 验证配置是否生效编写完配置文件后最关键的一步是验证它是否被 AI 正确读取和理解。直接提问测试在 Claude Code 的聊天框中问一个与配置相关的问题。例如如果你的配置里强调了“使用const/let”你可以问“请帮我写一个遍历数组并打印的示例。” 观察生成的代码是否使用了const或let而不是var。上下文关联测试问一个需要结合项目背景的问题。例如根据上面的博客配置你可以问“我想新增一个‘文章评论’的功能后端需要怎么设计” 一个生效的配置应该能让 AI 的回答包含“根据您的技术栈我们需要在 Express 中创建一个新的路由文件commentRoutes.js连接到 MongoDB 的comments集合并遵循 RESTful 风格设计 POST/api/comments和 GET/api/articles/:id/comments等接口。”观察系统提示一些高级的 AI 助手会在你打开项目时在后台信息或日志里显示“已加载配置文件Claude.md”之类的提示。留意这些信息。我的踩坑经验配置文件不生效最常见的原因有两个。一是文件不在项目根目录二是文件名称拼写错误比如写成了claude.md或Claude.MD。请务必检查这两点。另外有些插件可能需要重启 IDE 或重新加载窗口才能识别新创建的配置文件。5. 高级技巧与场景化配置当你掌握了基础配置后可以尝试一些更高级的用法让Claude.md的威力倍增。5.1 模块化配置为子目录定制规则大型项目往往包含多个模块每个模块可能有细微的规范差异。你可以在子目录下创建额外的Claude.md文件其规则会覆盖或补充根目录的配置。/my-project ├── Claude.md # 全局配置 ├── /backend │ ├── Claude.md # 后端专用配置强调 Java 规范、Spring 注解 │ └── /src └── /frontend ├── Claude.md # 前端专用配置强调 React Hooks 使用、CSS-in-JS 方案 └── /src在/backend/Claude.md中你可以写# 后端模块配置 **此配置继承并覆盖根目录配置。** - 本模块所有代码文件必须包含 author 标签的类级别 Javadoc。 - 单元测试使用 JUnit 5 和 Mockito测试类命名格式为 *Test。 - 配置文件统一使用 application-{env}.yml 格式。这样当你在backend目录下工作时AI 会同时应用全局和本地的规则。5.2 动态上下文注入链接到重要文档Claude.md本身不宜过长否则会影响 AI 处理主要任务的上下文窗口。对于非常详细的 API 文档、架构设计图、协议说明等你可以采用“链接”的方式。## 重要参考文档 在回答涉及以下领域的问题时请务必参考对应文档 - **数据库设计**详见 /docs/database-schema.md - **第三方支付接口协议**详见 /docs/payment-api-v2.md - **微服务间通信规范**详见 /docs/service-communication.md虽然目前的 AI 插件不一定能主动读取这些链接文件但当你提出相关问题时你可以手动将这些文件内容粘贴到对话中并提醒 AI“这是我们的数据库设计文档请基于此为我生成实体类。” 而Claude.md的作用是提醒你——也间接提醒 AI——这些关键资源的存在。5.3 针对不同任务的“技能”配置你可以创建多个“技能”片段在需要时快速激活。例如在Claude.md末尾添加## 技能片段 ### [代码审查模式] 当我要求进行代码审查时请按以下维度分析 1. **代码风格**是否符合本项目命名、格式规范 2. **潜在缺陷**有无空指针、资源未关闭、线程安全、SQL 注入风险 3. **性能**有无低效循环、重复查询、内存泄漏可能 4. **可读性**逻辑是否清晰注释是否恰当 5. **改进建议**提供具体的、可选的优化方案。 ### [编写单元测试模式] 当需要编写单元测试时请遵循 1. 测试类名被测试类名 Test 2. 使用 Given-When-Then 结构。 3. 覆盖正常流程和主要异常分支。 4. Mock 对象行为设置清晰。当你想让 AI 切换模式时只需在聊天中说“请切换到「代码审查模式」帮我看看这段代码。” 然后粘贴代码即可。6. 常见问题与排查技巧实录在实际使用中你肯定会遇到各种问题。下面是我和社区里总结的一些常见坑点及解决方案。6.1 配置文件不生效或部分不生效症状AI 生成的代码完全无视Claude.md中的规则。排查步骤检查文件位置与名称确保文件在项目根目录且名称完全正确Claude.md。检查插件状态确认 Claude Code 或 Cursor 插件已正确安装、登录并激活。尝试在 IDE 内重启插件或重新加载窗口。简化测试创建一个全新的、极简的Claude.md只写一条非常独特的规则例如“所有变量名必须包含前缀my_”然后让 AI 生成一个简单变量看是否遵守。查看插件日志有些插件有输出通道Output Channel里面可能有加载配置文件的日志或错误信息。6.2 AI 似乎“理解”了配置但执行有偏差症状AI 在对话中承认看到了你的配置但生成的代码还是不符合要求。原因与解决规则冲突或模糊你的规则可能和其他隐含规则冲突或者表述不够精确。例如“使用清晰的命名”就不如“方法名必须使用动词开头如getUser,calculateTotal”明确。上下文优先级有时你当前打开的单个文件内容或最近的对话历史会对 AI 产生比Claude.md更强的即时影响。尝试开启一个新的聊天会话并首先提问“请先阅读项目根目录下的Claude.md配置文件然后我们再开始。”模型限制不同的 AI 模型对指令的遵循能力不同。Claude 3.5 Sonnet 通常比 Claude 3 Haiku 表现更好。确保你在插件设置中选择了能力更强的模型。6.3 如何平衡配置文件的详细程度问题写得太简略没效果写得太详细又怕占用太多上下文影响 AI 处理主要任务。我的经验核心优先优先编写那些一旦违反就需要大量返工的规则如项目结构、核心依赖、API 响应格式、全局异常处理。渐进式细化从 10 条最重要的规则开始随着合作中发现问题再添加。一个 50-100 行、重点突出的配置文件远比一个 500 行面面俱到的文件有效。使用注释在配置文件中用!-- 注释 --或# 注释来分隔模块和解释复杂规则这不会增加 AI 的理解负担但能让你自己维护起来更清晰。定期回顾每隔一段时间回顾一下配置文件将那些 AI 已经很好掌握的规则适当简化或者将很少触发的规则移到次要位置。6.4 团队协作时如何管理统一的 Claude.md挑战团队成员各有偏好如何形成一份公认的配置解决方案建立基线由技术负责人或架构师起草一份最基础的、关于技术栈和核心架构的配置作为不可争议的基线。代码风格自动化将诸如缩进、命名、导入排序等风格问题交给Prettier、ESLint、Checkstyle等工具自动化处理。在Claude.md中只需写明“代码格式已由 Prettier 统一管理生成代码后请运行格式化命令。”流程化将Claude.md纳入代码仓库管理。任何修改都需要通过 Pull Request 和团队其他成员 review确保变更合理且被广泛接受。个性化扩展允许开发者在自己的本地或项目子目录下创建个人扩展配置如.claude.local.md用于存放个人偏好的代码片段或提示词但该文件不应提交到仓库且其规则不能与团队主配置冲突。经过几个月的实践我个人的体会是Claude.md的价值不在于一蹴而就的完美而在于它是一个持续演进的、人与 AI 之间的协作契约。它开始可能只有寥寥数行但每当你发现一个可以固化下来的经验或规避一个重复的解释它就增长一点。最终它会成为你项目知识库中一个极具价值的资产让 AI 助手真正变成一个深度理解你工作习惯和项目背景的“老搭档”。花点时间配置它绝对是一笔回报率超高的投资。