Harness 架构设计

打破砂锅问到底007

379人浏览 · 2026-05-19 09:44:16

打破砂锅问到底007 · 2026-05-19 09:44:16 发布

Harness 架构设计

AI Coding 落地方案

第零章 · 浓缩版

0.1 一页结论（一句话讲清）

Harness 不是"把规则写多"，而是把 AI 从"个人经验驱动"升级为"组织能力驱动"的一整套运行系统。

它要回答的不是"AI 会不会写代码"，而是 5 个问题：

#	问题	Harness 给的答案
1	AI 能看什么	环境层：信息边界、权限、脱敏
2	AI 能调用什么	工具层：统一 MCP 工具注册表
3	AI 按什么流程工作	Agent 层 + 编排层：角色 + DAG
4	出错怎么发现、修复、不再犯	评测层：Badcase 闭环
5	规则会不会过时	熵管理：定期复审、漂移检测

0.2 5 分钟讲述脚本

第 1 分钟 · 拔高：“我们前期搜集了不少规则，但规则是’点’。今天讲的 Harness 是’面’——把规则、上下文、流程、评测拼成一套可治理的运行体系，让 AI 在金融这种高合规场景能跑稳。”

第 2 分钟 · 三维：“设计哲学是三个维度：Agent 该知道什么（上下文）、只能在边界内做什么（约束）、长期不腐化（熵管理）。”

第 3 分钟 · 五层：“运行体系是五层堆叠的：环境层定边界、工具层定接口、Agent 层定角色、编排层定流程、评测层定闭环。最重要的是底下两层和最上面一层——先把红线和评测立起来，中间会自然长出来。”

第 4 分钟 · 落地：“新项目我会先写 AGENTS.md + Rules + Linter + Badcase 闭环这 4 件事；老项目按’读 → 改 → 重构’三段引入。规则我们已经在做收集，下一步要按 P0 红线 / P1 黄线 / P2 建议 分级。”

第 5 分钟 · 收口 + Q&A：“核心价值三句话：化零为整（碎片规则资产化）、合规保驾（资金红线在体系内被强约束）、数据驱动（Badcase 让体系自演进）。这就是我对 Harness 架构的整体思考。”

第一章 · 为什么必须做 Harness

1.1 现状定位：我们处在"Copilot 辅助"阶段

问题	表现	影响
质量不可控	同一任务，不同人 Prompt 不同，AI 产出差异大	代码质量参差不齐，Review 成本高
经验不可积累	每人各自摸索，无法沉淀为组织能力	团队能力无法规模化提升
合规不可审计	AI 生成代码缺过程记录与规则约束	金融合规审计要求难满足

引用 Mitchell Hashimoto 的设计哲学：
“每当你发现 Agent 犯了一个错误，你就花时间设计一个解决方案，使 Agent 永远不再犯同样的错误。”

1.2 为什么"只搜集规则"不够

规则收集解决	规则收集解决不了
AI 代码该怎么写、不该写什么	AI 出错了怎么发现、修复、回归
	多 Agent 协同时任务怎么分工、结果怎么聚合
	合规边界、数据权限怎么强约束
	半年后规则过时谁来更新、谁负责

结论：规则只是 Harness 体系里 Agent 层下的一小块（Rules 载体），不能替代体系本身。

第二章 · Harness 在企业技术架构中的定位

2.1 Harness 是横跨"应用 / 技术"之间的 AI 管控层

┌─────────────────────────────────────────────────────────────┐
│                    业务架构（Business）                       │
│          金融业务流程、合规规则、风控策略                  │
├─────────────────────────────────────────────────────────────┤
│                    应用架构（Application）                    │
│       产业数字化平台  ←→  数字金融化平台  ←→  运营管理平台     │
├─────────────────────────────────────────────────────────────┤
│               ┌─────────────────────────────┐               │
│               │    Harness 架构（AI 管控层）  │               │
│               │  L5: Evaluation  评测层      │               │
│               │  L4: Orchestration 编排层    │               │
│               │  L3: Agent     Agent 层      │               │
│               │  L2: Tool      工具层        │               │
│               │  L1: Environment 环境层      │               │
│               └─────────────────────────────┘               │
├─────────────────────────────────────────────────────────────┤
│                    技术架构（Technology）                     │
│          基础设施、大模型服务、MCP 协议、CI/CD 流水线          │
└─────────────────────────────────────────────────────────────┘

关键认知：Harness 不是独立系统，而是一层治理面——接收业务架构的规则约束，在技术架构之上运行，保障 AI 能力在应用架构中稳定落地。

2.2 Harness 的边界：哪些事 Harness 不做

整合时容易出现一个误区——把所有"AI / 代码 / 工程治理"的事都塞进 Harness。本节明确边界：

