【AI智能体】Claude Code 核心记忆文件 CLAUDE.md实战操作详解

目录一、前言二、Claude Code 介绍2.1 Claude Code 是什么2.2 Claude Code 核心特点2.3 与其他AI编程工具对比三、CLAUDE.md 项目记忆文件介绍3.1 CLAUDE.md 文件概述3.1.1 CLAUDE.md 是什么3.1.2 CLAUDE.md 核心特点3.1.3 CLAUDE.md 核心价值3.2 CLAUDE.md 目录结构说明3.2.1 Claude.md 文件存放目录优先级3.3 Claude.md 文件创建3.3.1 Claude.md 文件创建的几种方式3.4 Claude.md 文件项目操作实践3.4.1 Claude.md 文件可以存放的内容3.4.1.1 必须放的内容核心价值3.4.1.2 推荐放的内容高价值3.4.2 基于已有项目创建CLAUDE.md3.4.3 基于微服务项目级CLAUDE.md文件使用3.4.4 记忆加载过程3.4.5 基于规则文件开发接口3.4.6 Claude.md 应用最佳实践四、写在文末一、前言在AI技术日新月异的今天开发者们正经历着一场前所未有的效率革命。面对日益复杂的开发需求和快速迭代的技术栈借助AI工具提升开发效率已不再是选择题而是必选项。在这种情况下各种AI编程工具纷纷出现甚至一度让开发者感觉到眼花缭乱。借助AI编程工具不仅可大幅提升编程效率对开发者来说也是一场自我迭代和升级的过程让开发者自身从一个纯粹的编程人员逐步转型为AI编程全站工程师从而实现自身更大的价值本篇将详细介绍近期AI编程中非常火热的Claude Code以及CLAUDE.md文件规则编写在AI辅助编程中的重要作用。二、Claude Code 介绍2.1 Claude Code 是什么Claude Code是Anthropic推出的本地化AI编程助手专为开发者设计。它不是一个简单的代码补全工具而是一个能理解你的项目、执行复杂任务、自动化开发流程的智能编程伙伴。官方入口https://claude.com/product/claude-code中文文档https://code.claude.com/docs/zh-CN/mcpAI编程之旅始于GitHub Copilot的早期版本。记得当时虽然惊艳于它”自动补全”的能力但受限于上下文理解深度和代码质量实际应用中常常是“有点作用但不多”。随后出现的Cursor、Warp等新一代AI编程工具虽然引起了我的关注却因种种原因未能深入体验。2.2 Claude Code 核心特点Claude Code 具备如下核心特点技术搭档式协作能读懂整个代码库结构理解项目架构和业务逻辑主动分析代码依赖关系提供符合项目规范的代码建议根据项目上下文智能推断开发意图减少重复沟通CLI交互方式通过自然语言描述需求(如修复这个bug”、重构这段代码”)支持复杂任务分解自动执行多步骤操作提供实时反馈让开发过程透明可控深度集成开发流程不仅能写代码还能管理Git版本控制调用本地工具链执行构建、测试等任务根据你的代码习惯和项目规范优化输出2.3 与其他AI编程工具对比下表汇总了市面上几款主流的AI编程工具从多个维度对他们各自的特点进行了对比特性Claude CodeGitHub CopilotCursor项目理解深度能分析整个代码库理解项目架构能分析整个代码库理解项目架构有限的项目理解能力有限的项目理解能力可直接执行任务端到端自动化仅提供代码建议需手动采纳半自动化需要更多人介入模型优化原厂优化稳定性高响应快速第三方集成性能依赖网络第三方集成稳定性一般本地化支持完全本地化数据安全性高云端服务有数据隐私顾虑混合模式部分功能依赖云端三、CLAUDE.md 项目记忆文件介绍3.1 CLAUDE.md 文件概述3.1.1 CLAUDE.md 是什么CLAUDE.md 是 Claude Code 的项目记忆文件记录项目结构、构建命令、代码规范、架构决策等信息让 Claude Code 快速理解项目上下文。简单来说claude.md是Claude Code的持久化记忆配置文件本质是一个普通的Markdown文件却能在每次启动Claude Code会话时自动被加载到AI的上下文里相当于给AI提前“灌输”项目信息和规则不用你反复叮嘱。举个直观的例子如果把Claude Code比作一位临时加入你团队的工程师claude.md就是你给他的「项目手册」——里面写清了项目技术栈、编码规范、工作流要求他一看就懂不用你花半小时反复讲解背景上手就能配合干活。3.1.2 CLAUDE.md 核心特点CLAUDE.md是 Claude Code 的项目知识库文件其具备以下特点持久化存储记录项目相关信息长期有效自动读取Claude Code 自动加载无需重复解释团队共享整个团队可以共享同一份配置持续演进随项目发展不断更新3.1.3 CLAUDE.md 核心价值CLAUDE.md 是一个为 Claude 代码助手或类似 AI 编程助手提供项目上下文和指导的配置文件。其核心价值包括1、提供项目上下文快速告知 AI 项目的技术栈语言、框架、依赖说明项目结构和模块组织方式明确关键文件和目录的用途2、规范AI行为定义代码风格和命名约定指定测试命令、构建流程、运行方式设置响应格式偏好如简洁或详细3、提高协作效率减少重复性的背景说明避免 AI 产生不符合项目规范的代码保持代码生成的一致性4、知识沉淀记录项目的特殊约定或架构决策保存常见的开发工作流传递团队的最佳实践5、节省 Token 成本避免每次对话都要重新说明项目背景精准的指令减少试错和纠正次数3.2 CLAUDE.md 目录结构说明很多人反馈说Claude.md用起来没有方向核心是没搞懂它应该存放的位置和优先级规则Claude.md放在不同位置作用范围不同冲突时也有明确的覆盖逻辑记住这两点就能避免90%的配置踩坑3.2.1 Claude.md 文件存放目录优先级┌─────────────────────────────────────────────────────────────────┐ │ 文件位置层级 │ │ │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ 最高优先级: 特定规则 │ │ │ │ 位置: .claude/rules/*.md │ │ │ │ 说明: 针对特定模块或功能的详细规则 │ │ │ └───────────────────────────────────────────────────────────┘ │ │ ↓ │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ 第二优先级: 模块级配置 │ │ │ │ 位置: src/.claude/CLAUDE.md │ │ │ │ 说明: 针对特定模块的配置 │ │ │ └───────────────────────────────────────────────────────────┘ │ │ ↓ │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ 第三优先级: 项目配置 │ │ │ │ 位置: CLAUDE.md (项目根目录) │ │ │ │ 说明: 全局项目配置 │ │ │ └───────────────────────────────────────────────────────────┘ │ │ ↓ │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ 最低优先级: 用户级配置 │ │ │ │ 位置: ~/.claude/CLAUDE.md │ │ │ │ 说明: 用户个人偏好设置 │ │ │ └───────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘1各优先级使用场景通过上面的目录结构不难看出Claude.md支持4个层级的存放位置覆盖个人到企业不同场景新手建议从项目级和用户级入手企业级仅企业账号可用路径随系统不同如macOS/Library/Application Support/ClaudeCode/CLAUDE.md作用于企业内所有用户用于统一企业级编码策略和安全规范。项目级放在项目根目录路径./CLAUDE.md仅对当前项目生效是最常用的位置。适合存放项目专属的技术栈、团队规范、项目架构等内容建议纳入Git版本控制方便团队共享。用户级放在用户主目录路径~/.claude/CLAUDE.md作用于个人所有项目适合存放跨项目通用的个人偏好比如缩进规则、引号使用习惯、常用快捷指令等。2优先级规则如果多个位置都存在Claude.md文件时AI会按「优先级从高到低」加载冲突内容通常以高优先级为准规则其实很简单记好下面这个顺序即可企业级 项目级 用户级举个实际例子理解你在用户级claude.md中配置了“代码使用单引号”但当前项目的项目级claude.md中配置了“代码使用双引号”那么在这个项目中AI会优先遵循“双引号”规则——项目级覆盖用户级。小tips如果担心规则冲突可以在claude.md中用emoji标记重点规则AI会优先识别这类明确指引提升规则命中率。2、Claude.md 目录结构示例project/ ├── CLAUDE.md # 项目根目录配置 ├── src/ │ ├── .claude/ │ │ └── CLAUDE.md # 模块级配置 │ └── components/ ├── .claude/ │ └── rules/ │ ├── auth.md # 认证相关规则 │ ├── database.md # 数据库相关规则 │ └── api.md # API 设计规范 └── docs/ └── CLAUDE.md # 文档模块配置3.3 Claude.md 文件创建基于上面的描述创建 Claude.md可以手动按照上面的目录结构创建也可以自动生成通常比较推荐的实践方式是自动生成人工再根据生成的文件结合经验和项目实际情况进行微调优化3.3.1 Claude.md 文件创建的几种方式下面介绍几种Claude.md 文件的创建方式不用手动从零编写这3种方式能快速搞定建议新手优先考虑选择前两种自动生成在项目根目录启动Claude Code输入「/init」命令AI会自动分析项目结构、依赖和关键文件生成初始的claude.md后续只需人工修改完善即可手动创建进入对应目录项目根目录或用户主目录通过命令「touch CLAUDE.md」创建文件再写入基础规则比如技术栈、编码规范等快速添加在Claude Code对话中输入以「#」开头的内容比如「# 所有代码需遵循PEP8规范」选择“存入claude.md”即可快速将规则添加到对应文件中也可输入「/memory」命令直接在编辑器中编辑claude.md。3.4 Claude.md 文件项目操作实践通过上面的介绍后我们知道了Claude.md的作用目录结构以及创建的方式接下来通过几个实际案例操作演示下如何创建并使用Claude.md 文件。3.4.1 Claude.md 文件可以存放的内容Claude.md文件中可以存放多种类型的文件比如项目技术栈编码规范构建命令等从大的分类上讲可以分为两类必须放的内容推荐放的内容3.4.1.1 必须放的内容核心价值1、技术栈声明存放项目中的核心技术栈内容作用让AI知道可用的库和API避免建议不兼容的技术## Tech Stack - Java 21 Spring Boot 3.3.x - Maven 3.9 (use wrapper) - PostgreSQL 16 Redis 7 - Kafka 3.x for messaging - Testcontainers JUnit 52、项目结构作用让AI能准确找到和创建文件## Project Structure - src/main/java/com/example/domain/ - 核心业务逻辑 - src/main/java/com/example/api/ - REST controllers - src/main/resources/db/migration/ - Flyway脚本 - src/test/java/ - 单元测试和集成测试3、构建和运行命令作用AI知道如何执行测试、构建等操作## Common Commands - Build: ./mvnw clean package - Run: ./mvnw spring-boot:run -Dspring-boot.run.profilesdev - Test: ./mvnw test - DB migration: ./mvnw flyway:migrate4、关键约定禁止事项作用防止AI产生不符合规范的代码## CRITICAL RULES - NEVER use Autowired on fields - use constructor injection - NEVER catch Exception without logging - NEVER use eager fetching in JPA - NEVER hardcode credentials5、架构决策记录作用AI理解设计意图做出一致的扩展## Architecture Decisions (ADRs) - Outbox pattern for reliable event publishing - CQRS for order querying (separate read/write models) - Circuit breaker for all external HTTP calls3.4.1.2 推荐放的内容高价值这部分的内容是对上述必须放的内容的补充1、常用模式和代码示例作用让AI编写代码的时候提供参考## Code Patterns ### Repository Pattern java public interface OrderRepository extends JpaRepositoryOrder, Long { OptionalOrder findByOrderNumber(String orderNumber); }2、DTO MappingUse MapStruct:Mapper(componentModel spring)作用AI能给出正确的配置建议**作用**示范正确写法减少纠正次数。 ### 7. 环境配置说明 markdown ## Environment Setup - Dev: application-dev.yml (local Postgres, Redis) - Staging: Kubernetes namespace staging - Prod: Requires approval for deployment ## Required Environment Variables - DB_PASSWORD - PostgreSQL password - KAFKA_BOOTSTRAP_SERVERS - Kafka brokers3、测试策略作用AI生成的测试符合项目标准## Testing Guidelines - Unit tests: Mock all dependencies - Integration tests: Use Testcontainers for real DB - E2E tests: Run with -Pe2e profile - Target coverage: 80% (use JaCoCo)4、依赖和版本约束作用避免版本冲突避免AI 生成代码的时候另起一套## Version Constraints - Spring Boot: 3.3.x ONLY (not 3.2.x or 3.4.x) - Java: 21 LTS only - Jackson: 2.17 (for Java 21 records support) - Avoid: Lombok, Apache Commons Lang 2.x5、重要文件位置作用快速定位关键配置## Key Files Reference | Purpose | Location | |---------|----------| | Main config | src/main/resources/application.yml | | Security rules | SecurityConfig.java | | Error handling | GlobalExceptionHandler.java | | API docs | openapi.yaml (generated) |3.4.2 基于已有项目创建CLAUDE.md进入本地某个项目目录中进入Claude 交互式命令行窗口中使用 /init 命令让AI生成一个初始化的CLAUDE.md文件然后AI会对当前的项目进行完整的拆解、分析生成完成后在项目的根目录下生成了左侧的CLAUDE.md文件该文件中主要包含了下面的核心内容构建命令项目的基础设施核心业务微服务模块服务之间通讯方式项目规范关键技术栈和技术选型..结合前面的描述该文件属于项目根目录配置 文件属于全局配置文件全局生效3.4.3 基于微服务项目级CLAUDE.md文件使用更多情况下在实际的开发实践中不同的微服务项目都有属于项目级的规则比如开发规范、构建标准、技术栈等一个项目级的CLAUDE.md文件目录结构如下your-java-microservice/ ├── CLAUDE.md # 主配置文件80-150行 ├── .claude/ │ ├── rules/ # 模块化规则 │ │ ├── testing.md # 测试规范条件加载 │ │ ├── api-design.md # API设计规范 │ │ ├── database.md # 数据库操作规范 │ │ └── security.md # 安全规范 │ └── commands/ # 自定义命令 │ ├── test.md │ └── build.md └── agent_docs/ # 详细文档可选 ├── architecture-guide.md └── deployment.md仍然基于上述的项目与Claude Code 共创这几个文件按照上面的目录结构依次生成这些文件1生成项目级的CLAUDE.md文件输入下面的提示词有了这个文件后不管是新进入团队的人还是其他人想快速了解项目时看这个文件就能了解如果初始化的CLAUDE.md文件中仍然有一些不尽人意或者需要继续补充的地方直接在对应的位置加进去即可2生成项目级下面的其他规则文件按照上述的项目级的目录结构我们再依次生成其他的项目规则文件参考下面的提示词在当前工程的 ./claude/rules 目录下依次生成api-design.md(API接口设计规范)database.md数据库操作规范testing.md(测试规范)作为后续团队对该项目的开发规范生成后接下来我将与你持续共创并完善这些文件内容最后几个文件按照规范要求生成并放在指定的目录下3.4.4 记忆加载过程CLAUDE.md 文件生成后你不需要做任何“额外操作”来“激活”它 —— Claude Code 会自动读取并应用。但知道如何与它交互、如何利用它的能力才能真正发挥价值。一、立即验证确认配置生效在开始使用前先确认 CLAUDE.md 已被正确加载。启动 Claude Code 并检查状态# 在项目根目录启动 Claude Code cd your-java-microservice claude基于上面已经生成了 CLAUDE.md 文件的情况下先退出并重新开启会话启动后Claude 会自动读取 CLAUDE.md。可以通过以下命令验证 /status # 查看当前会话状态和配置 /context # 查看上下文窗口占用确认 CLAUDE.md 已加载在项目的根目录下下面的检查加载的是全局的那一个CLAUDE.md文件如果是项目级的话还需进入到项目目录下如下进入到具体的项目目录下之后再次查看通过输出的日志信息不难发现进入到项目目录后又把前文中项目下的几个md文件自动加载到上下文记忆中3.4.5 基于规则文件开发接口上面几步总结下来就是编写规则完善规则将规则加载到claude 的记忆这些可以理解为前置的步骤或者准备这些准备都是为接下来实际项目开发做参考使用的即通过这些文件来规范AI编写代码应该遵守的边界下面我们提一个明确的需求让AI为我们生成一个接口最后检查AI生成的接口是否符合预期的要求需求提示词如下参考 doc\api-develop-standard.md 规范在TmsWaybillController 新增一个查询订单表的接口支持多参数查询比如订单号创建时间客户编号我这里明确要求AI 编写接口的时候需要参考我提前指定好的API编写规范文件确保生成的接口与当前的接口规范是一致的接口效果如下生成的代码基本是按照当前项目的规范参考了上面创建的CLAUDE.md文件的同时也遵循了引用的接口编写规范文件/** * 分页查询订单表 */ PostMapping(/order/list) Operation(summary 分页查询订单列表, description 支持按订单号、客户编号、创建时间范围查询) public RPaginationTmsOrderVO orderList(RequestBody TmsOrderPageRequest request) { return R.ok(tmsOrderService.listByPage(request)); } Override public PaginationTmsOrderVO listByPage(TmsOrderPageRequest request) { PageTmsOrder page PageHelper.startPage(request.getPageNum(), request.getPageSize()); ListTmsOrder list tmsOrderMapper.listByPage(request); ListTmsOrderVO voList list.stream().map(order - { TmsOrderVO vo new TmsOrderVO(); BeanUtils.copyProperties(order, vo); return vo; }).collect(Collectors.toList()); return new Pagination(request.getPageNum(), request.getPageSize(), page.getTotal(), voList); }3.4.6 Claude.md 应用最佳实践Claude.md 配置的核心原则是「精简、精准、分层」不用写多余的说明只放AI每次会话都需要用到的信息否则会消耗过多Token反而降低AI的遵从度。结合一线实操经验以下总结了几个个最佳实践可以直接套用。1按层级拆分内容不重复、不冗余这是最关键的原则。不同层级的Claude.md各司其职发挥不同的作用为避免重复维护具体分工可以参考这个决策树用户级~/.claude/CLAUDE.md放「通用、跨项目」的内容比如个人编码风格缩进2空格、行尾必须加冒号、常用操作提交前运行npm test、通用安全规则禁止硬编码敏感信息项目级项目根目录/CLAUDE.md放「项目专属」的内容比如项目技术栈React 18 TypeScript、项目结构/src/components为UI组件目录、团队编码规范组件命名用PascalCase、构建命令npm run build2控制文件长度避免Token浪费Claude Code 上下文Token有限因此Claude.md 并非越长越好建议遵循这个下面这个长度标准单文件最佳长度100-200行最多不超过300行超过这个范围AI的规则遵从度会明显下降内容精简技巧只写“指令性内容”删除多余的说明比如“以下规则是团队讨论决定的”复杂规则可通过「path/to/file.md」语法导入其他文件拆分维护最大递归深度为5层3用「What-Why-How」结构组织内容清晰内容结构能让AI更容易识别规则建议按“What-Why-How”的逻辑组织内容比如What是什么项目技术栈、目录结构、核心架构比如“前端用React 18 Zustand后端用Node.js”Why为什么项目目的、设计原则、约束条件比如“项目需兼容IE11避免使用ES6新特性”How怎么做构建命令、测试方法、开发流程比如“运行npm run dev启动本地服务提交前需运行npm lint”4精准配置paths减少无效加载如果项目是多语言、多模块可在Claude.md 文件开头用paths元数据限定规则的生效范围避免无关内容加载消耗Token如下示例这样一来只有操作Python文件时这部分规则才会被加载操作其他类型文件如.js时不会生效大幅提升Token使用效率。--- paths: **/*.java # 仅对Java文件生效 --- # Java 专属规则 1. 必须遵循本项目中 /doc/ap-dev-rule.md 的接口编写规范 2. 变量命名采用驼峰命名 3. 严格遵守MVC的编写规范5团队协作必做纳入Git版本控制如果是团队项目项目级Claude.md 一定要纳入Git版本控制确保所有的团队成员都能使用统一的规则避免AI生成的代码风格不一致而用户级claude.md属于个人偏好不建议纳入Git避免冲突。修改Claude.md后无需重启Claude Code保存后会自动加载生效 若未生效输入「/restart」命令重启会话即可。6避开3个常见坑下面几个坑在实际使用中需要避免规则冲突优先级搞混记住“项目级覆盖用户级”冲突时优先检查项目级claude.md的规则避免模糊表述比如同时写“可用单引号”和“可用双引号”内容过于冗余写了任务特定的规则比如“实现登录功能用JWT”这类内容无需写进claude.md仅保留“所有会话都需要的通用规则”否则AI会将其视为噪音忽略整个文件规则过多不拆分如果规则超过20条建议改用「.claude/rules/」文件夹分类管理比单文件claude.md更易维护且加载更精准四、写在文末本文通过较大的篇幅详细介绍了Claude Code 中Claude.md 这个非常重要的“记忆文件”其实claude.md的用法并不复杂核心就是通过“分层配置精准规则”让Claude Code记住你的偏好、你的项目规范从而减少重复沟通提升编码效率。对于新手来说先从项目级claude.md入手用「/init」命令生成初始文件再补充项目技术栈和编码规范熟悉后再配置用户级claude.md统一个人编码习惯多项目维护时用好分层规则就能轻松搞定AI编码的“默契感”。最后提醒claude.md不是“一劳永逸”的建议定期用「/memory」命令检查、更新规则删除过期内容让AI始终保持“精准记忆”。