JavaAIjava
Claude Code 核心记忆文件 CLAUDE.md 实战操作详解
Claude Code 是 Anthropic 推出的本地化 AI 编程助手，支持理解项目上下文并执行复杂任务。CLAUDE.md 作为其项目记忆文件，记录技术栈、构建命令及代码规范，帮助 AI 快速适配项目环境。重点说明 CLAUDE.md 核心价值、目录优先级、创建方法及最佳实践，涵盖自动生成、手动配置及分层管理策略，以提升 AI 辅助编程效率与准确性。
Claude Code 是 Anthropic 推出的本地化 AI 编程助手，支持理解项目上下文并执行复杂任务。CLAUDE.md 作为其项目记忆文件，记录技术栈、构建命令及代码规范，帮助 AI 快速适配项目环境。重点说明 CLAUDE.md 核心价值、目录优先级、创建方法及最佳实践，涵盖自动生成、手动配置及分层管理策略，以提升 AI 辅助编程效率与准确性。
在 AI 技术快速发展的背景下，借助 AI 工具提升开发效率已成为开发者的重要选择。Claude Code 作为本地化 AI 编程助手，配合 CLAUDE.md 项目记忆文件，可显著提升 AI 辅助编程的准确性与效率。本文详细介绍 Claude Code 及其核心配置文件 CLAUDE.md 的使用方法。
Claude Code 是 Anthropic 推出的本地化 AI 编程助手，专为开发者设计。它不仅能理解项目结构，还能执行复杂任务并自动化开发流程。
AI 编程工具经历了从 GitHub Copilot 到 Cursor、Warp 等新一代工具的演进，Claude Code 在上下文理解和任务执行能力上表现突出。
Claude Code 具备如下核心特点：
下表汇总了市面上几款主流的 AI 编程工具对比：
| 特性 | Claude Code | GitHub Copilot | Cursor |
|---|---|---|---|
| 项目理解深度 | 能分析整个代码库，理解项目架构 | 能分析整个代码库，理解项目架构 | 有限的项目理解能力 |
| 任务执行能力 | 可直接执行任务，端到端自动化 | 仅提供代码建议，需手动采纳 | 半自动化，需要更多人介入 |
| 模型优化 | 原厂优化，稳定性高，响应快速 | 第三方集成，性能依赖网络 | 第三方集成，稳定性一般 |
| 本地化支持 | 完全本地化，安全性高 | 云端服务，有数据隐私顾虑 | 混合模式，部分功能依赖云端 |
CLAUDE.md 是 Claude Code 的'项目记忆文件'，记录项目结构、构建命令、代码规范、架构决策等信息，让 Claude Code 快速理解项目上下文。
简单来说，CLAUDE.md 是 Claude Code 的持久化记忆配置文件，本质是一个普通的 Markdown 文件，却能在每次启动 Claude Code 会话时，自动被加载到 AI 的上下文里，相当于给 AI 提前'灌输'项目信息和规则。
Claude.md 放在不同位置，作用范围不同，冲突时也有明确的覆盖逻辑。
┌─────────────────────────────────────────────────────────────────┐
│ 文件位置层级 │
├─────────────────────────────────────────────────────────────────┤
│ 最高优先级：特定规则 │
│ 位置：.claude/rules/*.md │
│ 说明：针对特定模块或功能的详细规则 │
├─────────────────────────────────────────────────────────────────┤
│ 第二优先级：模块级配置 │
│ 位置：src/.claude/CLAUDE.md │
│ 说明：针对特定模块的配置 │
├─────────────────────────────────────────────────────────────────┤
│ 第三优先级：项目配置 │
│ 位置：CLAUDE.md (项目根目录) │
│ 说明：全局项目配置 │
├─────────────────────────────────────────────────────────────────┤
│ 最低优先级：用户级配置 │
│ 位置：~/.claude/CLAUDE.md │
│ 说明：用户个人偏好设置 │
└─────────────────────────────────────────────────────────────────┘
1）各优先级使用场景
2）优先级规则 如果多个位置都存在 Claude.md 文件时，AI 会按「优先级从高到低」加载，冲突内容通常以高优先级为准。
优先级顺序：企业级 > 项目级 > 用户级
示例： 如果在用户级 claude.md 中配置了'代码使用单引号'，但当前项目的项目级 claude.md 中配置了'代码使用双引号'，那么在这个项目中，AI 会优先遵循'双引号'规则。
3、Claude.md 目录结构示例
project/
├── CLAUDE.md # 项目根目录配置
├── src/
│ ├── .claude/
│ │ └── CLAUDE.md # 模块级配置
│ └── components/
├── .claude/
│ └── rules/
│ ├── auth.md # 认证相关规则
│ ├── database.md # 数据库相关规则
│ └── api.md # API 设计规范
└── docs/
└── CLAUDE.md # 文档模块配置
推荐实践方式是自动生成，人工再根据生成的文件，结合经验和项目实际情况进行微调优化。
分为必须放的内容和推荐放的内容。
1、技术栈声明
## 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 5
2、项目结构
## 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、构建和运行命令
## Common Commands
- Build: `./mvnw clean package`
- Run: `./mvnw spring-boot:run -Dspring-boot.run.profiles=dev`
- Test: `./mvnw test`
- DB migration: `./mvnw flyway:migrate`
4、关键约定（禁止事项）
## CRITICAL RULES
- NEVER use `@Autowired` on fields - use constructor injection
- NEVER catch `Exception` without logging
- NEVER use `eager` fetching in JPA
- NEVER hardcode credentials
5、架构决策记录
## Architecture Decisions (ADRs)
- Outbox pattern for reliable event publishing
- CQRS for order querying (separate read/write models)
- Circuit breaker for all external HTTP calls
1、常用模式和代码示例
## Code Patterns
### Repository Pattern
public interface OrderRepository extends JpaRepository<Order, Long> {
Optional<Order> findByOrderNumber(String orderNumber);
}
2、DTO Mapping
Use MapStruct: @Mapper(componentModel = "spring")
3、环境配置说明
## Environment Setup
- Dev: `application-dev.yml` (local Postgres, Redis)
- Staging: Kubernetes namespace `staging`
- Prod: Requires approval for deployment
4、测试策略
## 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)
5、依赖和版本约束
## 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.x
进入本地某个项目目录中，进入 Claude 交互式命令行窗口中，使用 /init 命令让 AI 生成一个初始化的 CLAUDE.md 文件。
然后，AI 会对当前的项目进行完整的拆解、分析。
生成完成后，在项目的根目录下，生成了左侧的 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(测试规范)，作为后续团队对该项目的开发规范，生成后，接下来我将与你持续共创并完善这些文件内容
最后，几个文件按照规范要求生成，并放在指定的目录下。
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 文件。
如果是项目级的话，还需进入到项目目录下，如下，进入到具体的项目目录下之后，再次查看：
编写规则，完善规则，将规则加载到 claude 的记忆，这些可以理解为前置的步骤，或者准备，这些准备都是为接下来实际项目开发做参考使用的，即通过这些文件来规范 AI 编写代码应该遵守的边界。
下面提一个明确的需求，让 AI 为我们生成一个接口，最后检查 AI 生成的接口是否符合预期的要求，需求提示词如下：
参考 @doc\api-develop-standard.md 规范，在 TmsWaybillController 新增一个查询订单表的接口，支持多参数查询，比如订单号，创建时间，客户编号
明确要求 AI 编写接口的时候需要参考提前指定好的 API 编写规范文件，确保生成的接口与当前的接口规范是一致的。
接口效果如下，生成的代码基本是按照当前项目的规范，参考了上面创建的 CLAUDE.md 文件的同时，也遵循了引用的接口编写规范文件。
/**
* 分页查询订单表
*/
@PostMapping("/order/list")
@Operation(summary = "分页查询订单列表", description = "支持按订单号、客户编号、创建时间范围查询")
public R<Pagination<TmsOrderVO>> orderList(@RequestBody TmsOrderPageRequest request) {
return R.ok(tmsOrderService.listByPage(request));
}
@Override
public Pagination<TmsOrderVO> listByPage(TmsOrderPageRequest request) {
Page<TmsOrder> page = PageHelper.startPage(request.getPageNum(), request.getPageSize());
List<TmsOrder> list = tmsOrderMapper.listByPage(request);
List<TmsOrderVO> 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);
}
Claude.md 配置的核心原则是：「精简、精准、分层」。不用写多余的说明，只放 AI 每次会话都需要用到的信息，否则会消耗过多 Token，反而降低 AI 的遵从度。
1）按层级拆分内容，不重复、不冗余 这是最关键的原则。不同层级的 Claude.md 各司其职，发挥不同的作用，为避免重复维护，具体分工可以参考这个决策树：
2）控制文件长度，避免 Token 浪费 Claude Code 上下文 Token 有限，因此 Claude.md 并非越长越好，建议遵循这个下面这个长度标准：
3）用「What-Why-How」结构组织内容 清晰内容结构能让 AI 更容易识别规则，建议按'What-Why-How'的逻辑组织内容，比如：
4）精准配置 paths，减少无效加载 如果项目是多语言、多模块，可在 Claude.md 文件开头用 paths 元数据限定规则的生效范围，避免无关内容加载消耗 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 Code 中的 CLAUDE.md 是重要的'记忆文件'，核心就是通过'分层配置 + 精准规则'，让 Claude Code 记住你的偏好、你的项目规范，从而减少重复沟通，提升编码效率。
对于新手来说，先从项目级 claude.md 入手，用「/init」命令生成初始文件，再补充项目技术栈和编码规范；熟悉后再配置用户级 claude.md，统一个人编码习惯；多项目维护时，用好分层规则，就能轻松搞定 AI 编码的'默契感'。
建议定期用「/memory」命令检查、更新规则，删除过期内容，让 AI 始终保持'精准记忆'。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online
JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online
Terser 压缩、变量名混淆，或 javascript-obfuscator 高强度混淆（体积会增大）。 在线工具，JavaScript 压缩与混淆在线工具，online
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online