事项	谁来做	与 Harness 的关系
编码规范（命名、格式）	Checkstyle / ESLint	Harness 引用其结果，不重新发明
静态扫描（漏洞、复杂度）	SonarQube / SpotBugs	Harness 的 Linter 调用其规则集
CI/CD 流水线	Jenkins / GitLab CI	Harness 的工作流跑在 CI 里，不替代 CI
代码 Code Review	人 + AI Review Agent	Harness 提供 Review Agent 的 Rules
安全合规审计	安全部门 + 审计部门	Harness 提供审计日志与 Trace
业务需求与 PRD	产品 + 业务架构	Harness 把 PRD 转换为机器可读的 Spec
大模型选型与计费	平台/采购	Harness 抽象工具层，预留切换能力

一句话：Harness 是"AI 在企业内的安全带和仪表盘"，不是替代既有工程能力，而是把它们编排起来供 AI 使用。

2.3 Harness 与现有技术体系的对应

Harness 概念	对应传统体系	金融场景示例
Environment（环境层）	网络隔离、RBAC、数据脱敏	风控数据与贸易数据访问隔离
Tool（工具层）	API Gateway、契约测试	MCP 协议接入银行接口、中登网
Agent（Agent 层）	微服务、任务调度	审单 Agent、风控 Agent、编码 Agent
Orchestration（编排层）	工作流引擎、BPM	融资审批全流程编排
Evaluation（评测层）	质量门禁、CI/CD、监控告警	AI 审单准确率评测、Badcase 库

第三章 · 三维治理框架（设计哲学）

来源：Thoughtworks Birgitta Böckeler 在 Martin Fowler 官网发布的 Harness Engineering 三维度框架。
五层架构是"结构"，三维框架是"灵魂"。

┌──────────────────────┐  ┌──────────────────────┐  ┌──────────────────────┐
│  维度一：上下文工程    │  │  维度二：架构约束      │  │  维度三：熵管理        │
│  Agent 该知道什么     │  │  Agent 只能在边界内行事│  │  系统长期不腐化        │
│                      │  │                      │  │                      │
│ • 渐进式文档披露      │  │ • 确定性 Linter      │  │ • 文档漂移检测         │
│ • 分层记忆管理        │  │ • LLM 审计 Agent      │  │ • 规则过时预警         │
│ • RAG 知识检索        │  │ • 违规→检测→修复闭环  │  │ • 专用清理 Agent       │
└──────────────────────┘  └──────────────────────┘  └──────────────────────┘

3.1 维度一：上下文工程

核心问题：Agent 该知道什么？什么时候知道？

渐进式披露：入口 AGENTS.md ≤ 100 行 → 指向子文档；单文档 ≤ 32KB。
分层记忆：工作记忆（当前任务）+ 短期记忆（近 10-20 步摘要）+ 长期记忆（RAG）。
动态组装：按任务类型选注入哪些 Rules / Skills，避免上下文噪音。
实时数据接入：通过 MCP 协议访问实时融资状态、风控参数、汇率等动态数据。

3.2 维度二：架构约束

核心问题：如何确保 Agent 只在边界内行事？

确定性 Linter：专为 Agent 输出优化（不是给人写的代码用的）。
双轨审计：轨 1 确定性规则（100% 自动）+ 轨 2 LLM 语义审查（抽样 + 高风险全量）。
违规闭环：违规不只告警 → 给出明确修复路径 → 高频违规自动触发规则评审 → 回归验证。

3.3 维度三：熵管理（最易忽视，最重要）

核心问题：如何防止系统随时间腐化？

手段	描述	频率
专用清理 Agent	扫描过时规则与文档，生成漂移报告	每周
文档漂移检测	文档描述与实际代码不一致	每次 PR 合并
规则过时预警	业务系统变更后关联规则自动标记复审	按需
Harness 架构复审	架构委员会审视体系健康度	每季度

第四章 · 五层运行架构详解

4.0 五层全景

┌─────────────────────────────────────────────────┐
│   L5  Evaluation Layer（评测层）                 │  质量评测 · Badcase · 回归 · 可观测
├─────────────────────────────────────────────────┤
│   L4  Orchestration Layer（编排层）              │  DAG · 多 Agent 协同 · HITL 节点
├─────────────────────────────────────────────────┤
│   L3  Agent Layer（Agent 层）                    │  角色 · 任务执行 · 状态维护
├─────────────────────────────────────────────────┤
│   L2  Tool Layer（工具层）                       │  工具注册 · MCP · 异常处理
├─────────────────────────────────────────────────┤
│   L1  Environment Layer（环境层）                │  信息边界 · 权限 · 脱敏 · 沙箱
└─────────────────────────────────────────────────┘
        ↑ 上层依赖下层；下层是上层的"安全底座"

