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:
380
RULES.md
380
RULES.md
@@ -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 XML、DTO | 修复后上报 |
|
||||
| **L3 人工审查** | 10-30 分钟 | 架构、设计、业务正确性 | 驳回 / 指导 / 批准 |
|
||||
| **L1 编译检查** | <30秒 | 语法、类型、签名 | 立即阻断,自行修复 |
|
||||
| **L2 数据流验证** | <5分钟 | 全链路字段、Mapper XML、DTO | 修复后上报 |
|
||||
| **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 必须通过才能 commit,L3(如有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` 同步。
|
||||
|
||||
Reference in New Issue
Block a user