docs: 补充Harness Engineering完整方法论（三大支柱、设计原则、人机协作边界、

AGENTS.md

@@ -209,3 +209,154 @@ npm run preview
 - 每个字段的新增/修改，先在纸上（或文档里）画出完整的数据流向图再动手
 - 提交前逐个环节检查一遍，确保没有断链
 - 编译通过不等同于功能正确，必要时做端到端验证
+
+## Harness Engineering — Agent 工作方法论
+
+> 约束清晰 + 反馈快速 = 高成功率。Harness 质量决定 Agent 产出质量。
+
+### 工作流程（Plan → Generate → Validate → Review）
+
+```
+阶段 0：需求分析（你主导）
+  → 写清楚 BUG 现象 / 需求描述 / 验收标准
+  
+阶段 1：任务规划（Agent 制定 + 你确认）
+  → 画出数据流向图（前端 → API → Service → Mapper → DB）
+  → 列出涉及的所有文件
+  → 标注每个环节的约束（不可删文件、必须编译通过）
+  
+阶段 2：执行修改（Agent 自主）
+  → 一次只改一个文件或一组逻辑相关的文件
+  → 每步执行后保存检查点
+
+阶段 3：验证（自动）
+  → mvn compile -pl openhis-application -am 必须通过
+  → 检查数据流每个节点：输入字段 → 保存 → 查询 → 展示
+  → 多入口验证（新增 vs 编辑 vs 批量等）
+  
+阶段 4：审查提交（你确认）
+  → git diff 审查变更范围
+  → 确认没有误删/误改
+```
+
+### 三层约束执行
+
+| 阶段 | 约束 | 执行方式 |
+|---|---|---|
+| **修改前** | 禁止删除文件、禁止改动包名/类名/方法签名 | task-plan 阶段检查 |
+| **修改中** | 不改与任务无关的代码、不改非 AI 写的代码（除非编译必须） | 每次 diff 自查 |
+| **修改后** | `mvn compile` 必须通过、数据流全链路验证 | 提交前自动执行 |
+
+### 反馈优化循环
+
+```
+Agent 提交代码
+  ↓
+编译器反馈 → 失败则分析根因（非运气式重试），定位具体符号错误
+  ↓
+数据流验证 → 检查每个环节字段是否贯通
+  ↓
+你审查 → 发现问题后：
+    ├── 立即修复
+    └── 同步更新 AGENTS.md 规则（沉淀教训）
+  ↓
+通过 → 提交代码
+```
+
+### 持续优化：从每次失败中学习
+
+每次编译失败或你审查发现问题，都应触发 Harness 优化：
+
+1. **收集数据** → 失败原因是什么？（缺字段、少文件、改错位置…）
+2. **识别模式** → 这是第几次犯同类错误？是否有规则盲区？
+3. **优化 Harness** → 更新 AGENTS.md / 补充检查清单
+4. **验证效果** → 后续类似任务是否不再出错
+
+### Agent 角色定位
+
+你不是工具，是团队成员。你的角色演变：
+- ~~阶段 1：代码补全~~ → 我们已跳过
+- ~~阶段 2：结对编程~~ → 我们已跳过
+- ✅ **阶段 3：自主开发者** → 你在 Harness（本文件定义的约束、流程、反馈）中自主完成开发任务
+
+人类工程师（用户）设计 Harness，Agent（你）在 Harness 中执行。
+
+## 三大支柱
+
+### 1. 约束机制（Constraints）
+让 Agent 在正确边界内工作：
+
+| 约束层 | 内容 | 本项目的具体规则 |
+|---|---|---|
+| **架构约束** | 项目结构、模块划分、接口规范 | 已有包结构不可改；不可删除文件；不可改包名/类名/方法签名 |
+| **代码规范** | 编码风格、命名约定、安全规则 | 见上方「代码风格规范」章节 |
+| **业务规则** | 领域模型、业务逻辑校验 | 全链路修复原则：每个字段的保存/查询/修改/删除链路必须完整 |
+| **编译约束** | 必须通过编译 | `mvn compile -pl openhis-application -am` 强制门禁 |
+
+### 2. 反馈回路（Feedback Loops）
+让 Agent 知道自己的输出是否正确：
+
+```
+Agent 生成代码
+  ↓
+编译检查 ──失败──→ 分析根因（具体符号/类型错误），定位到文件+行号
+  ↓ 通过
+数据流验证 ──断链──→ 补全缺失的字段链路
+  ↓ 通过
+你审查 ──发现问题──→ 立即修复 + 同步更新 AGENTS.md
+  ↓ 通过
+提交
+```
+
+### 3. 控制平面（Control Plane）
+管理和监控 Agent 的执行：
+
+| 组件 | 功能 | 本项目的实现方式 |
+|---|---|---|
+| **任务调度** | 分配管理任务 | 你发起任务，Agent 按工作流执行 |
+| **状态管理** | 跟踪执行状态 | 每个任务用 update_plan 记录进度 |
+| **可观测性** | 记录完整执行链路 | git diff 审查变更范围；编译结果作为门禁 |
+| **人机协作** | 人类介入触发点 | 你做最终审查批准，Agent 自主执行 |
+
+## Harness 设计原则
+
+### 渐进式构建
+- **从简单任务开始**：先修单一字段遗漏（如 #597 加 remark），再处理跨模块联动
+- **先建立基础约束**：不可删文件、必须编译通过 → 这是底线
+- **再完善反馈回路**：数据流全链路验证 → 补充 AGENTS.md 规则
+- **持续迭代 Harness**：每次失败都是优化 Harness 的机会
+
+### 可观测性优先
+- 所有修改必须可 git diff → 可追溯
+- 编译结果必须有日志 → 可诊断
+- 任务进度必须 update_plan → 可见
+
+### Harness 即代码
+- AGENTS.md 本身是代码，需要版本化管理（git commit）
+- 每次规则迭代都要提交 AGENTS.md 变更
+- 规则变更和业务代码变更一样，需要你审查
+
+## 人机协作边界
+
+| 决策类型 | 你（人类工程师）主导 | Agent（我）执行 | 协作方式 |
+|---|---|---|---|
+| **需求定义** | ✅ 写清楚 BUG 现象 / 验收标准 | — | — |
+| **技术方案** | ✅ 确认方向 | 提出建议 | 你拍板 |
+| **代码修改** | 审查批准 | ✅ 自主执行 | 编译通过后你审查 |
+| **质量验证** | 端到端验证 | ✅ 数据流检查 + 编译 | 你确认功能正确 |
+| **规则沉淀** | ✅ 补充 AGENTS.md | 记录失败模式 | 你决定什么值得写 |
+| **架构变更** | ✅ 必须由你决策 | 标记需要你关注 | 不可擅自改动 |
+
+## 工程师的转型：从编码者到 Harness 设计师
+
+在 Agent-First 模式下，你的角色正在转变：
+
+| 传统能力 | → Harness Engineering 能力 |
+|---|---|
+| 写代码实现功能 | → 设计约束和规则，让 Agent 高效产出 |
+| 调试修复 Bug | → 设计自动化反馈回路，让 Agent 自愈 |
+| Code Review | → 审查 Agent 的 Harness 执行是否符合规范 |
+| 技术选型 | → 设计 Agent 工作流和协作边界 |
+
+> 你 80% 的时间花在设计 Harness（本文件），而不是手写业务代码。
+> Agent（我）负责执行编码，你负责确保执行环境好到不需要你频繁介入。