实施建议（重要）：先立 L1 + L5，再逐步把 L2 / L3 / L4 长起来。L1 是底线、L5 是反馈，缺一个都做不出"可演进的体系"，中间层是可以渐进补的。

4.1 L1 · Environment Layer（环境层）

核心职责：定义 Agent 能访问什么、不能访问什么、不能做什么。

4.1.1 核心能力

信息边界：按业务域划分可读路径、可访问数据库、可调用 API
权限控制：RBAC + ABAC 双轨；Agent 角色分读取型 / 写入型 / 审批型；子 Agent 不超父 Agent
数据脱敏：账号、融资金额、PII 自动脱敏
输出约束：危险操作白名单 + 不可逆操作二次确认 + 合规前置校验

4.1.2 双平台映射

机制	产业数字化	数字金融化
可读	贸易合同、物流、发票	风控规则、融资记录、银行反馈（只读）
禁止访问	融资台账、风控分值	核心系统直写、绕过风控放款
脱敏	联系人姓名脱敏，企业全名保留	账户与融资金额仅供审查、不得透传
跨域	通过 Harness 审批流交换；不直接传敏感数据，只传索引 ID

4.1.3 落地交付物

environment-config.yaml：权限矩阵
data-classification.md：数据分级（公开 / 内部 / 机密 / 严格保密）
forbidden-operations.md：禁止操作清单

4.1.4 配置示例

environment:
  readable_paths: [src/, docs/, tests/]
  forbidden_paths: [.env, config/prod/, data/customer/]
  forbidden_operations:
    - "DROP TABLE"
    - "DELETE FROM"
    - "直接修改风控阈值"
    - "绕过审批节点"
  masking_rules:
    - { pattern: "银行账号", method: "保留前4后4" }
    - { pattern: "身份证号", method: "保留前3后4" }

4.2 L2 · Tool Layer（工具层）

核心职责：定义 Agent 能调用什么工具、如何调用、失败怎么办。

4.2.1 工具定义规范（标准字段）

tool_id: scf_contract_parser
name: 合同智能解析工具
version: "2.1.0"
description: 提取合同关键要素（编号、金额、付款条款等）
input_schema:
  type: object
  required: [contract_text, contract_type]
output_schema:
  type: object
  properties:
    contract_id: { type: string }
    amount: { type: number }
    parse_confidence: { type: number, minimum: 0, maximum: 1 }
permissions_required: [contract_read]
timeout_seconds: 30
retry_policy: { max_retries: 3, backoff_strategy: exponential }

4.2.2 异常处理分级

轻微异常（自动重试）：网络超时、临时不可用
中度异常（降级处理）：置信度低、结果需人工确认
严重异常（终止 + 告警）：权限违规、数据异常
灾难性异常（回滚 + 上报）：影响生产数据的不可逆操作

4.2.3 核心工具目录（示例）

Tool ID	名称	所属域	权限
`scf_contract_parser`	合同智能解析	产业数字化	内部只读
`invoice_validator`	发票三要素核验	产业数字化	内部只读
`trade_background_check`	贸易背景验证	产业数字化	内部只读
`risk_score_query`	企业风险评分查询	数字金融化	机密只读
`credit_limit_check`	授信额度查询	数字金融化	机密只读
`loan_application_create`	融资申请创建	数字金融化	机密写入 + 审批
`code_linter`	代码规范检查	开发工具	普通
`unit_test_runner`	单元测试执行	开发工具	普通

4.2.4 落地交付物

tools-registry.yaml：工具注册表
tools-exception-handling.md：异常处理标准
tools-audit-dashboard：调用监控看板

4.3 L3 · Agent Layer（Agent 层）

核心职责：定义 Agent 角色、能力边界、协同机制、状态管理。
这一层是当前规则收集工作的"归宿地"。

4.3.1 设计原则

单一职责：一个 Agent 聚焦一类任务
显式边界：不允许模糊扩展
标准化通信：角色间通过标准接口通信，不直接共享状态

4.3.2 Agent 矩阵

AI Coding 域（本期重点）

Agent	职责	输入	输出	边界
需求解析 Agent	PRD → Spec	PRD	任务分解 + Spec	只输出规格，不写代码
编码 Agent × N	按 Spec 实现模块	Spec + 代码上下文	代码片段	只操作指定目录
Review Agent	多维检查代码	代码 diff	审查报告 + 建议	只读，结论供人工最终确认
测试 Agent	生成测试用例	代码	测试代码	覆盖率 ≥ 80%
文档 Agent	同步代码与文档	代码 diff	接口文档 / CHANGELOG	不修改代码逻辑

业务域（后续扩展）

