Claude Code 开发规范博主是某个技术团队的负责人团队规模中等50人今年开始团队成员应用AI辅助编程的越来越多效率提升的同时也逐渐暴露出很多问题AI 生成代码出现架构不统一、编码规范混乱、业务逻辑偏离设计、重复口述项目背景、上下文冗余膨胀等问题;同时缺少标准化 AI能力管控手段不同成员使用习惯差异大代码返工、架构破坏风险持续上升。为统一全团队 AI 开发标准结合团队特点和自身关于vibe coding的思考和实践 特制定本套完整开发规范文档统一AI工具约定仓库 AI 配置目录层级明确四层记忆文件权责与提交规则标准化技能包、审核子 Agent、全局拦截钩子模板配套项目迭代专属 Prompt 沉淀机制。通过标准化约束固化项目架构、DDD 分层、业务红线与编码规范降低 AI 上下文损耗统一代码产出质量沉淀可复用 AI 开发资产实现 AI 辅助开发可管控、可沉淀、可协同保障长期迭代架构一致性。注希望本文档对大家有一定的帮助当然没有放之四海而皆准的规范不同团队都需要结合自设特点进行调整本文涉及的规范也是博主团队最初的一个版本结合项目实际后期也做了很多调整。文档说明适用对象全栈研发团队统一 AI 工具Claude CodeCLI VSCode 插件核心目标统一 AI 记忆、统一工具调用逻辑、统一 Agent 协作模式、沉淀可复用业务 Prompt降低 AI 产出代码的返工率保证项目架构一致性核心组件覆盖分层记忆体系CLAUDE.md / CLAUDE.local.md / MEMORY 自动记忆、自定义 Skills、子 AgentSub Agent、全局 Hooks、迭代式业务 Prompt所有规范配套标准 MD 模板可直接落地到任意业务仓库示例项目通用绩效管理 DDD 微服务系统该项目业务聚焦域边界清晰前后端代码90%由AI实现一、仓库根目录规范层级所有业务仓库必须遵循以下固定目录AI 相关文件统一收拢禁止散落文件PROJECTY-NAME(项目根仓库)/ ├── CLAUDE.md # 项目级长期静态记忆团队统一提交Git ├── CLAUDE.local.md # 本地私有记忆.gitignore个人环境/临时调试规则 ├── .claude/ # AI能力配置根目录统一存放Skills、Hooks、子Agent定义 │ ├── skills/ # 可复用技能包按业务/技术分类 │ │ ├── ddd-java/ # DDD后端编码技能 │ │ ├── react-admin/ # 中后台前端组件开发技能 │ │ ├── bpmn-camunda/ # 流程引擎开发技能 │ │ └── common-lint/ # 代码校验、重构通用技能 │ ├── sub-agents/ # 如果由子Agent按单一职责拆分 │ │ ├── sql-review.agent.md # SQL审核子Agent │ │ ├── api-design.agent.md # 接口设计子Agent │ │ ├── code-review.agent.md # 代码评审子Agent │ │ └── bug-debug.agent.md # 故障定位子Agent │ ├── hooks/ # 全局生命周期钩子全局生效 │ │ ├── pre-query.hook.md # AI发起模型请求前预处理钩子 │ │ ├── post-tool.hook.md # 工具执行完成后后置校验钩子 │ │ └── file-write.hook.md # 文件写入拦截钩子权限/规范校验 │ └── prompts/ # 项目迭代持续沉淀业务Prompt库 │ ├── init-project.prompt.md # 新项目初始化Prompt │ ├── crud-dev.prompt.md # 单模块CRUD开发Prompt │ ├── refactor.prompt.md # 代码重构Prompt │ ├── bug-fix.prompt.md # 线上问题修复Prompt │ └── version-iter/ # 按迭代版本存放迭代专属Prompt │ ├── v1.0-kpi.prompt.md │ └── v1.1-report.prompt.md ├── backend/ # 后端项目 ├── frontend/ # 前端项目 ├── scripts/ # 脚本代码 └── .gitignore # 文件统一忽略二、分层记忆系统规范2.1 四层记忆使用规则强制记忆层级文件归属Git提交核心用途行数限制全局个人记忆~/.claude/CLAUDE.md个人本机不提交个人编码习惯、全局代理、默认模型、通用工具偏好≤300行项目团队长期记忆仓库根目录/CLAUDE.md全团队必须提交项目架构、DDD分层、技术栈、业务边界、编码红线、目录规范≤600行本地临时记忆仓库根目录/CLAUDE.local.md个人本地禁止提交本机端口、本地数据库、临时调试开关、临时豁免规则≤200行AI自动沉淀记忆MEMORY.md / debugging.mdAI自动生成禁止提交自动记录踩坑、接口约定、Bug修复方案无强制限制AI自动分片强制约束CLAUDE.md 是项目宪法所有 AI 生成代码必须优先遵守冲突时以本文件规则为准不变架构、业务规则、分层约束写入CLAUDE.md临时调试、本地环境全部放入CLAUDE.local.md禁止在会话中反复口述项目基础信息新增会话前必须保证CLAUDE.md更新到位自动记忆仅作辅助架构变更必须同步更新CLAUDE.md不能依赖 AI 自动记忆。2.2 模板1项目根目录/ CLAUDE.md 标准模板示例项目绩效管理系统# 【项目长期记忆】通用绩效管理系统 ## 1. 项目基础信息 1. 业务定位多租户企业绩效考核DDD微服务平台 2. 技术栈后端SpringBoot3 DDD分层 Sa-Token maybatisplus前端React19 TS Zustand Ant Design v6 3. 仓库结构backend 后端服务; frontend 前端服务 4. 会话模型默认glm-5.1复杂架构重构切换opus glm-5.2 ## 2. 强制分层架构禁止跨层依赖 ### 后端DDD四层 1. facade层Controller、入参校验、权限拦截仅做请求转发无业务逻辑 2. application应用层命令编排、事务、DTO转换、跨服务调用 3. domain领域层聚合根、实体、领域服务、核心评分业务规则业务代码唯一合法存放处 4. Infrastructure基础设施层数据库、Redis、Feign防腐层隔离外部依赖 ### 前端分层 1. route路由配置meta携带权限标识 2. storeZustand全局状态按业务域拆分 3. api统一axios请求封装 4. pages业务页面复用公共组件 5. hooks: 自定义hooks 6. components通用业务组件、基础封装组件 ## 3. 数据库统一规范 1. 所有表必带id, tenant_id, create_time, update_time, deleted逻辑删除 2. 多租户自动注入tenant_id禁止接口手动传租户ID 3. 禁止手写原生SQL统一MyBatis-Plus Lambda ## 4. 业务强制规则 1. 已提交考核记录不可直接修改仅支持驳回重提流程 2. 数据权限员工仅查看本人部门经理查看本部门管理员全量 3. 指标权重计算逻辑统一在Domain领域服务不允许写在接口/前端 ## 5. 编码红线 1. 禁止Domain层依赖Web、Feign、Controller相关类 2. 禁止前端硬编码接口地址、令牌、租户ID 3. 禁止直接修改数据库实体新增字段必须补充Flyway迁移脚本 4. 禁止AI自动执行高危shell命令rm -rf、数据库drop等必须人工确认 ## 6. 项目标准命令 ### 后端 mvn spring-boot:run 启动服务 mvn flyway:migrate 执行数据库迁移 ### 前端 pnpm dev 3100端口启动 pnpm lint 代码校验 ## 7. AI工具使用约束 1. 复杂代码重构必须启用code-review子Agent审核 2. SQL生成必须调用sql-review子Agent校验多租户、性能 3. 新增业务模块优先使用ddd-java技能包生成标准DDD代码 4. 所有文件写入触发file-write全局hook自动校验规范2.3 模板2CLAUDE.local.md 本地私有模板# 本地私有记忆不提交Git仅本机生效 ## 1. 本地环境配置 后端本地端口8080 前端本地端口3100 本地数据库地址127.0.0.1:3306 本地测试租户IDlocal_001 ## 2. 临时豁免规则仅本机调试 1. 本地调试阶段允许跳过租户过滤校验生产代码必须删除 2. 允许打印完整SQL日志上线代码移除所有sysout打印 ## 3. 个人AI偏好 默认流式输出工具执行前强制弹窗确认文件写入操作三、Skills 技能包规范.claude/skills/3.1 使用规范按技术领域拆分技能单一技能只解决一类固定开发场景技能 标准化提示词 固定工具调用组合开发时通过/skill xxx一键加载新增业务通用能力必须封装为Skill禁止每次会话重复写相同规则Skill 内部不修改项目基础架构仅标准化代码生成格式。3.2 Skill 标准模板示例.claude/skills/ddd-java/skill.md# SkillDDD Java 后端代码生成 ## 适用场景 新增领域聚合、新增业务模块、生成facade/Application/Domain/Infrastructure分层代码 ## 强制输出规范 1. 严格四层分层输出每层代码分开标注文件路径 2. Domain实体只包含业务属性不关联数据库注解 3. Application层接收Command入参返回DTO不暴露数据库实体 4. Infrastructure层实现Repository防腐MyBatis操作统一放在Infra 5. 自动注入多租户tenant_id逻辑逻辑删除自动拼接条件 ## 输出格式要求 1. 先输出模块目录结构 2. 分层输出完整可运行代码附带注释 3. 结尾输出mvn编译校验命令提示人工核对迁移脚本 4. 禁止生成任何将业务逻辑写在facade的代码四、Sub Agent 子Agent 统一规范.claude/sub-agents/4.1 团队使用规则主Agent负责整体任务调度子Agent单一职责禁止一个子Agent同时做代码生成SQL评审复杂任务必须拆分子Agent串行执行需求梳理 → 接口设计Agent → SQL审核Agent → 代码生成 → 代码评审Agent子Agent独立上下文执行完成仅将摘要结论返回主会话不把完整执行日志灌入主上下文避免Token爆炸高危操作SQL、代码修改、重构强制启用对应子Agent校验未经过子Agent审核的代码禁止落地。4.2 Sub Agent 标准模板示例.claude/sub-agents/sql-review.agent.md# 子AgentSQLMyBatis代码审核Agent ## 职责 接收生成的SQL语句、MyBatis-Plus查询代码完成合规性校验并输出审核报告 ## 校验规则 1. 校验是否自动携带tenant_id多租户过滤条件 2. 校验是否拼接deleted逻辑删除条件 3. 禁止select *必须明确字段 4. 大表查询强制校验索引、分页参数 5. 禁止delete、update无where条件语句 ## 输出格式 ### 【SQL审核结果】 1. 合规项xxx 2. 风险项xxx风险等级/修改建议 3. 修改后标准SQL代码 ## 执行约束 发现高危SQL直接阻断返回不允许落地必须修复后再生成代码五、全局 Hooks 钩子规范.claude/hooks/5.1 钩子分层与执行时机pre-query.hook.md调用模型前执行预处理上下文、裁剪冗余历史、校验记忆完整性post-tool.hook.md任意工具执行完成后执行校验工具输出是否符合规范file-write.hook.md文件写入/编辑前拦截强制校验编码规范、目录约束5.2 模板示例.claude/hooks/file-write.hook.md# 文件写入前置拦截Hook ## 触发时机 调用writeFile/edit工具写入代码文件前自动执行 ## 校验逻辑 1. 校验文件存放路径是否符合项目CLAUDE.md目录规范禁止新建非法目录 2. Java代码校验DDD分层依赖禁止跨层导入 3. TS代码校验any类型、组件规范 4. 检测是否包含硬编码租户ID、密钥、本地端口等敏感信息 ## 拦截策略 存在违规项直接拒绝写入输出整改清单待人工调整后重新执行六、项目迭代持续 Prompt 库规范.claude/prompts/6.1 管理规则按场景分类初始化、CRUD开发、重构、Bug修复版本迭代专属Prompt放入version-iter/每次迭代更新专属业务约束迭代需求变更时优先更新对应迭代Prompt再发起AI会话通用Prompt全项目复用迭代专属Prompt仅当前版本生效。6.2 模板示例.claude/prompts/crud-dev.prompt.md# 通用CRUD开发迭代Prompt ## 前置要求 1. 读取项目CLAUDE.md完整架构规则 2. 自动加载ddd-java、react-admin技能包 3. 生成SQL后自动调用sql-review子Agent审核 4. 代码生成完成后调用code-review子Agent评审 ## 开发步骤强制流程 1. 梳理当前模块业务实体、字段、业务约束 2. 输出数据库表结构 Flyway迁移脚本 3. 子Agent审核SQL通过后生成后端DDD四层完整代码 4. 生成前端TS类型、Zustand状态、API请求、页面组件 5. 输出单元测试基础代码 6. 输出启动验证命令给出自测步骤 ## 输出约束 所有代码严格遵循项目分层规则多租户、逻辑删除自动处理不输出冗余注释6.3 迭代版本Prompt示例.claude/prompts/version-iter/v1.0-kpi.prompt.md# V1.0 绩效管理系统迭代专属Prompt ## 本次迭代业务范围 1. 考核方案配置模块 2. 员工自评上级审批BPMN流程 3. 绩效分数统计报表 ## 迭代新增特殊约束 1. 考核指标分为定量/定性两类两套计算逻辑分开实现 2. 流程节点支持动态配置审批层级不可写死2级审批 3. 报表查询需支持按部门、考核周期多维度筛选统一封装查询条件 ## AI开发顺序约束 1. 先设计指标库实体与数据库表 2. 开发领域层分数计算规则 3. 开发Camunda流程定义与执行逻辑 4. 开发前端配置页面、报表页面 5. 全量代码评审子Agent校验后输出最终代码七、团队 AI 开发流程标准化会话初始化打开项目自动加载CLAUDE.md 全局hooks本地环境加载CLAUDE.local.md加载对应能力根据开发场景加载对应Skill复杂任务自动绑定对应Sub Agent导入迭代Prompt读取当前迭代版本专属Prompt同步本次迭代业务需求AI生成代码文件写入自动触发file-write hook拦截校验SQL自动走sql-review子Agent后置审核代码生成完成调用code-review子Agent输出评审报告迭代沉淀开发完成后关键架构变更同步更新CLAUDE.md高频踩坑点由团队统一补充至对应Skill/Prompt。八、团队违规处理原则未配置CLAUDE.md直接使用AI生成代码产出代码一律返工复杂SQL、重构未使用对应子Agent审核禁止提交代码新增业务模块未封装Skill重复冗余Prompt纳入代码评审问题本地临时规则写入项目CLAUDE.md并提交Git直接回滚修改AI生成代码违反分层架构、业务规则开发人承担全部整改工作量。九、详细说明Claude code 文件加载机制以及如何发起一个新的需求9.1 Claude Code 自动加载规则哪些文件会自动载入9.1.1 自动加载无需手动指令打开项目会话即生效1记忆类文件全自动读取./CLAUDE.md项目根目录必读完整加载全文作为全局最高优先级规则./CLAUDE.local.md存在则自动加载优先级高于项目CLAUDE.md仅本地生效全局用户记忆~/.claude/CLAUDE.md全局兜底优先级最低自动记忆MEMORY.md / debugging.md会话启动预加载前200行剩余按需分片读取。2.claude/hooks全局钩子全自动挂载目录下所有*.hook.md文件会话初始化自动全部注册无需手动启用pre-query每次请求模型前自动执行file-write每次读写文件工具触发拦截post-tool任意工具调用结束自动校验。钩子属于运行时强制逻辑全程静默生效不受手动开关控制。9.1.2. 不会自动加载必须手动触发的文件.claude/skills/技能包不会自动加载必须手动/skill xxx载入.claude/sub-agents/子Agent不会自动激活需手动指令调用.claude/prompts/下所有通用/迭代版本Prompt无自动匹配逻辑需要手动导入。9.2 Claude Code 如何识别、加载子Agent9.2.1 不会自动识别当前业务并加载对应子Agent无自动路由机制子Agent是按需手动调用两种标准调用方式指令式/agent sql-review任务内显式声明需求描述中写明“执行sql-review子Agent校验SQL”9.2.2 子Agent加载逻辑检索路径固定读取./.claude/sub-agents/*.agent.md隔离上下文子Agent启动独立微型会话仅传入当前待校验片段输出收敛仅返回摘要结论完整执行日志不灌入主会话上下文防止Token膨胀无常驻机制执行完毕即销毁下次使用需要重新调用。9.2.3 团队使用规范在pre-query.hook.md增加前置识别逻辑实现半自动触发每次发起任务前自动识别任务类型 1. 需求包含建表/MyBatis/SQL → 自动调用sql-review子Agent 2. 完成代码生成后自动调用code-review子Agent 3. 重构、大批量文件修改强制启动bug-debug子Agent。钩子仅做自动发起调用指令底层仍依赖手动Agent加载逻辑只是省去人工输入命令。9.3 如何识别当前迭代、自动加载对应版本Prompt原生不存在读取git分支、迭代标记、自动匹配对应prompt文件的逻辑两种可行的方案方案1人工显式导入基础规范流程每次开发前固定执行指令/prompt .claude/prompts/version-iter/v1.2-kpi-limit.prompt.md执行后文件全文注入本次会话上下文。方案2团队使用规范基于Hook半自动绑定目前未按次规范实施在pre-query.hook.md增加迭代版本识别规则统一约定版本标记约定项目根目录存在ITERATION.md记录当前迭代号pre-query钩子启动时自动读取ITERATION.md获取版本自动拼接路径加载对应迭代prompt文件注入上下文示例钩子逻辑会话初始化自动读取项目根目录ITERATION.md提取当前迭代版本号 自动加载 .claude/prompts/version-iter/{版本号}.prompt.md 并入会话上下文 若文件不存在提示手动导入迭代Prompt。9.4 整体加载优先级与执行顺序完整时序加载全局用户记忆~/.claude/CLAUDE.md加载项目长期记忆./CLAUDE.md加载本地私有记忆./CLAUDE.local.md自动注册全部.claude/hooks钩子全程生效预加载自动记忆MEMORY前200行触发pre-query钩子读取迭代标识自动注入对应版本Prompt识别任务类型自动调度对应子Agent校验用户输入需求手动加载skills技能包辅助开发工具执行时触发file-write/post-tool钩子校验代码规范代码完成后自动调用code-review子Agent评审