feat: 全面整合agentforge-rs + .codex/harness方法论到AI开发规范

RULES.md 420→460行,新增整合内容:
- Karpathy编码准则(先想再写/简洁优先/精准修改/目标驱动)
- 验证后才宣称完成铁律(Verification Before Completion)
- 系统化调试四阶段(Systematic Debugging)
- 约束设计原则(可验证/无歧义/优先级/渐进增强)
- 持久执行三层状态管理(系统层/执行层/业务层)
- 审查与审计三层体系(自审/配对审查/合规审查)
- BDT方法论(Bug Driven Testing + Playwright 7种检查模式)
- L4/L5分析与AI自主优化机制
- 标准工作循环(Init→Select→Implement→Verify→Cleanup)
- Clean State Checklist(会话结束检查)
- 新增10条过往教训(含上下文焦虑/过早宣告胜利等)

新增 MD/specs/HARNESS_ENGINEERING.md (305行) — 完整方法论参考:
- WalkingLabs 5子系统模型
- 约束/反馈/控制平面/持久执行详解
- Agent协作管线/路由/去重/禅道操作
- BDT测试用例设计/质量标准
- L4量化分析 + L5 AI自优化

7个AI工具配置文件同步更新(470行内嵌)
This commit is contained in:
2026-06-06 10:01:41 +08:00
parent 84ba9a4139
commit f3880eb8df
9 changed files with 1991 additions and 1366 deletions

380
RULES.md
View File