Agent	职责	关键约束
审单 Agent	贸易背景审核	准确率 > 99%，不确定项转人工
风控 Agent	融资风险评估	决策必须可解释可追溯
合规 Agent	监管合规检查	规则变更需人工审批后生效

4.3.3 状态管理

初始化 → 接收任务 → 规划步骤 → 逐步执行 → 自检验证 → 提交结果
                                  │
                              遇到异常？
                            ╱            ╲
                       可自恢复          不可自恢复
                          │                │
                      重试 / 降级        转人工处理

4.4 L4 · Orchestration Layer（编排层）

核心职责：让多个 Agent 像有序团队一样工作。

4.4.1 四种基本编排模式

模式	适用	典型例子
顺序编排	严格先后依赖	融资申请：合同核验 → 贸易验证 → 风控评估 → 放款
并行编排	相互独立	智能审单：发票 + 提单 + 合同 + 资质同时核验
条件路由	分支决策	风控分 ≥ 80 自动审批 / 50-80 人工 / <50 拒绝
自反思	高质量产出	代码生成 → Review → 修复（最多 3 轮）→ 通过

4.4.2 AI Coding 编排流程（本期重点）

开发者提交 Spec
   │
   ▼
编码 Agent 生成代码 ──失败──▶ 开发者修正 Spec
   │ 成功
   ▼
Linter 检查 ──不通过──▶ 编码 Agent 修复 ──▶ 回到 Linter（≤3 次）
   │ 通过
   ▼
测试 Agent 运行测试 ──不通过──▶ 编码 Agent 修复 ──▶ 回到测试
   │ 通过
   ▼
Review Agent 代码审查 ──问题──▶ 编码 Agent 修复 ──▶ 回到 Review
   │ 通过
   ▼
【HITL 人工最终确认】
   │
   ▼
合并代码 / 部署

HITL（Human-in-the-Loop）：阶段一所有 AI 生成代码最终合并必须经人工确认；阶段三起逐步放开低风险场景。

4.4.3 状态机示例

workflow_id: trade_finance_application
states: [INITIATED, CONTRACT_VERIFIED, TRADE_BACKGROUND_VERIFIED,
         RISK_ASSESSED, PENDING_APPROVAL, APPROVED, LOAN_EXECUTED,
         COMPLETED, FAILED, CANCELLED]
failure_handling:
  max_retry: 3
  on_final_failure: notify_operations + log_badcase

4.4.4 落地交付物

workflow-definitions/：工作流 DAG
orchestration-patterns.md：编排模式选择指南
state-machine-spec.yaml：核心业务状态机

4.5 L5 · Evaluation Layer（评测层）

核心职责：让 Harness 能自我进化。

4.5.1 评测体系三支柱

支柱一 · 评测数据集

类别	数量目标	内容	更新
编码任务集	100+	CRUD、业务逻辑、边界	双周追加
审查任务集	50+	含已知 Bug 代码，验证检出率	每月追加
金融场景集	50+	合同解析、风控、审单	按业务需求

支柱二 · Badcase 五步法

发现 → 分类 → 根因 → 策略调整 → 回归

分类体系（参考占比）：
  Prompt 不清晰（40%）→ 优化 Prompt / AGENTS.md
  Context 不足（30%）→ 补 RAG / 上下文
  工具调用错（15%）→ 优化工具定义
  规则缺失（10%）→ 新增 Rules
  模型能力边界（5%）→ 标记人工处理

支柱三 · 度量看板

指标	定义	阶段一目标	阶段二目标
任务完成率	Agent 成功完成比例	≥ 80%	≥ 90%
首次通过率	首次过 Lint + 测试	≥ 60%	≥ 80%
Code Review 通过率	人工 Review 一次通过	≥ 50%	≥ 75%
规则违规次数	触碰红线次数	0	0
Badcase 修复周期	发现到修复	≤ 3 天	≤ 1 天
AI 辅助人均产出提升	引入前后对比	+30%	+60%

4.5.2 可观测性三支柱

Trace（链路追踪）：每一步执行 + 决策快照
Metrics（指标监控）：完成率、延迟、Token、工具调用热点
Logs（结构化日志）：决策日志、异常日志、不可删改审计日志

4.5.3 落地交付物

evaluation-dataset/：标准评测集
badcase-library.md：Badcase 积累库
monitoring-dashboard-config：看板配置
evaluation-runbook.md：评测操作手册

第五章 · 知识显式化体系：Spec / Rules / Skills + AGENTS.md

5.1 三种载体的分工

