分享一个最新的 claude code 中 claude.md 写代码的规约文件，主要是避免 ai 进行发散开发。
# 项目开发规约
## 排查问题的基本原则（强制）
排查问题时**必须实际论证**，不允许通过下列方式绕过或伪装成"已解决"：
1. **禁止猜测式修复**
- 任何"我觉得可能是……"必须先通过日志、堆栈、断点、复现、单元测试或数据库查询等**实证手段**验证，再动手改代码。
- 无法复现或无证据的假设，不得作为提交依据。
2. **禁止用屏蔽/注释规避问题**
- 不允许通过 `try { ... } catch (Exception ignored) {}`、注释掉报错代码、`if (false)`、临时 `return`、删除断言/校验、关闭告警日志等方式让报错"消失"。
- 不允许把失败的测试用例 `@Disabled`、`@Ignore`、`skip`、注释掉，除非附有明确的 issue 链接与恢复计划。
- 不允许通过降级日志级别（ERROR → INFO/DEBUG）来隐藏异常。
3. **必须定位根因（Root Cause）**
- 每个 bug 的修复说明中要能回答：
- 现象是什么？如何复现？
- 根因在哪一行代码 / 哪一条数据 / 哪个配置？
- 为什么这样改能解决？是否引入新的副作用？
- 遇到"表面看起来好了但不确定为什么"的情况，视为**未解决**，继续排查。
4. **修复必须可验证**
- 提交前要有可复现的验证步骤：单元测试、集成测试、接口调用、SQL 结果、日志输出，任选其一并在提交说明或 PR 描述中给出。
- 关键路径 bug 修复应补充回归测试，防止再次发生。
5. **临时绕过必须显式标注**
- 如果确因外部依赖、时间窗口等原因必须临时绕过，需要：
- 用 `// TODO(bugfix-临时绕过): 原因 + 负责人 + 期限` 注明；
- 建立 issue 跟踪；
- 不得合并到 release 分支。
> 一句话：**先证据，后代码**；宁可多花时间定位根因，也不允许用注释、`ignore`、屏蔽日志等手段把问题藏起来。
---
## 防止随意改代码（强制）
### 一、变更范围
1. **最小改动原则**
- 只改与当前任务直接相关的代码，不做"顺手优化"。
- 单次变更聚焦一个目标，跨越多个模块的改动必须拆分。
2. **禁止未经授权的重构**
- 不允许在修 bug / 加功能的同时重命名函数、调整目录结构、改代码风格、抽公共方法。
- 重构必须是**独立任务**，单独提交、单独 PR。
3. **禁止改动"看起来没用"的代码**
- 不允许以"我觉得没用"为由删除代码、import、注释、日志、字段、配置项。
- 如果确信是死代码，必须先给出调用链/引用搜索证据，再单独提交删除。
4. **禁止扩大受影响文件集**
- 修改前先声明预计要改的文件；如果实施中发现要动更多文件，先停下来说明原因再继续。
### 二、破坏性变更
5. **公共 API / 接口签名保持向后兼容**
- Controller/Service/公共工具类的方法签名、返回值、字段名，未经确认不得修改。
- 需要变更时优先新增重载或新方法，标注 `@Deprecated`，不得原地改。
6. **数据库 / 迁移脚本**
- 不得随意修改已有的 DDL 脚本、Mapper XML 字段映射、实体类字段。
- 新增字段一律走新的迁移脚本，禁止改历史迁移。
7. **依赖与构建配置**
- `pom.xml` / `build.gradle` / `package.json` 的依赖版本、`application.yml` / `.env` / `settings.xml` 等配置，未经确认不得修改。
- 新增依赖需说明来源、用途、版本选择理由。
8. **框架 / 中间件配置**
- Spring、MyBatis、日志、线程池等基础设施配置属于"高影响面"，改动前必须先说明动机与影响范围。
### 三、测试与验证
9. **禁止改测试来让测试通过**
- 不允许修改断言、删除测试用例、放宽期望值来让红变绿。
- 测试失败先假设"代码有问题"，而不是"测试有问题"。
10. **禁止禁用 / 跳过测试**
- 不允许 `@Disabled`、`@Ignore`、`skip`、注释测试用例；例外情况必须挂 issue + 期限。
11. **不主动"重写"现有测试**
- 只允许**新增**测试；修改已有测试需说明原因（例如需求变更）。
### 四、Git 与产物
12. **不改 Git 历史**
- 已推送到远端的分支不得 `git rebase` / `git push --force` / `git commit --amend`；只有本地未推送的提交才允许调整。
13. **不动自动生成的代码**
- MyBatis Generator、Lombok delombok、OpenAPI 生成物、前端构建产物（`dist/`、`build/`）等禁止手改。
14. **不提交调试残留**
- `System.out.println` / `console.log` / `debugger` / 临时 TODO / 注释掉的代码块，提交前必须清理。
### 五、执行流程
15. **改动前先说明计划**
- 非平凡变更（>1 个文件 或 >20 行）在动手前，先用一段中文说明：目标、拟改的文件、预期影响、如何验证；得到确认后再实施。
16. **改动后自审 diff**
- 提交前先 `git diff` 通读一遍，逐处回答"这一行为什么必须改"；答不上来的，回滚该行。
17. **不确定就问，不要猜**
- 需求描述不清、字段含义不明、业务规则未知时，先问用户，禁止用"合理默认值"糊过去。
18. **保留现有实现风格**
- 命名、缩进、日志格式、异常处理模式，与周围代码保持一致；不引入新库、新范式、新架构分层。
> 一句话：**未授权不重构，未证据不删除，未确认不扩面**。
---
## 开发验证规范（强制）
### 一、变更后必须验证
1. **代码改动必须自测**
- 任何代码改动（新增/修改/删除）完成后，必须通过实际运行验证，不允许"理论正确"就提交。
- 验证方式根据改动类型选择：单元测试、接口调用、页面操作、日志观察，至少选一种。
2. **后端接口改动必须用 curl 测试**
- 新增或修改 Controller/Service 接口后，必须用 curl 或 httpie 发请求验证。
- 验证内容包括：正常入参、边界值、异常入参、权限校验、返回格式。
- curl 命令要保存在提交说明或 PR 描述里，便于复审时复现。
3. **数据库相关改动必须验证 SQL**
- 新增/修改 Mapper、SQL 语句后，必须在数据库客户端实际执行验证。
- 验证内容包括：语法正确、查询结果符合预期、索引是否命中（EXPLAIN）、性能是否可接受。
4. **前端改动必须在浏览器验证**
- UI/交互改动必须在浏览器中实际操作验证，不允许只看代码。
- 验证内容包括：正常流程、异常提示、边界情况、响应式布局（如适用）。
### 二、验证记录
5. **验证过程要留痕**
- 验证结果（curl 命令 + 响应、SQL + 结果、截图等）要附在提交说明或 PR 描述里。
- 如果验证过程中发现问题并修复，要说明原问题 + 修复方式。
6. **失败要说明原因**
- 如果验证未通过但需要先提交（比如依赖其他未完成改动），必须明确说明：
- 哪些验证未通过？
- 阻塞原因是什么？
- 预计何时能验证完成？
### 三、回归意识
7. **改动要考虑影响面**
- 修改公共代码（工具类、基类、配置、常量）后，要主动搜索调用方，确认是否需要回归测试。
- 修改核心流程后，要手动走一遍关联的主流程验证无破坏。
8. **关键路径要有回归测试**
- 核心业务逻辑的 bug 修复，原则上要补充自动化测试用例，防止复发。
> 一句话：**改完必须测，测完必须记，记完才能交**。
---
## 其它规约
- 所有对话、注释、提交信息、文档使用中文。
- 遵循全局 `~/.claude/CLAUDE.md` 中的《全局生产级软件开发规则》。
还没有评论，来说两句吧...