@@ -1,6 +1,6 @@
# HealthLink-HIS — AI 开发规范(自动加载)
> 🤖 **本文件供所有 AI 编码工具自动读取**。无论使用 Claude Code、Cursor、Codex CLI、Copilot、Qwen、Cline 还是其他工具,进入本项目后必须遵守以下规范。
> 🤖 **本文件供所有 AI 编码工具自动读取**。进入本项目后必须遵守以下规范。
>
> **模型决定上限Harness 决定底线。**
@@ -42,7 +42,6 @@
- 凡是新建表、新增字段,必须创建 Flyway 迁移脚本
- 路径:`healthlink-his-domain/src/main/resources/db/migration/`
- 命名:`V{版本号}__{描述}.sql`(双下划线)
- 禁止直接在数据库执行 SQL 不走 Flyway
**铁律3: 测试通过后才提交**
- 编译 + 测试全部通过后才能 git commit
@@ -51,59 +50,80 @@
**铁律4: 前后端API路径对齐**
- 后端前缀:`/healthlink-his/api/v1/`
- 前端 `request.js` 的 baseURL 必须与后端匹配
- 接口变更必须同步更新前后端代码
**铁律5: 状态值一致性(来自 Bug #574 教训)**
**铁律5: 状态值一致性Bug #574 教训)**
- 修改任何状态值前,必须先列出完整的状态流转链路
- 检查项:
1. 枚举定义的值是否正确
2. Service 层设置的状态值是否与枚举一致
3. 查询/列表接口的状态映射是否覆盖所有枚举值
4. 前端 `STATUS_CLASS_MAP` 是否包含新状态
5. 前端过滤条件(如 `v-if`)是否兼容新状态
6. 池/统计表的聚合 SQL 是否包含新状态值
- 检查项:枚举定义 → Service 设置 → 查询映射 → 前端 STATUS_CLASS_MAP → 前端 v-if → 统计SQL
- 禁止:只改一端不检查其他端
**铁律6: 禁止删除源文件(来自 Bug #574 教训)**
**铁律6: 禁止删除源文件Bug #574 教训)**
- 绝对禁止删除项目中已有的 Java/Vue/SQL 源文件
- 文件有编译错误 → 修复错误,不删除文件
- 文件是重复的 → 重构合并,不删除文件
- 文件是 AI 幻觉创建的 → 检查 git baseline 确认后再删除
- 编译错误 → 修复错误;重复文件 → 重构合并
- 唯一例外:明确由人类确认删除的文件
**铁律7: 禁止修改已有公开方法签名**
- 不能删除重命名已有的 public 方法
- 不能修改已有方法的参数列表
- 需要新增功能时 → 添加新的重载方法
- 需要改行为时 → 修改方法内部实现,不改签名
- 不能删除/重命名已有的 public 方法,不能修改参数列表
- 需要新功能 → 添加重载方法;需要改行为 → 修改内部实现
**铁律8: 验证后才宣称完成Verification Before Completion**
- **没有跑过验证命令,就不能说"完成了""通过了""没问题"**
- 禁止使用"应该可以""大概没问题""看起来正确"
- 必须:运行命令 → 读取输出 → 确认结果 → 才能宣称
- 这是诚实原则,不是效率问题
### 🟡 P1 铁律 — 强烈建议
**铁律8: 先分解再行动**
**铁律9: 先分解再行动**
- 修改超过3个文件、涉及多模块、数据库变更必须先制定计划
**铁律9: 验证后信**
**铁律10: 验证后信**
- 每次修改后必须验证编译通过,不信记忆
- 重新编译命令:`mvn clean compile -DskipTests`
**铁律10: 文档统一管理**
**铁律11: 文档统一管理**
- 所有文档存储在 `MD/` 目录
- 文件名:大写英文+下划线(如 `BACKEND_CHECKLIST.md`
- 文档头部必须包含元数据块(文档类型、版本、日期)
---
## 三、全链路 6 环分析
## 三、Karpathy 编码准则
> ⚠️ **涉及数据库字段的 Bug / 需求,必须走完整链路,不得"就事论事"。**
> 减少 LLM 常见编码错误。偏向谨慎而非速度。
### 3.1 先想再写
- 明确陈述假设,不确定就问
- 多种解读时都列出来,不要默默选一种
- 有更简单的方案就说出来,该推回就推回
- 不清楚的地方停下来,说清楚哪里不清楚
### 3.2 简洁优先
- 不做没要求的功能,不做一次性代码的抽象
- 不加没要求的"灵活性"和"可配置性"
- 200 行能 50 行搞定就重写
- 自问:"高级工程师会不会觉得这过度设计?"
### 3.3 精准修改
- 只改必须改的,不"顺手改进"相邻代码
- 匹配现有代码风格,即使你有不同的偏好
- 每行改动都能追溯到用户的请求
- 只清理你自己改动产生的无用代码
### 3.4 目标驱动
- 把任务转化为可验证目标
- 多步任务声明计划:`[步骤] → 验证: [检查]`
- 强验收标准让 Agent 能独立循环,弱标准需要持续澄清
---
## 四、全链路 6 环分析
> ⚠️ **涉及数据库字段的 Bug / 需求,必须走完整链路。**
```
前端/页面 → Controller → Service → Mapper → DB/SQL → 关联模块
①录入 ②验证 ③业务 ④持久化 ⑤存储 ⑥联动
```
### 每一环必须确认
| 环 | 检查内容 |
|----|---------|
| ① 录入 | 前端有无输入入口(弹窗、表格行编辑、表单) |
@@ -113,104 +133,113 @@
| ⑤ 存储 | 数据库表结构、索引、NOT NULL 约束 |
| ⑥ 联动 | 上游(医嘱→护士站)、下游(打印、计费、报表)是否同步 |
### 全链路验证顺序
修复涉及状态流转的问题后,必须按以下顺序验证:
1. **数据库**:确认状态值已正确写入
2. **后端接口**:确认返回的状态映射正确
3. **前端显示**:确认页面显示正确状态文本
4. **前端交互**:确认按钮/操作基于正确状态启用/禁用
5. **统计数据**:确认池/报表统计包含新状态
### 常见陷阱
- ❌ 只修了「主入口」的保存逻辑,忘了「批量保存」「签发保存」等其他入口
- ❌ 前端加了输入框,后端 Service 没传字段
- ❌ Mapper XML 是 UNION ALL 查询,只改了其中一个子查询
- ❌ DTO 层级继承关系没检查
- ❌ 只测了新增,没测编辑已有数据的回显和修改再保存
**修复后的验证顺序**
1. 数据库:确认状态值已正确写入
2. 后端接口:确认返回的状态映射正确
3. 前端显示:确认页面显示正确状态文本
4. 前端交互:确认按钮/操作基于正确状态启用/禁用
5. 统计数据:确认池/报表统计包含新状态
---
## 、Harness Engineering 方法论
## 、Harness Engineering 方法论
> Harness = 约束 + 反馈 + 控制平面 + 持久执行
### 4.1 四层约束金字塔
### 5.1 四层约束金字塔
| 层级 | 内容 | 落地方式 |
|------|------|---------|
| **L1 架构约束** | 接口合约、包结构、命名规范、禁止模式 | 本文件铁律、AGENTS.md |
| **L1 架构约束** | 接口合约、包结构、命名规范、禁止模式 | 本文件铁律 |
| **L2 代码质量** | 圈复杂度、代码风格、类型提示 | 编译门禁 + ESLint |
| **L3 安全约束** | 敏感信息检测、权限检查、输入验证 | 配置不可硬编码 |
| **L4 业务规则** | 领域逻辑、数据一致性、事务边界 | 全链路 6 环验证 |
**约束优先级**:安全 > 架构 > 质量 > 业务
**约束设计原则**
- **可验证**:每条约束必须能被自动化检查("覆盖率>90%"✅ "质量要高"❌)
- **无歧义**"每函数不超过50行"✅ "函数不要太长"❌
- **优先级**:安全(1) > 架构(2) > 业务(3) > 质量(4) > 性能(5)
- **渐进增强**L1编译通过 → L2+命名规范 → L3+测试覆盖 → L4+安全扫描
### 4.2 三层反馈系统
### 5.2 三层反馈系统
| 层级 | 速度 | 覆盖范围 | 失败处理 |
|------|------|---------|---------|
| **L1 编译检查** | <30 | 语法类型签名 | 立即阻断自行修复 |
| **L2 数据流验证** | <5 分钟 | 全链路字段Mapper XMLDTO | 修复后上报 |
| **L3 人工审查** | 10-30 分钟 | 架构设计业务正确性 | 驳回 / 指导 / 批准 |
| **L1 编译检查** | <30秒 | 语法类型签名 | 立即阻断自行修复 |
| **L2 数据流验证** | <5分钟 | 全链路字段Mapper XMLDTO | 修复后上报 |
| **L3 人工审查** | 10-30分钟 | 架构设计业务正确性 | 驳回/指导/批准 |
**反馈设计铁律**
- 反馈必须可行动指出文件 + 行号 + 错误类型 + 修复方向
- 反馈越及时越好L1 即时 L2 分钟 L3 小时
**反馈铁律**
- 反馈必须可行动文件 + 行号 + 错误类型 + 修复方向
- 失败后先回滚到最近检查点再重试
- 持续失败3次 上报人类
### 4.3 控制平面Agent 协调)
### 5.3 控制平面
```
┌─────────────────────────────────────────────┐
│ 战略层(人类主导) │
│ ├── 设定目标、审批关键决策 │
│ └── 异常升级处理 │
├─────────────────────────────────────────────┤
│ 战术层Control Plane
│ ├── 任务分解 + update_plan │
│ ├── 依赖协调 + 资源分配 │
│ └── 检查点保存 + 恢复 │
├─────────────────────────────────────────────┤
│ 执行层Agent 自主) │
│ ├── 代码生成、测试执行 │
│ └── 错误恢复 + 幂等重试 │
└─────────────────────────────────────────────┘
战略层(人类) → 设定目标、审批决策、异常升级
战术层Agent → 任务分解、update_plan、依赖协调、检查点保存
执行层Agent → 代码生成、测试执行、错误恢复、幂等重试
```
### 4.4 持久执行
### 5.4 持久执行
- 每个关键步骤保存检查点`update_plan` 进度
- 失败后从最新检查点恢复不从头开始
- 幂等设计同一操作重复执行结果一致
- **三层状态管理**系统层(工作流ID/超时/重试) 执行层(当前活动/进度) 业务层(已完成工作/中间产物)
---
## 五、质量门禁5 级)
## 六、五层质量门禁
| 级别 | 门禁 | 通过标准 |
|------|------|---------|
| **L1** | 编译通过 | `mvn clean compile` + `npm run build:dev` ERROR |
| **L2** | 测试通过 | 单元测试 + 接口测试全部通过 |
| **L3** | DB 审查 | Flyway 脚本规范SQL 安全索引合理 |
| **L4** | 验收通过 | 核心功能流程完整验证全链路检查 |
| **L5** | 归档完成 | Git commit + 文档更新 + 代码推送 |
| 门禁 | 时间 | 范围 | 失败处理 |
|------|------|------|---------|
| **L1 编译检查** | <30秒 | 语法类型导入 | Agent 自行修复 |
| **L2 静态分析** | <2分钟 | 代码风格复杂度安全 | Agent 修复 |
| **L3 单元测试** | <5分钟 | 功能正确性边界条件 | 自动修复或上报 |
| **L4 集成测试** | <15分钟 | 模块间交互数据流 | 上报人工 |
| **L5 生产验证** | 持续 | 监控告警性能 | 自动回滚 |
### 提交铁律
- L1-L2 必须通过才能 commit
- L3如有DB变更必须通过才能 push
- L4-L5 发布前必须完成
**提交铁律**L1-L2 必须通过才能 commitL3如有DB变更必须通过才能 push
---
## 六、后端开发规范
## 七、系统化调试Systematic Debugging
> **铁律:没有根因调查,不能提出修复方案。**
### 四阶段流程
**阶段1根因调查**修复前必须完成
1. 仔细阅读错误信息堆栈行号错误码
2. 稳定复现能否可靠触发步骤每次
3. 检查最近变更git diff新依赖配置变更
4. 多组件系统在每个组件边界加诊断日志定位哪一层断裂
5. 追踪数据流坏值从哪里来谁调用的一直追溯到源头
**阶段2模式分析**
- 找到同代码库中类似的正常工作代码
- 逐项对比差异
- 理解依赖关系
**阶段3假设与测试**
- 形成单一假设"我认为X是根因因为Y"
- 做最小改动测试
- 有效 阶段4无效 新假设
**阶段4实施**
- 创建失败测试用例
- 修复根因不是症状
- 验证修复
---
## 八、后端开发规范
### 分层架构
```
Controller → AppService → Service → Mapper → Entity
接收请求 编排业务 单表CRUD 数据访问 实体定义
```
### 命名规范
@@ -234,110 +263,125 @@ com.healthlink.his.domain.{module}
com.healthlink.his.common.enums
```
### 统一返回格式
```java
AjaxResult.success(data) // 成功
AjaxResult.error("错误信息") // 失败
getDataTable(list) // 列表
```
### 关键约束
- 所有查询使用 `LambdaQueryWrapper`禁止字符串拼接 SQL
- `@Transactional(rollbackFor = Exception.class)` 管理事务
- 所有接口标注 `@PreAuthorize` 权限控制
- 患者敏感信息身份证手机号在日志中脱敏
- **扩展功能不修改原有函数签名**新建 Service/AppService
- 涉及多表写操作的方法标注 `@Transactional`
- 事务方法未被同一类内方法直接调用避免自调用失效
- 患者敏感信息在日志中脱敏
- **扩展功能不修改原有函数签名**
---
## 、前端开发规范
## 、前端开发规范
### 技术栈
- Vue 3 + Vite + Element Plus + Pinia + Axios
- 基于 RuoYi-Vue3 框架
- Vue 3 + Vite + Element Plus + Pinia + Axios基于 RuoYi-Vue3
### 目录结构
```
src/api/{module}/ # API接口kebab-case路径
src/api/{module}/ # API接口
src/views/{module}/ # 页面组件
src/store/modules/ # Pinia状态管理
src/components/ # 公共组件
```
### API 路径规范
```javascript
// 统一前缀 /healthlink-his/api/v1/
export function listXxx(query) {
return request({ url: '/healthlink-his/api/v1/xxx/list', method: 'get', params: query })
}
```
### 组件规范
- 页面组件使用 `<script setup>` 语法
- 弹窗组件使用 `defineExpose({ open })` 暴露打开方法
- 列表必须支持分页`pagination` 组件
- 按钮权限使用 `v-hasPermi` 指令
### 关键约束
- API前缀`/healthlink-his/api/v1/`
- 路由懒加载`() => import('@/views/xxx/index.vue')`
- 使用 `v-html`除非做 XSS 转义
- 不在前端硬编码密码密钥
- 页面使用 `<script setup>` 语法
- 按钮权限使用 `v-hasPermi` 指令
- `onMounted` 中注册的事件在 `onUnmounted` 中移除
---
## 、Agent 体系(智能体协作)
## 、Agent 体系
### 角色定义
### 角色与路由
| 代号 | 名称 | 角色 | 职责 |
|------|------|------|------|
| liubei | 刘备 | 项目经理 | 协调任务分配异常升级 |
| zhugeliang | 诸葛亮 | 架构师 | 需求分析方案设计技术决策 |
| guanyu | 关羽 | 后端开发 | Java 后端修复API 开发 |
| zhaoyun | 赵云 | 前端开发 | Vue 前端修复页面开发 |
| xunyu | 荀彧 | DBA | 数据库审查SQL 优化Flyway 脚本 |
| zhangfei | 张飞 | 测试 | Playwright 测试接口测试回归测试 |
| huatuo | 华佗 | 验收 | 功能验收质量确认发布检查 |
| chenlin | 陈琳 | 文档 | 归档记录文档更新Git 提交 |
| 代号 | 名称 | 角色 | 路由关键词 |
|------|------|------|-----------|
| liubei | 刘备 | 项目经理 | 协调分派异常升级 |
| zhugeliang | 诸葛亮 | 架构师 | 分析路由设计 |
| guanyu | 关羽 | 后端开发 | java, api, spring, service, controller |
| zhaoyun | 赵云 | 前端开发 | vue, 界面, 显示, 弹窗, 按钮 |
| xunyu | 荀彧 | DBA | 数据库, sql, 迁移, mapper xml |
| zhangfei | 张飞 | 测试 | 测试, QA, 回归 |
| huatuo | 华佗 | 验收 | 需求验收质量确认 |
| chenlin | 陈琳 | 文档 | 文档归档Git提交 |
### 协作流水线
```
刘备(协调) → 诸葛亮(分析) → {关羽|赵云}(修复) → 荀彧(DB审查) → 张飞(测试) → 华佗(验收) → 陈琳(归档)
刘备(协调) → 诸葛亮(分析路由) → {关羽|赵云}(修复) → 荀彧(DB审查) → 张飞(测试) → 华佗(验收) → 陈琳(归档)
```
### Bug 修复完整管线BDT 方法论)
```
获取Bug → 设计测试用例 → 基线测试(应失败) → 全链路修复 → 回归测试(应通过) → 扩展测试(无回归) → 提交
```
### Bug 状态管理铁律
- 人类提的 Bug只加备注不改状态不改分配
- 智能体提的 Bug可以改分配和加备注
- 已关闭/已解决的 Bug 不再处理
### 修复流程铁律
---
- 一次只修一个 Bug不扩大范围
- 修复前必须读 AGENTS.md
- 修复后必须验证编译
- 涉及 SQL 必须先查真实数据库
## 十一、审查与审计
### 测试流程铁律
### 三层审查体系
- Playwright 必须 `--workers=1` 单线程
- 超时 120
- 最多重试 3
- 测试结果写入禅道备注
| 层级 | 内容 | 时机 |
|------|------|------|
| **L1 自审** | Agent 对照约束逐条检查 | 每次提交前 |
| **L2 配对审查** | Agent 生成变更摘要人类终审 | PR/提交时 |
| **L3 合规审查** | 审计追踪记录所有 AI 操作 | 持续 |
### 归档流程铁律
### L1 自审清单
```yaml
self_review:
- "所有修改能通过编译?"
- "遵守命名规范?"
- "测试覆盖达标?"
- "没有遗漏的 TODO / DEBUG"
- "变更范围没超出任务边界?"
```
- 三重归档Git + SQLite + Redis
- SQLite 必须使用完整字段
- 禅道备注格式`[📝 陈琳归档] Bug #xxx`
### 评审评分维度
| 维度 | 问题 |
|------|------|
| 正确性 | 行为是否符合目标功能 |
| 验证 | 检查是否真的跑过并留下证据 |
| 范围纪律 | 是否保持在选定功能范围内 |
| 可靠性 | 结果能否在重启后继续工作 |
| 可维护性 | 代码和文档是否清楚到可交接 |
---
## 九、开发流程
## 十二、标准工作循环
```
开始会话
├→ 1. Init — 读 AGENTS.md + PROGRESS.md + git log
├→ 2. Select — 只选一个未完成功能
├→ 3. Implement — 一次只做一个,不扩大范围
├→ 4. Verify — 运行验证命令,有证据才标记完成
└→ 5. Cleanup — 更新进度 + clean-state-checklist + git commit
```
### 会话结束前必须运行 Clean State Checklist
```
□ 标准启动路径仍然可用
□ 标准验证路径仍然可运行
□ 当前进度已记录到进度日志
□ 无半成品步骤处于未记录状态
□ 下一轮会话无需人工修复即可继续
```
---
## 十三、开发流程
```
收到任务
@@ -361,60 +405,56 @@ scope: 模块名(如 registration, billing, pharmacy)
---
## 十、快速参考命令
## 十、快速参考命令
```bash
# === 后端 ===
export JAVA_HOME=/opt/jdk-25
mvn clean compile -DskipTests # 编译
mvn install -DskipTests # 完整构建
mvn test -pl healthlink-his-application -Dtest="XxxTest" -Dsurefire.failIfNoSpecifiedTests=false # 测试
mvn install -DskipTests # 构建
mvn test -pl healthlink-his-application -Dtest="XxxTest" -Dsurefire.failIfNoSpecifiedTests=false
# === 前端 ===
cd healthlink-his-ui
npm run dev # 开发模式
npm run build:dev # 构建
npm run lint # 代码检查
npm run test:run # 单元测试
npm run dev && npm run build:dev && npm run lint && npm run test:run
# === Git ===
git status # 查看变更
git add -A # 暂存所有
git commit -m "feat(module): description" # 提交
git push origin develop # 推送
git status && git add -A && git commit -m "feat(module): desc" && git push origin develop
```
---
## 十、详细规范文档索引
## 十、详细规范文档索引
| 文档 | 路径 | 用途 |
|------|------|------|
| 执行铁律 | `MD/specs/IRON_RULES.md` | 铁律完整版 |
| 后端规范 | `MD/specs/BACKEND_DEVELOPMENT_STANDARD.md` | 后端编码标准 |
| 前端规范 | `MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md` | 前端编码标准 |
| Harness方法论 | `MD/specs/HARNESS_ENGINEERING.md` | 完整Harness+Agent方法论 |
| 文档规范 | `MD/DOCUMENTATION_STANDARD.md` | 文档管理标准 |
| 后端清单 | `MD/specs/BACKEND_CHECKLIST.md` | 发布前检查 |
| 前端清单 | `MD/specs/FRONTEND_CHECKLIST.md` | 发布前检查 |
| 三甲标准 | `MD/standards/GRADE3A_HIS_STANDARD.md` | 三甲医院达标标准 |
| Flyway指南 | `MD/guides/FLYWAY_USAGE_GUIDE.md` | 数据库迁移指南 |
| E2E测试 | `MD/specs/PLAYWRIGHT_TESTING_PLAN.md` | Playwright测试方案 |
---
## 十、过往教训(必须铭记)
## 十、过往教训
| 教训 | 来源 | 教训内容 |
|------|------|---------|
| 状态链路断裂 | Bug #574 | `checkInTicket()` BOOKED(1) 而非 CHECKED_IN(3)前端映射缺失池统计漏计 必须走完整状态链路验证 |
| 盲删源文件 | Bug #574 | AI 看到编译错误直接删文件没检查是否在 baseline 必须先确认文件来源再操作 |
| 修复方向偏差 | Bug #574 | 多次 fallback 改的是 OrderServiceImpl完全没触及 TicketServiceImpl 必须用 rg 搜索所有相关代码路径 |
| bug_reports 表缺少 | 经验 | INSERT 静默失败必须检查表结构 |
| 禅道 comment API | 经验 | API 不存在必须 resolve+activate workaround |
| SQLite WAL 并发 | 经验 | 多进程并发写需要 checkpoint |
| UTF-8 切片 | 经验 | 多字节字符不能用 byte index 切片 |
| 禅道图片附件 | 经验 | 必须 OCR 读取不能直接解析 |
| 教训 | 内容 |
|------|------|
| 状态链路断裂 | Bug#574: 签到 BOOKED(1) 而非 CHECKED_IN(3)前端映射缺失 必须走完整状态链路 |
| 盲删源文件 | AI 看到编译错误直接删文件没检查 baseline 必须先确认文件来源 |
| 修复方向偏差 | 多次 fallback 改的是错误的 Service 必须用 rg 搜索所有相关代码路径 |
| bug_reports | INSERT 静默失败 必须检查表结构 |
| 禅道 comment API | API 不存在 resolve+activate workaround |
| SQLite WAL 并发 | 多进程并发写需要 checkpoint |
| UTF-8 切片 | 多字节字符不能用 byte index 切片 |
| 上下文焦虑 | Agent 感觉上下文快满时会匆忙结束跳过验证 注意 context 40% 阈值 |
| 过早宣告胜利 | 自评验证分开"干活""检查" |
| 覆盖率幻觉 | 覆盖率达标但逻辑没测 引入变异测试 |
---
> ⚠️ **警告**: 本文件是项目 AI 开发规范的唯一信源。各工具配置文件AGENTS.md、.cursorrules 等)均通过 `bash scripts/sync-ai-rules.sh` 从本文件同步。修改规范请只修改本文件
> ⚠️ 本文件是 AI 开发规范的唯一信源。各工具配置文件 `bash scripts/sync-ai-rules.sh` 同步