载体	定义	核心特点	示例	落地位置
Spec（规格）	机器可读的业务意图	人机双读、精确无歧义	融资接口契约、合同解析输出规范	`docs/specs/`
Rules（规则）	可执行 if-then 逻辑	机器直接执行、硬约束	风控准入阈值、安全合规红线	`.cursor/rules/` 或 `AGENTS.md`
Skills（技能）	封装好的能力单元	可复用、可组合	合同要素抽提、发票真伪核验	`.claude/skills/` 或 `skills/`

5.2 规则文件载体的双格式策略

与本项目 001-Harness工程知识图谱.md 的"双格式并行"策略保持一致。

载体	适合放什么	谁会读
`.cursor/rules/*.mdc`	强约束、风格、偏好（细粒度，按 `globs` 触发）	Cursor IDE
`CLAUDE.md` / `AGENTS.md`（项目根）	项目导航、技术栈、红线、命令清单（粗粒度）	Claude Code / Cursor CLI / OpenAI Codex CLI
`.github/copilot-instructions.md`	同上（如启用 Copilot）	GitHub Copilot

原则：一处为权威（推荐 AGENTS.md），其他载体引用；避免规则双源漂移。

5.3 AGENTS.md 双栈模板

兼顾老栈（Java 8 + Vue 2）与新栈（Java 17 + Vue 3），按项目实际删去不相关部分。

5.3.1 老栈模板（Java 8 + Vue 2 + Spring Boot 2.x）

# AGENTS.md - 管理系统

## 1. 项目概述
本项目负责核心企业授信额度、应收账款流转额度、风险敞口计算。
对资金安全、事务一致性具有极高要求。

## 2. 技术栈（务必遵守版本）
- 后端：Java 8 + Spring Boot 2.x + MyBatis（XML 优先）+ MySQL 8
- 前端：Vue 2 + Vuex + Element UI
- 构建：Maven（避免引入 Java 17+ 语法：record/sealed/switch 模式匹配等）

## 3. 核心架构约束
- 分层：Controller → Service → Repository（不允许跳层）
- 所有额度变更必须通过 Seata SAGA 进行分布式事务
- 严禁循环中直接操作数据库
- 数据库变更必须通过 Flyway 迁移脚本

## 4. 工具与开发命令
- 单元测试：`mvn clean test`（覆盖率 ≥ 80%）
- 代码规范：`mvn spotless:apply`
- 静态扫描：SonarQube 必须 0 Critical
- 外部依赖：所有中登网 / 核心企业 ERP 调用走 `src/main/resources/mcp/`

## 5. 绝对红线（Forbidden Zone）
- 🚫 禁止修改 `src/main/java/com/scf/quota/risk/` 下的底层风控核心
- 🚫 禁止注入任何跳过风控审批、直接置 `APPROVED` 的代码
- 🚫 禁止硬编码任何密钥、密码、生产连接串
- 🚫 金融计算禁止 `float` / `double`；必须 `BigDecimal`
- 🚫 `BigDecimal` 比较禁止 `equals`，使用 `compareTo`
- 🚫 禁止删除审计日志相关代码

## 6. 业务术语
- 确权：核心企业确认应收账款真实性
- 流转：应收账款凭证在供应商之间转让
- 融资：持有凭证的供应商向银行申请贷款

5.3.2 新栈模板（Java 17 + Vue 3 + Spring Boot 3.x）

将 §5.3.1 的「技术栈」部分替换为：

后端：Java 17 + Spring Boot 3.x（jakarta.*）+ MyBatis-Plus 或 Spring Data JPA

前端：Vue 3 + TypeScript + Composition API + Pinia + Element Plus

其他章节保持一致；可逐步启用 record / sealed / 模式匹配。

第六章 · 规则分级体系（P0 / P1 / P2）

这是 04-Opus 文档独有的实操亮点，整合保留。

级别	名称	处置方式	触发后动作	示例
P0 - 红线	强制阻断	立即停止，必须人工介入	CI 阻断 / Agent 拒绝执行	硬编码密钥、SQL 注入、绕过风控、金额用 `double`
P1 - 黄线	自动修复	Agent 自动修复，修复后继续；3 次失败转人工	自动重试	Lint 错误、类型不匹配、缺单测、命名违规
P2 - 建议	提示优化	给出建议，不阻断	仅记录	命名不够语义化、可优化的性能写法

配套机制：

P0 规则变更必须走 架构委员会评审，不允许个人提交直接合并。
P1 / P2 规则可按团队习惯调整，但需在 AGENTS.md 引用。
所有 P0 违规必须沉淀到 Badcase 库，作为永久回归用例。

第七章 · 双平台业务场景落地设计

7.1 场景一：智能审单（产业数字化）

业务背景：当前人工审单单笔 2-4 小时，错误率 3-5%。

