From f3880eb8df9e666bb0c05d25680f3c15ee1790f0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=8D=8E=E4=BD=97?= Date: Sat, 6 Jun 2026 10:01:41 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E5=85=A8=E9=9D=A2=E6=95=B4=E5=90=88age?= =?UTF-8?q?ntforge-rs=20+=20.codex/harness=E6=96=B9=E6=B3=95=E8=AE=BA?= =?UTF-8?q?=E5=88=B0AI=E5=BC=80=E5=8F=91=E8=A7=84=E8=8C=83?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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行内嵌) --- .aider.conf.yml | 380 +++++++++++++++++-------------- .clinerules | 382 ++++++++++++++++++-------------- .cursorrules | 382 ++++++++++++++++++-------------- .github/copilot-instructions.md | 382 ++++++++++++++++++-------------- .qwenrules | 382 ++++++++++++++++++-------------- .windsurfrules | 382 ++++++++++++++++++-------------- AGENTS.md | 382 ++++++++++++++++++-------------- MD/specs/HARNESS_ENGINEERING.md | 305 +++++++++++++++++++++++++ RULES.md | 380 +++++++++++++++++-------------- 9 files changed, 1991 insertions(+), 1366 deletions(-) create mode 100644 MD/specs/HARNESS_ENGINEERING.md diff --git a/.aider.conf.yml b/.aider.conf.yml index 9b03103ab..a424ee2bc 100644 --- a/.aider.conf.yml +++ b/.aider.conf.yml @@ -4,7 +4,7 @@ instructions: | # HealthLink-HIS — AI 开发规范（自动加载） - > 🤖 **本文件供所有 AI 编码工具自动读取**。无论使用 Claude Code、Cursor、Codex CLI、Copilot、Qwen、Cline 还是其他工具，进入本项目后必须遵守以下规范。 + > 🤖 **本文件供所有 AI 编码工具自动读取**。进入本项目后必须遵守以下规范。 > > **模型决定上限，Harness 决定底线。** @@ -46,7 +46,6 @@ instructions: | - 凡是新建表、新增字段，必须创建 Flyway 迁移脚本 - 路径：`healthlink-his-domain/src/main/resources/db/migration/` - 命名：`V{版本号}__{描述}.sql`（双下划线） - - 禁止直接在数据库执行 SQL 不走 Flyway **铁律3: 测试通过后才提交** - 编译 + 测试全部通过后才能 git commit @@ -55,59 +54,80 @@ instructions: | **铁律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 → 关联模块 ①录入 ②验证 ③业务 ④持久化 ⑤存储 ⑥联动 ``` - ### 每一环必须确认 - | 环 | 检查内容 | |----|---------| | ① 录入 | 前端有无输入入口（弹窗、表格行编辑、表单） | @@ -117,104 +137,113 @@ instructions: | | ⑤ 存储 | 数据库表结构、索引、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 数据访问 实体定义 ``` ### 命名规范 @@ -238,110 +267,125 @@ instructions: | 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 }) - } - ``` - - ### 组件规范 - - 页面组件使用 `