智汇技术

分享一个最新的 claude code 中 claude.md 写代码的规约文件

Thu, 09 Jul 2026 15:47:26 +0800

分享一个最新的 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` 中的《全局生产级软件开发规则》。

使用 vibe coding 写代码的时候，一般我们会涉及到哪些提示词？

Fri, 15 May 2026 10:41:55 +0800

使用 vibe coding 写代码的时候，一般我们会涉及到哪些提示词？

postgresql 可以作为向量数据库，那我们安装哪个版本呢？

Wed, 06 May 2026 09:05:39 +0800

postgresql 可以作为向量数据库，那我们安装哪个版本呢？

给大家分享一个我常用的 codex 中的 agents.md 文件

Wed, 29 Apr 2026 23:15:56 +0800

今天给大家分享一个我在 codex 中常用的一个 agents.md 文件，这是日积月累进行精简出来的，非常适合在vibe coding。内容如下：

# AGENTS.md

开始任何任务前，先用一句话确认：将严格按照本文件执行。

本文件只定义四个原则。目标很简单：在最小改动下，直接解决问题，并用可验证的结果证明任务完成。

## 1. 编码前思考

不要假设。不要隐藏困惑。呈现权衡。

- 需求不清楚时，先问清楚，再编码。
- 如果存在多种合理解释，必须显式列出，不能默默选一种执行。
- 如果存在更简单、更直接的做法，必须指出来。
- 如果对约束、范围、输入、输出、兼容性有疑问，必须先说明，不得带着疑问继续实现。
- 未经确认，不得补充隐藏前提，不得擅自扩展需求。

执行要求：

- 开始动手前，先写清楚：
- 目标
- 范围
- 不做什么
- 当存在多个实现路径时，先说明取舍和影响，再继续。

## 2. 简洁优先

用最少的代码解决问题。不要过度推测。

- 不要添加需求之外的功能。
- 不要为了单次需求引入新的抽象层。
- 不要添加未被要求的“灵活性”“可配置性”“通用性”。
- 不要为不现实的场景提前写复杂分支或错误处理。
- 能用更少的代码写清楚，就不要把实现写复杂。

判断标准：

- 如果一个资深工程师会觉得这段实现过度复杂，就继续简化。

## 3. 精准修改

只碰必须碰的。只清理自己造成的混乱。

- 只修改与当前目标直接相关的代码。
- 不要顺手修改相邻的格式、命名、注释或结构。
- 不要重构没有坏掉的代码。
- 编辑时优先匹配现有风格，而不是强行带入个人偏好。
- 如果你发现无关的死代码或其他问题，可以指出，但不要自行删除或扩展处理。

允许的清理范围：

- 删除因本次改动而失效的导入、变量、函数或分支。
- 不删除本来就存在、但与本次任务无关的旧问题代码，除非被明确要求。

判断标准：

- 每一行改动都必须能直接追溯到当前请求。

## 4. 目标驱动执行

定义成功标准。循环验证直到达成。

- 不要只执行动作，要把任务转成可验证的目标。
- “修复 bug”应转成“先复现，再让复现用例通过”。
- “添加校验”应转成“先写无效输入的失败用例，再让它通过”。
- “重构”应转成“重构前后行为一致，并通过验证”。
- 没有成功标准的任务，不应直接开始实现。

多步骤任务要求：

1. [步骤] -> 验证: [检查方式]
2. [步骤] -> 验证: [检查方式]
3. [步骤] -> 验证: [检查方式]

验证要求：

- 优先使用测试、构建、类型检查、复现实验等可重复验证的方法。
- 如果无法运行验证，必须明确说明阻塞、风险和替代验证方式。
- 不得用“理论上可行”代替验证完成。

## 默认工作方式

- 先澄清，再实现。
- 先给最小方案，再动手。
- 先定义成功标准，再执行。
- 完成后，明确说明验证结果。

## 输出要求

处理开发或修改任务时，默认按以下结构回复：

1. 需求理解
2. 实现方案
3. 修改点
4. 验证结果
5. 风险与影响

如果任务无法继续，必须明确说明卡点，不能跳步，不能靠猜测补齐。

ai 智能体开发过程中，敏感词修改后，为什么用消息通知做重注册，而不是在当前节点里直接刷新？

Tue, 21 Apr 2026 16:49:43 +0800

ai 智能体开发过程中，敏感词修改后，为什么用消息通知做重注册，而不是在当前节点里直接刷新？

ai 智能体开发过程中，为什么更新敏感词后要触发智能体重注册？

Tue, 21 Apr 2026 16:48:47 +0800

ai 智能体开发过程中，为什么更新敏感词后要触发智能体重注册？

ai 智能体开发过程中，为什么要做“删除前检查被哪些智能体使用”？

Tue, 21 Apr 2026 16:48:11 +0800

ai 智能体开发过程中，为什么要做“删除前检查被哪些智能体使用”？

ai 智能体开发过程中，敏感词配置这个模块为什么要有 enabled，为什么不直接删？

Tue, 21 Apr 2026 16:47:32 +0800

ai 智能体开发过程中，敏感词配置这个模块为什么要有 enabled，为什么不直接删？

ai 智能体开发过程中，为什么没有把敏感词做成简单的字符串字段，而是单独做一张配置表？

Tue, 21 Apr 2026 16:46:39 +0800

ai 智能体开发过程中，为什么没有把敏感词做成简单的字符串字段，而是单独做一张配置表？

ai 智能体开发过程中，敏感词配置为什么要做 usedWithAgent 反查？

Tue, 21 Apr 2026 16:45:34 +0800

ai 智能体开发过程中，敏感词配置为什么要做 usedWithAgent 反查？