claude code 开发实践 - 记忆系统
·
Claude Code 记忆系统
Claude Code 的本质是一个高度可扩展的智能体框架，采用模块化单体分层架构 + 事件驱动 + 异步生成器主循环，而不仅仅是一个聊天工具。
下图是claude code的四层架构模型（来源于：《cluade code实战：harness 工程之道》），本期结合具体的案例，主要讲解最底层的记忆层（claude.md）。
一、Claude Code 记忆系统（核心：CLAUDE.md）
大家平常使用claude code 过程中，相信Cluade.md应用是最多的，基于本人在绩效考核项目中的实践分享一下我对记忆系统的理解。
项目已经开源，前后端基本90%是用cluade code写的，模型采用的是glm5.1，项目地址是:
https://gitee.com/fish982000/kpi-360-backend.git
1.1 四层记忆分层模型（加载优先级由低→高，高层覆盖低层冲突）
记忆分为长期静态记忆（人工编写）+ 中期自动记忆（AI自学）+ 短期会话记忆三层，核心文件就是项目根目录下的 CLAUDE.md。
| 层级 | 文件 | 写入者 | 存放路径 | 生效时机 | 作用定位 |
|---|---|---|---|---|---|
| 第1层：全局用户记忆 | CLAUDE.md | 开发者 | ~/.claude/CLAUDE.md |
每次会话启动自动加载 | 个人通用编码习惯、语言、全局工具配置 |
| 第2层：项目团队记忆（核心） | 项目根目录/CLAUDE.md | 团队开发者，Git版本管控 | 项目仓库根目录 | 会话必加载，全文读取无行数限制 | 项目架构、技术栈、目录规范、业务约束、编码规则（永久记忆，跨会话不丢失） |
| 第3层：本地私有记忆 | CLAUDE.local.md | 个人本地 | 项目根目录（加入.gitignore） | 会话加载 | 本机环境、本地配置、临时调试规则，不提交代码库 |
| 第4层：自动学习记忆 | MEMORY.md / debugging.md | Claude自动写入 | ~/.claude/projects/{仓库hash}/memory/ |
会话启动只加载前200行，其余按需读取 | AI自动沉淀架构决策、踩坑日志、接口约定、Bug解决方案（自学经验） |
核心机制
- CLAUDE.md = 项目的长期大脑
每次新开会话、重启终端，都会优先读取这份文件，不用反复重复交代项目背景，彻底解决跨会话失忆问题。 - 自动记忆（Auto Memory）
开发过程中，Claude会自动把架构决策、调试经验、API约定写入自动记忆文件，无需人工维护；同一个Git仓库所有目录共享一套自动记忆。 - 上下文隔离
- 静态记忆：CLAUDE.md（必须遵守）
- 经验记忆：Auto Memory（迭代沉淀）
- 临时记忆：当前对话上下文（会话结束自动销毁）
关键限制
- CLAUDE.md：全文完整加载，无行数上限，官方建议精简到500行以内;
- MEMORY.md：仅前200行在会话初始化载入，超长内容会拆分到子文件，避免挤占Token。
1.2 CLAUDE.md 标准内容结构（通用模板）
固定分为6大块，所有业务项目都遵循这套结构：
- 项目概述与业务边界
- 整体技术栈与架构分层
- 目录结构说明
- 编码规范与类型约束
- 业务领域规则（最重要）
- 脚本命令、权限约束、禁止修改清单
二、实战案例：通用绩效管理系统（360绩效考核平台）
项目背景：企业级绩效考核全栈系统，DDD分层微服务架构，前后端分离；后端SpringBoot3 + Sa-Token + MyBatis-Plus，前端React19 + Zustand + Ant Design + Tailwind。
在项目根目录新建 CLAUDE.md，内容如下：
# 项目：通用绩效管理系统（360考核平台）
## 1. 项目业务概述
### 业务范围（严格遵守边界，禁止扩展）
1. 组织架构管理：部门、岗位、员工树形组织树
2. 角色权限RBAC：数据权限+功能权限，Sa-Token实现会话管控
3. 考核方案管理：创建考核周期、考核指标库、评分权重配置
4. 支持上下级、平级、自评
5. 成绩统计、绩效报表、历史归档
### 业务约束
- 数据隔离：各部门数据严格隔离
## 2. 技术架构（DDD领域驱动分层，严格分层，禁止跨层调用）
### 后端（backend/）SpringBoot3 微服务
1. 基础设施层(infrastructure)：数据库、Redis、Feign调用、Sa-Token会话、外部接口防腐层
2. 应用层(Application)：Query、Command入参、服务编排、事务控制
3. 领域层(Domain)：聚合根、实体、领域服务、业务规则（核心业务逻辑必须放在此处）
4. 接口层(facade)：web、权限拦截、参数校验
### 前端（frontend/）React19 + TS
1. 路由：React Router v6，路由元信息配置权限 meta.requiresAuth
2. 状态：Zustand + persist持久化，拆分store（组织store、考核store、用户store）
3. UI组件：Ant Design v6 + Tailwind CSS，统一封装通用表格、树形组件
4. 网络：Axios统一封装，携带Sa-Token令牌，统一异常拦截
### 技术栈清单
- 后端：Java17、SpringBoot3、SpringCloud、MyBatis-Plus、Sa-Token、MySQL8、Redis
- 前端：React19、TypeScript、Vite、Zustand、Ant Design、Tailwind、React Query
- 包管理：后端Maven，前端pnpm
- 数据库：MySQL，所有表必须包含字段：id, create_time, update_time, deleted（逻辑删除）
## 3. 全局目录结构（禁止随意新增目录）
src/main/java/com/kpi360/
├── Kpi360Application.java # @MapperScan("com.kpi360.infrastructure.persistence.mapper")
├── common/ # Result / PageResult
├── config/ # MyBatisPlusConfig (分页 + createTime/updateTime 自动填充)
├── exception/ # BusinessException / GlobalExceptionHandler
│
├── facade/ # 接口层（替代关键字 interface）
│ ├── web/ # 全部 /api/v2/* REST 控制器
│ │ ├── AuthFacade.java # /api/v2/auth
│ │ ├── DepartmentFacade / UserFacade / RoleFacade / ResourceFacade # /api/v2/system/*
│ │ ├── DimensionFacade / IndicatorFacade / TemplateFacade # /api/v2/assessment/*
│ │ ├── CampaignFacade.java # /api/v2/assessment/campaigns (含 calculate 端点)
│ │ ├── EvaluationFacade.java # /api/v2/assessment/evaluation
│ │ ├── TaskFacade.java # /api/v2/assessment/tasks (仪表板)
│ │ ├── PlanFacade.java # /api/v2/assessment/plans (仪表板)
│ │ ├── ResultFacade.java # /api/v2/assessment/results
│ │ ├── AppealFacade.java # /api/v2/assessment/appeals
│ │ └── NotificationFacade.java # /api/v2/notifications
│ ├── dto/ # 入参 (Request) — 多个 *Dto
│ ├── vo/ # 出参 (Response) — 多个 *Vo
│ └── assembler/ # MapStruct 转换器 — 多个 *Assembler
│
├── application/ # 应用层（事务边界 + Command/Query 编排）
│ ├── command/ # 写命令对象 — *Command
│ │ ├── CreateDimensionCommand / UpdateDimensionCommand # +assessType
│ │ ├── CreateIndicatorCommand / UpdateIndicatorCommand # +targetValue/unit/scoringType/scoringConfig, idxType→String
│ │ ├── CreateTemplateBasicCommand # [v2新增] 仅名称/部门/考核类型
│ │ ├── CreateTemplateCommand / UpdateTemplateCommand # details+options 替代 dimensions
│ │ └── SaveEvaluationCommand # actualValue/textValue 替代 score/content
│ ├── query/ # CQRS 查询返回 View — *View
│ │ ├── DimensionView # +assessType
│ │ ├── IndicatorView / IndicatorOptionView # v2 字段
│ │ ├── TemplateDetailView / TemplateOptionView # [v2新增] 替代 TemplateDimensionView
│ │ ├── TemplateView # details+totalWeight 替代 dimensions
│ │ └── EvaluationFormView # v2: scoringType/targetValue/unit/currentActualValue/currentTextValue/currentCalScore
│ └── service/
│ ├── DimensionAppService # +search() +listByDeptAndAssessType()
│ ├── IndicatorAppService # v2字段适配
│ ├── TemplateAppService # +createBasic() create/update用TemplateDetail/Option快照
│ ├── CampaignAppService # calculateScores 适配
│ ├── EvaluationAppService # [v2] 集成ScoringEngine, computeDetails()自动计算calScore+dimScore
│ └── AppealAppService
│
├── domain/ # 领域层（充血模型）
│ ├── auth/
│ │ └── service/ # AuthSessionPort, PasswordHasher (端口)
│ ├── system/ # 【系统管理域】Department/User/Role/Resource
│ │ ├── model/{entity,valobj,aggregate}/
│ │ ├── service/ # DepartmentDomainService
│ │ └── repository/ # I*Repository 4 个
│ ├── assessment/ # 【考核执行域 — v2 重构】
│ │ ├── model/
│ │ │ ├── entity/ # Dimension(+assessType)/Indicator(+targetValue/unit/scoringType/scoringConfig)/IndicatorOption(20字段)/Template(+assessType/deptCode)/TemplateDetail[v2新增]/TemplateOption[v2新增]/Campaign/CampaignRelation/EvaluationTask/EvaluationDetail(actualValue/textValue/calScore/dimScore)/ResultSummary/ResultDimension/ResultComment/Appeal
│ │ │ ├── valobj/ # AssessType[v2新增]/ScoringType[v2新增]/IndicatorType(QUAN/QUAL)/IndicatorDomain/TemplateStatus/RaterType/CampaignStatus/TaskStatus
│ │ │ └── aggregate/ # TemplateAggregate(details+options) + CampaignAggregate + ResultAggregate
│ │ ├── service/
│ │ │ ├── TemplateDomainService # validateDimensionWeights 支持1.0和100
│ │ │ ├── CampaignDomainService / CampaignGenerateService
│ │ │ ├── ScoreCalculationService # [v2] 通过taskId关联取assesseeId/raterType, 用calScore
│ │ │ └── scoring/ # [v2新增] 打分引擎
│ │ │ ├── ScoringStrategy.java # 策略接口
│ │ │ ├── DirectScoreStrategy.java # 直接打分
│ │ │ ├── RatioStrategy.java # 比率法
│ │ │ ├── StepStrategy.java # 区间法
│ │ │ ├── AddSubStrategy.java # 加减分法
│ │ │ ├── QualLevelStrategy.java # 定性等级法
│ │ │ └── ScoringEngine.java # 路由器
│ │ ├── repository/ # IDimension(+search)/IIndicator/IIndicatorOption/ITemplate/ITemplateDetail[v2新增]/ITemplateOption[v2新增]/ICampaign/ICampaignRelation/IEvaluationTask/IEvaluationDetail/IResultSummary/IResultDimension/IResultComment/IAppeal
│ │ └── port/ # OrgUserQueryPort + EvaluationFormQueryPort(v2:templateDetailId/scoringType/targetValue/unit/20字段OptionNode)
│ └── notification/
│ ├── model/Notification.java
│ └── repository/INotificationRepository.java
│
└── infrastructure/ # 基础设施层
├── persistence/
│ ├── dataobject/ # AssessDimensionDO(+assessType)/AssessIndicatorDO(+targetValue/unit/scoringType/scoringConfig,idxType→String)/AssessIndicatorOptionDO(20字段)/AssessTemplateDO(+assessType/deptCode)/AssessTemplateDetailDO[v2新增]/AssessTemplateOptionDO[v2新增]/AssessEvaluationDetailDO(actualValue/textValue/calScore/dimScore) + sys DOs
│ ├── mapper/ # AssessTemplateDetailMapper[v2新增]/AssessTemplateOptionMapper[v2新增]; AssessTemplateDimensionMapper[已删除]
│ ├── converter/ # TemplateDetailConverter[v2新增]/TemplateOptionConverter[v2新增]; TemplateDimensionConverter[已删除]
│ └── repository/ # TemplateDetailRepositoryImpl[v2新增]/TemplateOptionRepositoryImpl[v2新增]; TemplateDimensionRepositoryImpl[已删除]
├── bridge/ # OrgUserQueryPortImpl + EvaluationFormQueryPortImpl(v2:查template_detail+template_option)
└── security/
### 4. 编码强制规范
### 后端Java规范
1. 严格DDD分层，领域层不能依赖Web框架，不能注入Controller
2. 禁止在Controller写业务判断，所有评分、权限校验逻辑下沉到Domain领域服务
3. 入参统一使用DTO，数据库实体只在领域层使用，不对外暴露
4. Sa-Token上下文必须在网关统一初始化，Feign远程调用自动传递Token
5. 所有SQL使用MyBatis-Plus Lambda写法，禁止手写硬编码SQL
6. 异常统一抛出自定义业务异常，全局统一捕获返回固定格式：{code,msg,data}
### 前端TS规范
1. 开启strict严格模式，禁止使用any类型，统一用泛型约束接口返回值
2. 组件全部为函数组件+React Hook，不写Class组件
3. API请求统一封装在services文件夹，页面只调用hooks，不直接写axios
4. 树形组织组件统一复用Tree组件，不要重复封装
5. 表格组件使用全局封装的通用ProTable，统一实现筛选、分页、导出
### 5. 本项目专属业务规则（最重要记忆项）
### 权限规则
1. 功能权限：基于角色编码判断；数据权限：自动过滤当前租户+所属部门数据
2. 普通员工仅能查看本人绩效；部门经理查看本部门所有员工；管理员全量数据
### 考核评分业务规则
1. 考核总分 = 定量指标得分 * 权重 + 定性评价得分
2. 已提交评审的考核记录不允许修改，只能走驳回流程
3. 考核周期一旦开启，指标库不允许删除，只能新增版本
### 流程约束
1. 绩效审批全部使用bpmn-js绘制流程图，由Camunda执行流转
2. 流程节点执行人自动从组织架构获取直属上级，禁止硬编码账号
### 6. 开发命令清单（只允许执行以下命令）
### 后端
mvn clean compile # 编译检查
mvn spring-boot:run # 启动后端服务
mvn flyway:migrate # 执行数据库版本迁移
### 前端
pnpm install # 安装依赖
pnpm dev # 启动前端，端口3100
pnpm build # 生产打包
pnpm lint # ESLint代码检查
### 7. 禁止操作清单
1. 禁止修改 infrastructure 防腐层代码，外部依赖统一在防腐层隔离
2. 禁止直接修改数据库实体字段，必须先更新Flyway迁移脚本
3. 禁止在前端硬编码接口地址，统一使用环境变量
4. 禁止跨层引入依赖：领域层不能依赖应用层与接口层
5. 不要改动全局权限拦截器，所有权限配置写在路由meta注解中
### 8. 调试经验沉淀（自动记忆补充项）
> 本条会自动同步到Auto Memory，下次会话自动生效
1. Sa-Token在Gateway网关必须开启上下文同步，否则Feign调用丢失会话
2. Camunda流程实例需要绑定tenant_id，防止多租户流程串数据
3. 前端树形组织懒加载，必须传递parentId，一次性加载全量树会卡顿
三、配套自动记忆（Auto Memory）补充
开发绩效管理系统，Claude会自动生成3份经验笔记，存放在内存目录：
- MEMORY.md（主记忆）
自动记录：DDD分层踩坑、多租户SQL写法、Sa-Token微服务会话共享解决方案、前后端联调跨域代理配置。 - debugging.md
自动记录：Camunda流程无法驳回、树形组件回显异常、Feign序列化SaSession失败等Bug修复方案。 - api-conventions.md
自动沉淀绩效系统统一接口格式、分页参数、租户自动注入规则。
四、总结
- CLAUDE.md只写不变的规则
架构、分层、业务边界、编码规范写在这里；临时调试、临时方案不要写入，放到CLAUDE.local.md。 - 拆分长短记忆
长期架构写CLAUDE.md，临时经验交给Auto Memory，不要把几万字文档塞进记忆文件。 - 业务规则单独切块
像绩效评分、审批流转这类核心业务逻辑，单独开辟章节，模型优先级最高。 - 严格控制行数
CLAUDE.md保持在300~500行，精简凝练，规则越少，模型遵守度越高。 - 项目总体逻辑复杂度不高，所以本项目claude.md 没有做的很复杂，更规范的做法是按域、分层建立claude.md,在另一个项目中会采用更复杂的记忆系统，等项目完成再分享。
欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。
更多推荐
0
0- 0
已为社区贡献1条内容
所有评论(0)