docs: 补充约束四层模型、反馈三层结构和常见陷阱表
This commit is contained in:
53
AGENTS.md
53
AGENTS.md
@@ -286,28 +286,40 @@ Agent 提交代码
|
||||
### 1. 约束机制（Constraints）
|
||||
让 Agent 在正确边界内工作：
|
||||
|
||||
| 约束层 | 内容 | 本项目的具体规则 |
|
||||
约束分四个层级，从底层架构到顶层业务：
|
||||
|
||||
| 层级 | 约束内容 | 示例 |
|
||||
|---|---|---|
|
||||
| **架构约束** | 项目结构、模块划分、接口规范 | 已有包结构不可改；不可删除文件；不可改包名/类名/方法签名 |
|
||||
| **代码规范** | 编码风格、命名约定、安全规则 | 见上方「代码风格规范」章节 |
|
||||
| **业务规则** | 领域模型、业务逻辑校验 | 全链路修复原则：每个字段的保存/查询/修改/删除链路必须完整 |
|
||||
| **编译约束** | 必须通过编译 | `mvn compile -pl openhis-application -am` 强制门禁 |
|
||||
| **架构层** | 项目结构、模块划分、接口规范、技术栈 | 不可删文件、不可改包名/类名/方法签名 |
|
||||
| **代码层** | 编码风格、命名约定、函数长度、注释标准 | 见「代码风格规范」章节 |
|
||||
| **安全层** | 输入验证、敏感数据处理、权限控制 | SQL 注入防护、XSS 防护 |
|
||||
| **业务层** | 领域模型、业务逻辑校验、数据一致性 | 全链路修复原则：每个字段的保存/查询/修改/删除链路必须完整 |
|
||||
|
||||
**设计原则**：清晰可验证（具体而非模糊）、适度不过度（松→失控，紧→限制）、可进化（版本化管理，持续优化）
|
||||
|
||||
### 2. 反馈回路（Feedback Loops）
|
||||
让 Agent 知道自己的输出是否正确：
|
||||
让 Agent 知道自己的输出是否正确。反馈分三层：
|
||||
|
||||
| 层级 | 时间 | 本项目的实现 |
|
||||
|---|---|---|
|
||||
| **即时反馈** | 秒级 | 编译检查 → 定位具体符号/类型错误 + 行号 |
|
||||
| **功能反馈** | 分钟级 | 数据流全链路验证（输入→保存→查询→展示） |
|
||||
| **深度反馈** | 你审查时 | 你审查变更范围，发现问题后同步更新 AGENTS.md |
|
||||
|
||||
```
|
||||
Agent 生成代码
|
||||
↓
|
||||
编译检查 ──失败──→ 分析根因（具体符号/类型错误），定位到文件+行号
|
||||
编译检查 ──失败──→ 分析根因，定位到文件+行号（即时反馈）
|
||||
↓ 通过
|
||||
数据流验证 ──断链──→ 补全缺失的字段链路
|
||||
数据流验证 ──断链──→ 补全缺失的字段链路（功能反馈）
|
||||
↓ 通过
|
||||
你审查 ──发现问题──→ 立即修复 + 同步更新 AGENTS.md
|
||||
你审查 ──发现问题──→ 立即修复 + 同步更新 AGENTS.md（深度反馈）
|
||||
↓ 通过
|
||||
提交
|
||||
```
|
||||
|
||||
**反馈设计要点**：快速失败（低成本检查优先）、清晰具体（包含位置/原因/建议）、可行动（Agent 能据此修复）
|
||||
|
||||
### 3. 控制平面（Control Plane）
|
||||
管理和监控 Agent 的执行：
|
||||
|
||||
@@ -411,6 +423,29 @@ Agent 生成代码
|
||||
|
||||
> 你的成功不再取决于你写的代码行数，而是取决于你设计的 Harness 质量。
|
||||
|
||||
## 常见陷阱
|
||||
|
||||
### 约束机制陷阱
|
||||
| 陷阱 | 表现 | 对策 |
|
||||
|---|---|---|
|
||||
| 约束过松 | Agent 行为失控，产出不符合规范 | 从架构层开始逐层收紧 |
|
||||
| 约束过紧 | 限制 Agent 能力，效率低下 | 保留创新空间，只约束核心边界 |
|
||||
| 约束不可验证 | 变成摆设，Agent 不遵守 | 每条约束必须可自动化检查 |
|
||||
|
||||
### 反馈回路陷阱
|
||||
| 陷阱 | 表现 | 对策 |
|
||||
|---|---|---|
|
||||
| 反馈太慢 | Agent 迭代效率低，等反馈浪费时间 | 先做即时反馈（编译），再做深度反馈 |
|
||||
| 反馈模糊 | Agent 看不懂，无法修复 | 反馈必须包含具体位置、原因、建议 |
|
||||
| 反馈不可行动 | 知道错了但不知道怎么改 | 提供修复方向或参考示例 |
|
||||
|
||||
### 控制平面陷阱
|
||||
| 陷阱 | 表现 | 对策 |
|
||||
|---|---|---|
|
||||
| 监控不足 | 问题发现晚，修复成本高 | 每次修改必须 git diff 可追溯 |
|
||||
| 无断点续传 | 失败后从头重来，浪费时间 | 从失败点继续修复，不重新开始 |
|
||||
| 缺乏人机边界 | Agent 擅自做架构决策 | 架构变更必须由你审批 |
|
||||
|
||||
## 范式对比：Harness 不是取代，而是进化
|
||||
|
||||
Harness Engineering 建立在前人范式之上，将"编码实现"层交给 AI Agent：
|
||||
|
||||
Reference in New Issue
Block a user