本文记录一个真实的企业级 Java 后端项目（Spring Boot 2.7 + MyBatis-Plus）如何基于krio从零构建 AI Agent Harness 体系的完整实践。
一、问题：AI Agent 在企业级项目中为什么不好用？
把 AI Agent 扔进一个有 20 万行代码的企业级 Java 项目，你会发现四个核心痛点：
这四个痛点不是 Prompt Engineering 能解决的——你不可能每次对话都手动把所有规则、业务知识、验证流程重新告诉 Agent 一遍。
需要的是一个系统性的解决方案：Harness Engineering。
二、框架：Harness Engineering 的四个维度
Prompt Engineering 解决"怎么跟 AI 说话"。Context Engineering 解决"给 AI 看什么"。Harness Engineering 解决"怎么让 AI 在企业级项目中持续、可靠地干活"。
Harness Engineering（最外层 - 整个 Agent 系统的设计）
|-- Context Engineering（上下文工程 - 管理所有喂给 LLM 的信息）
| |-- Prompt Engineering（提示工程 - 优化指令文本）
| +-- 工具定义、RAG、消息历史、MCP 数据、仓库知识库...
|-- Architectural Constraints（架构约束 - 确定性的强制执行）
|-- Entropy Management（熵管理 - 持续的质量维护）
+-- Workflow Control（工作流控制 - Agent 的运行时管理）四个维度对应四个痛点：
三、实践：我们怎么做的
3.1 Context Engineering — 给 Agent 精准的上下文
核心问题：Agent 每次干活都需要知道"规矩是什么"和"业务是什么"，但不能把所有信息一股脑塞进去（token 有限、噪音会降低遵守率）。
我们的解法：分层加载 + 领域文档 + 知识图谱。
Steering 规则：分层按需加载
Steering 是 Kiro 的规则文件机制，我们按"加载时机"分为两类：
关键设计决策：Steering 只写可执行约束，禁止写科普性内容。
反例："新表和老表的区别在于主键生成策略不同..."（科普，Agent 看了也不知道该怎么做）
正例："新表 Entity 必须继承 BaseEntity，审计字段由 FieldFill 自动填充，禁止手动 set"（约束，Agent 直接遵守）
领域文档：业务知识库
每个业务领域在 docs/domain/{领域名}/ 下维护五个标准文档：
消费方式：Spec 创建时 requirements.md 引用业务规则和决策记录，design.md 引用 API 契约和数据模型。开发完成后代码变更反向更新文档，形成正向循环。
冷启动问题用 domain-doc-builder Skill 解决——Agent 扫描代码生成初稿，人工校验修正。
MCP 知识图谱：结构化代码理解
通过 code-review-graph MCP Server 提供代码知识图谱，Agent 探索代码时优先用图谱（比 grep 更快、消耗更少 token、提供调用者/依赖方/测试覆盖等结构化上下文）。
3.2 Architectural Constraints — 用确定性约束概率性
核心问题：Steering 规则的遵守率是 60-90%，不是 100%。10-40% 的情况下 Agent 会违反规则而不自知。
我们的解法：确定性检测脚本 + 编码规范 + 项目规范。
确定性检测层（Lint 脚本）
核心理念来自 OpenAI Codex：linter 的错误信息本身就是修复指令——Agent 看到报错就知道怎么改。
错误输出设计原则——四要素，让 Agent 看到就能自己修：
[LINT FAIL] {规则名称}
文件: {文件路径}:{行号}
违规: {具体违规内容}
修复: {修复指令，Agent 可直接执行}不是告诉 Agent "你错了"，而是告诉它"你错了，这样改"。
编码规范的确定性约束
Steering 规则中的编码规范（Java编码规范、MyBatis规范、Spring规范）通过 fileMatch 在编辑对应文件时自动加载，确保 Agent 写代码时"看得到规矩"。但看得到不等于遵守——所以 Lint 脚本作为确定性兜底。
两层防线的关系：
Steering 规范 = 事前约束（告诉 Agent 怎么做，遵守率 60-90%）
Lint 脚本 = 事后检测（检查 Agent 有没有做到，遵守率 100%）
3.3 Workflow Control — 让流程自动跑起来
核心问题：Agent 没有记忆，不能指望它"记住"该跑测试、该更新文档、该做审查。
我们的解法：Hook 自动化 + Spec 结构化工作流 + 子代理专业化分工 + Skill 能力包。
Hook：极简自动化（仅 3 个）
经过四轮演进，从最初的 7 个 Hook 精简为 3 个：
为什么从 7 个精简到 3 个？因为发现 Steering 规则 always-on 可以替代大部分 askAgent 类型的 Hook——Steering 已经告诉 Agent "什么时候必须做什么"，不需要额外的 Hook 提醒。Hook 只保留"Agent 想跳也跳不过"的自动化。
Spec 工作流：结构化功能迭代
一次功能开发的完整流程：
需求输入 → 需求澄清（Skill）→ requirements.md → 方案比对 → design.md → tasks.md → 子代理执行 → 文档更新 → 归档每个功能切片按"垂直切片三件套"编排：
Task 1: {功能} - 开发 ← Kiro 原生执行
Task 1-review: {功能} - 审查 ← 并行调用 3 个 reviewer 子代理
Task 1-test: {功能} - 测试 ← 调用 test-writer 子代理子代理：专业化分工（6 个）
核心理念：活可以分出去，思考不行。主代理自己消化信息、做出判断、给出明确方向，再委派给子代理执行。
Skill：可复用能力包（7 个）
五层验证体系
3.4 Entropy Management — 让系统自我进化
核心问题：AI Agent 没有记忆，每次对话都是全新的。如果规则不持久化，同样的错误会反复出现。
我们的解法：三个机制 + 规范演进日志。
三个核心机制
规则固化标准
不是所有发现都值得写入规范。三个条件全部满足才固化：
可复现性：这个问题会在未来再次出现
可执行性：规则足够具体，Agent 能直接遵守（不是"注意代码质量"这种空话）
通用性：不是只针对某一次特殊情况
判定验证
区分"个案"和"系统性缺陷"的方法：
换一个全新 Agent（没有本次对话的上下文），执行同样的任务，仅凭当前 Steering 规则，能否避免这个问题？
能避免 → 个案，不需要固化。不能避免 → 系统性缺陷，必须提炼规则。
禁止用"下次会注意"、"下次会更严格"等无法持久化的承诺替代规则固化。没有记忆的智能体，必须靠规则而非承诺。
规范演进日志
docs/规范演进日志.md 记录每次规则变更的来源、内容和原因。只追加，不修改。是整个自成长体系的"审计轨迹"。
四、知识流转闭环
整个 Harness 的核心逻辑是一个自增强的正向循环：
graph TB
A["开发新功能"] -->|引用| B["领域文档（已有知识）"]
A -->|Steering 自动加载| C["项目规范 + 编码规范"]
A -->|执行| D["代码产出"]
D -->|Hook + Lint 自动验证| E{通过?}
E -->|否| A
E -->|是| F["功能完成"]
F -->|覆盖更新| B
F -->|如有流程改进| C
G["执行中出错"] -->|执行复盘 Hook| H["提炼新规则"]
H -->|写入| C
H -->|记录| I["规范演进日志"]
J["用户重复要求"] -->|Steering always-on| H每次开发都消费已有知识，同时沉淀新知识。每次出错都提炼新规则，下次不再犯。
五、踩坑清单（精选）
六、落地路线图
七、核心理念
这套 Harness 的本质是：
用确定性的机制（Steering 规则、Hook 自动化、Lint 脚本、子代理审查）约束概率性的 AI Agent，同时通过自成长体系让确定性的机制本身也在持续进化。
不是让 Agent 更聪明，而是让 Agent 犯错的空间更小。