层	配置要点
环境层	可访问：贸易合同、发票、物流、商品；禁止：融资台账、风控模型；脱敏：客户账号
工具层	`invoice_ocr_tool` / `contract_parser_tool` / `trade_match_tool` / `anomaly_detector_tool`
Agent 层	Skills：三要素核验 + 贸易真实性判断 + 异常标记；Rules：发票早于合同日期自动异常等
编排层	并行核验 → 三单匹配 → 异常分析 → 条件路由（无异常自动 / 有异常人工）
评测层	准确率 / 异常识别率 / 漏检率；目标准确率 ≥ 98%、时效 ≤ 15 分钟

预期收益：参考联易融同类实践，效率提升 10-20 倍，准确率从 95-97% → 98-99%。

7.2 场景二：AI Coding 代码生成（本期落地起点）

层	配置要点
环境层	仅限分配模块目录；禁止：直接推 main、改 CI、删测试、访问生产数据
工具层	code_read / code_write / test_runner / lint_check / git_commit（不可直接合并）
Agent 层	Rules：参数化 SQL、金融计算用 BigDecimal、禁止 any、新功能必须含单测
编排层	Spec → 编码 → Lint → 测试 → Review →（自反思最多 3 轮）→ PR → 文档同步
评测层	首次通过率、PR 平均轮次、规则违规率（目标 0）、Badcase 修复周期（≤ 3 天）

第八章 · 老项目改造路径（独立成章）

“新项目用 AI Coding，老项目逐步用 AI agent”。本章专门为老代码库改造给出可执行路径。

8.1 老项目的现实挑战

挑战	描述	对 Harness 的要求
缺文档	接口、业务逻辑没文档或文档失效	需先做"文档反向工程"
耦合高	类/模块边界模糊，AI 不知道改一处会牵动多处	必须先画出"模块边界图"
测试覆盖低	改完不敢合并，怕回归	AI 必须先补单测再动
版本旧	Java 8 / Vue 2 / Spring Boot 2.x，部分 API 已不推荐	规则中明确"禁止使用 Java 17+ 特性"
业务在跑	不能停服改造	必须分支隔离 + 灰度策略

8.2 三段式改造法：“读 → 改 → 重构”

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  阶段 A 读  │ ──▶│  阶段 B 改  │ ──▶│ 阶段 C 重构 │
│  零侵入     │    │  小步快跑   │    │  谨慎演进   │
│  只读理解   │    │  补丁式修改 │    │  结构性优化 │
└─────────────┘    └─────────────┘    └─────────────┘

8.2.1 阶段 A · 读（第 1-4 周，零风险）

目标：让 AI "看懂"老项目，沉淀为可复用的文档与术语表。

任务	用谁做	产出
反向生成模块边界图	文档 Agent	`docs/legacy-map.md`
反向生成接口契约（OpenAPI）	文档 Agent + 人工校对	`docs/specs/legacy-api.yaml`
提取业务术语 → 写入 `AGENTS.md`	业务架构师	`AGENTS.md` 术语段
标记"危险区"（核心风控、资金路径）	业务架构师 + 风控	`AGENTS.md` 红线段

不允许 AI 写任何代码；只产出文档。这一阶段建立信任、积累 Context。

8.2.2 阶段 B · 改（第 5-12 周，低风险）

目标：从"补丁式修改"开始让 AI 动手。

首选场景（按风险从低到高）：

单元测试补全（无业务风险）
日志增强、注释补全、命名规范化
Bug 修复（已确认的小范围）
非核心接口的字段新增
前端样式 / 文案微调

禁止场景：

❌ 核心风控逻辑
❌ 资金路径
❌ 数据库 Schema 变更
❌ 跨模块重构

强制流程：每个 PR 必须经 Linter + Test + Review Agent + 人工 HITL 四道关。

8.2.3 阶段 C · 重构（第 13 周+，谨慎演进）

目标：在 Spec 与单测齐全的前提下，让 AI 做"结构性重构"。

任务	前置条件	风险控制
抽取重复代码	单测覆盖 ≥ 80%	一次只动一个模块
接口下沉 / 上浮	接口契约完整	灰度发布 + 双跑对比
老 API → 新 API 迁移	制定迁移 Spec	老接口保留 6 个月
框架版本升级（Vue 2 → 3）	全量回归测试集	分支隔离，可回退

8.3 老项目 AGENTS.md 的特殊条款

## 老项目改造专项约束

### 改动范围
- 本次改造仅允许修改 `src/main/java/com/scf/<模块>/` 下的代码
- 跨模块改动必须发起独立任务，禁止顺手改

### 单测先行
- 任何代码修改前，必须先补齐对应单元测试
- 单测必须覆盖修改前后的行为对比

### 文档同步
- 改动接口必须同步更新 `docs/specs/legacy-api.yaml`
- 改动业务规则必须更新 `AGENTS.md` 术语段

