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.git1.1 四层记忆分层模型加载优先级由低→高高层覆盖低层冲突记忆分为长期静态记忆人工编写 中期自动记忆AI自学 短期会话记忆三层核心文件就是项目根目录下的CLAUDE.md。层级文件写入者存放路径生效时机作用定位第1层全局用户记忆CLAUDE.md开发者~/.claude/CLAUDE.md每次会话启动自动加载个人通用编码习惯、语言、全局工具配置第2层项目团队记忆核心项目根目录/CLAUDE.md团队开发者Git版本管控项目仓库根目录会话必加载全文读取无行数限制项目架构、技术栈、目录规范、业务约束、编码规则永久记忆跨会话不丢失第3层本地私有记忆CLAUDE.local.md个人本地项目根目录加入.gitignore会话加载本机环境、本地配置、临时调试规则不提交代码库第4层自动学习记忆MEMORY.md / debugging.mdClaude自动写入~/.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 # detailsoptions 替代 dimensions │ │ └── SaveEvaluationCommand # actualValue/textValue 替代 score/content │ ├── query/ # CQRS 查询返回 View — *View │ │ ├── DimensionView # assessType │ │ ├── IndicatorView / IndicatorOptionView # v2 字段 │ │ ├── TemplateDetailView / TemplateOptionView # [v2新增] 替代 TemplateDimensionView │ │ ├── TemplateView # detailstotalWeight 替代 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()自动计算calScoredimScore │ └── 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(detailsoptions) 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_detailtemplate_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,在另一个项目中会采用更复杂的记忆系统等项目完成再分享。