首页/资讯中心/详情

claude code 开发实践 - 生产级别的项目规范

claude code 开发实践 - 生产级别的项目规范
📅 发布时间：2026/7/2 10:49:32

Claude Code 开发规范

博主是某个技术团队的负责人，团队规模中等（50人+），今年开始团队成员应用AI辅助编程的越来越多，效率提升的同时也逐渐暴露出很多问题：

  • AI 生成代码出现架构不统一、编码规范混乱、业务逻辑偏离设计、重复口述项目背景、上下文冗余膨胀等问题;
  • 同时缺少标准化 AI能力管控手段，不同成员使用习惯差异大，代码返工、架构破坏风险持续上升。

为统一全团队 AI 开发标准，结合团队特点和自身关于vibe coding的思考和实践， 特制定本套完整开发规范：

  • 文档统一AI工具，约定仓库 AI 配置目录层级，明确四层记忆文件权责与提交规则，标准化技能包、审核子 Agent、全局拦截钩子模板，配套项目迭代专属 Prompt 沉淀机制。
  • 通过标准化约束固化项目架构、DDD 分层、业务红线与编码规范，降低 AI 上下文损耗，统一代码产出质量，沉淀可复用 AI 开发资产，实现 AI 辅助开发可管控、可沉淀、可协同，保障长期迭代架构一致性。

注：希望本文档对大家有一定的帮助，当然没有放之四海而皆准的规范，不同团队都需要结合自设特点进行调整，本文涉及的规范也是博主团队最初的一个版本，结合项目实际后期也做了很多调整。

文档说明

  1. 适用对象：全栈研发团队，统一 AI 工具：Claude Code（CLI + VSCode 插件）
  2. 核心目标：统一 AI 记忆、统一工具调用逻辑、统一 Agent 协作模式、沉淀可复用业务 Prompt，降低 AI 产出代码的返工率，保证项目架构一致性
  3. 核心组件覆盖：分层记忆体系（CLAUDE.md / CLAUDE.local.md / MEMORY 自动记忆）、自定义 Skills、子 Agent（Sub Agent）、全局 Hooks、迭代式业务 Prompt
  4. 所有规范配套标准 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自动分片

强制约束

  1. CLAUDE.md 是项目宪法：所有 AI 生成代码必须优先遵守，冲突时以本文件规则为准；
  2. 不变架构、业务规则、分层约束写入CLAUDE.md；临时调试、本地环境全部放入CLAUDE.local.md；
  3. 禁止在会话中反复口述项目基础信息，新增会话前必须保证CLAUDE.md更新到位；
  4. 自动记忆仅作辅助，架构变更必须同步更新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. store：Zustand全局状态，按业务域拆分 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 模板2：CLAUDE.local.md 本地私有模板

# 本地私有记忆（不提交Git，仅本机生效） ## 1. 本地环境配置 后端本地端口：8080 前端本地端口：3100 本地数据库地址：127.0.0.1:3306 本地测试租户ID：local_001 ## 2. 临时豁免规则（仅本机调试） 1. 本地调试阶段允许跳过租户过滤校验，生产代码必须删除 2. 允许打印完整SQL日志，上线代码移除所有sysout打印 ## 3. 个人AI偏好 默认流式输出，工具执行前强制弹窗确认文件写入操作

三、Skills 技能包规范（.claude/skills/）

3.1 使用规范

  1. 按技术领域拆分技能，单一技能只解决一类固定开发场景；
  2. 技能 = 标准化提示词 + 固定工具调用组合，开发时通过/skill xxx一键加载；
  3. 新增业务通用能力必须封装为Skill，禁止每次会话重复写相同规则；
  4. Skill 内部不修改项目基础架构，仅标准化代码生成格式。

3.2 Skill 标准模板示例：.claude/skills/ddd-java/skill.md

# Skill：DDD 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 团队使用规则

  1. 主Agent负责整体任务调度，子Agent单一职责，禁止一个子Agent同时做代码生成+SQL评审；
  2. 复杂任务必须拆分子Agent串行执行：需求梳理 → 接口设计Agent → SQL审核Agent → 代码生成 → 代码评审Agent；
  3. 子Agent独立上下文，执行完成仅将摘要结论返回主会话，不把完整执行日志灌入主上下文，避免Token爆炸；
  4. 高危操作（SQL、代码修改、重构）强制启用对应子Agent校验，未经过子Agent审核的代码禁止落地。

4.2 Sub Agent 标准模板示例：.claude/sub-agents/sql-review.agent.md