### 灰度策略
- 所有合并到 develop 的改动必须经过 7 天灰度
- 资金相关改动必须人工双人 Review

第九章 · 分阶段实施路线图

9.1 四阶段路线图

       第1-6周           第7-16周          第17-28周         第29周+
   ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
   │  阶段一       │ │  阶段二       │ │  阶段三       │ │  阶段四       │
   │  夯实基础     │ │  能力积累     │ │  规模落地     │ │  自进化       │
   │              │ │              │ │              │ │              │
   │ AGENTS.md    │ │ 编排流程      │ │ 业务 Agent   │ │ Dreaming     │
   │ Rules        │ │ Badcase 库   │ │ 多 Agent 协同 │ │ Outcomes     │
   │ Linter       │ │ Skills 库    │ │ 熵管理       │ │ 自优化闭环    │
   │ 评测集       │ │ 评测看板      │ │ 最佳实践     │ │              │
   └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
    ◄── Copilot+ ──► ◄── Agent 辅助 ──► ◄── Agent 自主 ──► ◄── 自进化 ──►
    我们在这里 ▲

9.2 阶段一：夯实基础（第 1-6 周）

目标：从个人摸索 → 团队统一规范

周次	动作	负责人	产出
W1-2	梳理现有编码规范 → Rules	Tech Lead	编码规范 Rules
W3-4	编写 AGENTS.md + 配置 Linter	架构组	AGENTS.md + Linter
W5-6	搭建评测数据集 + Badcase 流程	QA + 开发	评测集 + Badcase 模板

里程碑：所有开发使用统一 AGENTS.md，AI 代码 Lint 通过率 > 70%。

9.3 阶段二：能力积累（第 7-16 周）

目标：从统一规范 → 体系化 Harness

周次	动作	产出
W7-8	搭建编排流程，自动化检查链	编排流程配置
W9-10	积累 Badcase，提炼共性问题	Badcase 库 v1
W11-12	构建 Skills 库	Skills 库 v1
W13-14	搭建评测看板 + 度量基线	看板 + 基线
W15-16	反馈闭环首次完整运行	闭环验证报告

里程碑：AI 代码首次通过率 > 60%，Badcase 闭环时长 < 3 天。

9.4 阶段三：规模落地（第 17-28 周）

目标：从 AI Coding → 业务场景扩展

业务 Agent 试点（审单 / 合同解析）
多 Agent 协同流程
熵管理机制（规则过时检测、文档漂移扫描）
完善度量体系
Harness 最佳实践手册

里程碑：AI 辅助人均产出 > +60%，核心场景规则覆盖率 > 90%。

9.5 阶段四：自进化（第 29 周+）

Dreaming 试点
跨会话知识自动沉淀
Outcomes 评分体系
Agent 持续自优化闭环

9.6 近期行动清单

时间	行动	负责人	产出
05.19-05.23	选定第一个试点项目	业务架构师	试点确认单
05.19-05.23	编写试点 AGENTS.md	技术架构师	AGENTS.md v0.1
05.26-05.30	数据分级标准	业务架构师	数据分类标准
05.26-05.30	核心工具目录梳理	技术架构师	tools-registry v0.1
06.02-06.06	初版评测集 ≥ 30 用例	QA	评测集
06.09	阶段一成果汇报	全员	量化效果数据

第十章 · 评估体系与度量指标

10.1 分层评估（先人工，再 AI）

阶段	评估方式	适用范围
一	纯人工评估	人工审 AI 代码，建立基线
二	人工为主 + AI 辅助	人工定标准，Review Agent 执行
三	AI 为主 + 人工抽检	AI 自动评估，人工按比例抽检
四	AI 自评 + Dreaming 自优化	全自动闭环，人工只看异常

10.2 核心 KPI

KPI	定义	目标	采集
AI 代码采纳率	AI 代码被采纳比例	阶段二 > 60%	Git 分析
首次通过率	首次过 Lint + 测试	阶段二 > 60%	CI 统计
Badcase 闭环率	已修复为 Rule 的比例	> 90%	Badcase 库
人均产出提升	引入前后对比	阶段二 +30%	交付数据
规则月增长	有效 Rules 月增数	≥ 10 条	规则库

第十一章 · 行业标杆对标

11.1 对标矩阵

维度	Stripe Minions	OpenAI Codex	联易融	我们的方案
工具管理	MCP Toolshed 500+	Codex 统一工具链	蜂联专项	MCP 统一注册
编排	中心化任务分发	多 Agent 协作	审单自动化	DAG + HITL
评测	每周 1300+ PR	5人5月100万行	准确率 99%	Badcase + 看板
核心成果	全球支付稳定	零手写代码	资产 5000 亿	分阶段渐进落地

11.2 直接可借鉴的做法