# 子Agent：SQL&MyBatis代码审核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 钩子分层与执行时机

  1. pre-query.hook.md：调用模型前执行，预处理上下文、裁剪冗余历史、校验记忆完整性
  2. post-tool.hook.md：任意工具执行完成后执行，校验工具输出是否符合规范
  3. 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 管理规则

  1. 按场景分类：初始化、CRUD开发、重构、Bug修复；
  2. 版本迭代专属Prompt放入version-iter/，每次迭代更新专属业务约束；
  3. 迭代需求变更时，优先更新对应迭代Prompt，再发起AI会话；
  4. 通用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 开发流程标准化

  1. 会话初始化
    打开项目自动加载CLAUDE.md+ 全局hooks；本地环境加载CLAUDE.local.md；
  2. 加载对应能力
    根据开发场景加载对应Skill；复杂任务自动绑定对应Sub Agent；
  3. 导入迭代Prompt
    读取当前迭代版本专属Prompt，同步本次迭代业务需求；
  4. AI生成代码
    文件写入自动触发file-write hook拦截校验；SQL自动走sql-review子Agent；
  5. 后置审核
    代码生成完成调用code-review子Agent输出评审报告；
  6. 迭代沉淀
    开发完成后，关键架构变更同步更新CLAUDE.md；高频踩坑点由团队统一补充至对应Skill/Prompt。

八、团队违规处理原则

  1. 未配置CLAUDE.md直接使用AI生成代码，产出代码一律返工；
  2. 复杂SQL、重构未使用对应子Agent审核，禁止提交代码；
  3. 新增业务模块未封装Skill，重复冗余Prompt，纳入代码评审问题；
  4. 本地临时规则写入项目CLAUDE.md并提交Git，直接回滚修改；
  5. AI生成代码违反分层架构、业务规则，开发人承担全部整改工作量。

九、详细说明Claude code 文件加载机制以及如何发起一个新的需求

9.1 Claude Code 自动加载规则：哪些文件会自动载入

9.1.1 自动加载（无需手动指令，打开项目会话即生效）
（1）记忆类文件（全自动读取）
  1. ./CLAUDE.md：项目根目录必读，完整加载全文，作为全局最高优先级规则；
  2. ./CLAUDE.local.md：存在则自动加载，优先级高于项目CLAUDE.md，仅本地生效；
  3. 全局用户记忆~/.claude/CLAUDE.md：全局兜底，优先级最低；
  4. 自动记忆MEMORY.md / debugging.md：会话启动预加载前200行，剩余按需分片读取。
（2）.claude/hooks全局钩子（全自动挂载）

目录下所有*.hook.md文件会话初始化自动全部注册，无需手动启用：

  • pre-query：每次请求模型前自动执行；
  • file-write：每次读写文件工具触发拦截；
  • post-tool：任意工具调用结束自动校验。
    钩子属于运行时强制逻辑，全程静默生效，不受手动开关控制。
9.1.2. 不会自动加载，必须手动触发的文件
  1. .claude/skills/技能包：不会自动加载，必须手动/skill xxx载入；
  2. .claude/sub-agents/子Agent：不会自动激活，需手动指令调用；
  3. .claude/prompts/下所有通用/迭代版本Prompt：无自动匹配逻辑，需要手动导入。

9.2 Claude Code 如何识别、加载子Agent？

9.2.1 不会自动识别当前业务并加载对应子Agent

无自动路由机制，子Agent是按需手动调用，两种标准调用方式：

  1. 指令式：/agent sql-review
  2. 任务内显式声明：需求描述中写明“执行sql-review子Agent校验SQL”
9.2.2 子Agent加载逻辑
  1. 检索路径：固定读取./.claude/sub-agents/*.agent.md；
  2. 隔离上下文：子Agent启动独立微型会话，仅传入当前待校验片段；
  3. 输出收敛：仅返回摘要结论，完整执行日志不灌入主会话上下文，防止Token膨胀；
  4. 无常驻机制：执行完毕即销毁，下次使用需要重新调用。
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增加迭代版本识别规则，统一约定版本标记：

  1. 约定项目根目录存在ITERATION.md，记录当前迭代号；
  2. pre-query钩子启动时自动读取ITERATION.md获取版本；
  3. 自动拼接路径加载对应迭代prompt文件注入上下文；
    示例钩子逻辑：
会话初始化自动读取项目根目录ITERATION.md，提取当前迭代版本号； 自动加载 .claude/prompts/version-iter/{版本号}.prompt.md 并入会话上下文； 若文件不存在，提示手动导入迭代Prompt。

9.4 整体加载优先级与执行顺序（完整时序）

  1. 加载全局用户记忆~/.claude/CLAUDE.md
  2. 加载项目长期记忆./CLAUDE.md
  3. 加载本地私有记忆./CLAUDE.local.md
  4. 自动注册全部.claude/hooks钩子，全程生效
  5. 预加载自动记忆MEMORY前200行
  6. 触发pre-query钩子：
    • 读取迭代标识，自动注入对应版本Prompt
    • 识别任务类型，自动调度对应子Agent校验
  7. 用户输入需求，手动加载skills技能包辅助开发
  8. 工具执行时触发file-write/post-tool钩子校验代码规范
  9. 代码完成后自动调用code-review子Agent评审