来源	做法	我们的应用
Stripe	中心化 MCP 管理所有工具	统一工具注册表
OpenAI	人只做架构决策	阶段三：CRUD Agent 自主完成
联易融	审单 Agent 99% 准确率	审单作为业务首试点
Mitchell Hashimoto	"错误只犯一次"哲学	Badcase → Rule 闭环
招行	火眼助手贷后预警提前 42 天	风控 Agent 分级预警

第十二章 · 风险与应对

风险	可能性	影响	应对
团队接受度低	高	推进慢	低风险场景切入；让愿意尝试者先跑通闭环
规则过度膨胀	中	冲突 / 维护贵	分级 P0/P1/P2 + 定期清理（熵管理）
过度依赖 AI	中	人工技能退化	HITL 节点 + 初级开发必参与 Review
合规风险	高	监管处罚	金融场景决策必须可解释、可追溯、可审计
模型供应商依赖	中	成本不可控	工具层抽象，预留模型切换
规则与 CI 不一致	中	纸上规则	P0/P1 规则必须有 Linter 实现 + CI 阻断
老项目改造引入回归	中	生产故障	三段式（读→改→重构）+ 单测先行 + 灰度

附录 A · 术语表

术语	全称 / 含义	在 Harness 中的位置
Harness	驾驭工程，Agent 生产级管控体系	整体框架
AGENTS.md	Agent 项目操作手册，AI 的 README	Agent 层入口
Spec	业务规格，机器可读	Agent 层知识载体
Rules	可执行规则	Agent 层知识载体
Skills	封装好的 Agent 能力单元	Agent 层知识载体
MCP	Model Context Protocol	工具层
RAG	检索增强生成	上下文工程
DAG	有向无环图	编排层
Badcase	Agent 出错的典型场景	评测层
HITL	Human-in-the-Loop，人机协作节点	编排层
Linter	代码规范检查器	架构约束维度
Dreaming	Anthropic 提出的 Agent 自进化	未来演进
Outcomes	Agent 效果量化评分	未来演进
P0/P1/P2	规则分级：红线 / 黄线 / 建议	规则治理

附录 B · 核心参考资料

资料	来源	重要性
Harness Engineering 原始命名	Mitchell Hashimoto，2026.02.05	⭐⭐⭐⭐⭐
Harness 三维框架	Birgitta Böckeler / Martin Fowler 官网	⭐⭐⭐⭐⭐
OpenAI Codex Agent 实验报告	OpenAI，2026.02	⭐⭐⭐⭐
Stripe Minions 体系实践	Stripe 工程博客	⭐⭐⭐⭐
Cursor Rules 官方文档	docs.cursor.com	⭐⭐⭐⭐
Claude Code Memory 官方文档	docs.anthropic.com	⭐⭐⭐⭐
OpenAI Codex AGENTS.md 指南	developers.openai.com	⭐⭐⭐⭐
公司 AI 工程化范式演进研究	公司内部，2026.03	⭐⭐⭐⭐⭐

附录 C · 整合说明

C.1 四份原稿优劣对比

原稿	优点	局限	本整合采用比例
01-Gemini	演讲叙事好；AGENTS.md 业务化模板；6 阶段标注当前点	开头大段 Python 噪音；缺风险/KPI/对标	~15%（话术 + 模板）
02-GPT5.5	极简一页结论；分工建议好	内容单薄；缺示例	~10%（一页结论）
03-Sonnet	五层每层有 YAML 示例 + 交付物清单；术语表与议程详	篇幅长（982 行）不易讲完	~30%（YAML + 议程 + 评测）
04-Opus	"Copilot 阶段"现状定位；P0/P1/P2 规则分级；双平台映射最完整；行业对标	缺 AGENTS.md 红线明细；缺 6 阶段旅程	~35%（骨架 + 规则分级）
【补充】	整合人新增 5 处：边界、双格式、双栈 AGENTS、老项目改造、汇报小技巧	—	~10%

C.2 5 处内容索引

§2.2 Harness 的边界（哪些事 Harness 不做）
§5.2 规则文件双格式策略（.cursor/rules + AGENTS.md）
§5.3 AGENTS.md 双栈模板（Java 8/Vue 2 + Java 17/Vue 3）
§8 老项目改造路径（独立成章）
§13.3 业务架构师汇报小技巧

核心总结：Harness 不是"独立系统"，而是 AI 能力生产级落地的"管控层"。
当务之急是在 Copilot 阶段建好 AGENTS.md + Rules + Linter + Badcase 闭环 这 4 件基础设施，然后分阶段向 Agent 自主、自进化演进。
五层架构是骨架，三维治理是准则，规则分级是抓手，双格式与双栈是落地，老项目三段式是延伸。