一文讲清楚 Harness Engineering

Python编程杰哥

265人浏览 · 2026-03-26 12:02:42

Python编程杰哥 · 2026-03-26 12:02:42 发布

AI 最大的问题，从来不是“不会做”，而是“每次都做得不一样”。

如果你已经开始用 AI 写代码，你大概率经历过这种状态：

有时候，它非常惊艳。

有时候，它又让人抓狂。

你让它写一个功能，它完成了；

你让它改一下，它开始偏离；

你再补充一些说明，它看起来更努力，但结果却更不稳定。

于是，一个几乎所有人都会问的问题出现了：

是不是我的 prompt 写得不够好？

你开始不断优化 prompt：

写得更详细
加更多约束
补更多上下文

但慢慢你会发现一件有点反直觉的事情：

你写得越多，它不一定做得越对。

一、问题不在 Agent，而在“你给它的世界”

我们之所以会陷入“不断优化 prompt”的循环，是因为我们默认了一件事：

AI 像一个工程师，只要你讲清楚，它就能做好，但这其实是一个误解。

人类工程师的工作方式是：

阅读 → 理解 → 设计 → 实现

所以我们习惯写文档、写规范、写说明。

但 Agent 不是这样工作的，它更像是在一个环境中不断：

观察 → 尝试 → 调用工具 → 获得反馈 → 修正

它不会线性读完你的说明。

不会建立完整的全局理解。

更不会长期记住规则。

它只是：

在当前上下文里，做一个“看起来合理的下一步”。

这意味着一件关键的事情：

决定它行为的，不是你写了什么，而是它“身处什么环境”。

这也是 Harness Engineering 想解决的核心问题：

二、与其教它怎么做，不如设计一个让它自然做对的环境。

从 “说什么” 到 “在什么环境里做事”：当你的 AI Agent 开始失控，问题不在模型，而在Harness。

2025 年，我们见证了 AI Agent 的爆发；2026 年，我们发现一个残酷现实：再强的 LLM，没有 Harness 就是"裸奔"。

OpenAI 最近披露，他们用一个 3 人小团队，在 5 个月内生成了一百万行代码，实现了 3.5 个 PR/人/天的吞吐量——关键不是用了 GPT-5，而是他们实践了 Harness Engineering

想象一下这个场景：你让 Agent 重构一个遗留模块，它信心满满地开始工作，中途因为上下文超限"失忆"了，重启后它看着半成品代码一脸懵逼，最后干脆宣布"任务完成"——实际上单元测试全挂。

这不是模型不够聪明，而是 Agent 在裸奔。

Mitchell Hashimoto（HashiCorp 创始人）精准地描述了这个问题：“每次 Agent 犯错，你都应该设计一个系统，让它永远不再犯同样的错误。” 这就是 Harness Engineering 的核心理念。

Agentic 技术的演进

阶段	关注点	核心问题	失效场景
Prompt Engineering	说什么	单次对话的指令质量	多轮后上下文混乱
Context Engineering	知道什么	动态组装上下文	Agent 行为不可控
Harness Engineering	在什么环境里做事	系统级约束与状态管理	长时任务、自主决策

Harness Engineering 关注的是环境设计——给 Agent 一个"操作系统"，让它能持久化状态、验证行为、优雅失败。

Harness Engineering 的四大支柱

如果把 LLM 比作 CPU，Harness 就是操作系统：

上下文治理（Context Curation）：不是塞满上下文，而是智能裁剪和恢复
工具编排（Tool Orchestration）：验证参数、沙箱执行、防幻觉调用
状态持久化（State Persistence）：跨会话记忆，崩溃后可恢复
渐进式披露（Progressive Disclosure）：按需加载技能和权限，最小权限原则

三、实战：构建一个"代码自治优化"的Harness

现在，我们用一个真实可落地的示例，展示如何用 Harness Engineering 让 Agent 自主优化遗留代码。

场景设定

你有一个屎山 Python 项目，想让 Agent 自动完成以下任务：

识别代码坏味道（长函数、魔法数字、缺少类型注解）
生成优化方案并实施重构
运行测试验证不破坏功能
生成代码审查报告

环境相关设计

根据 Harness 的"渐进式披露"原则，我们设计一个完成任务相关的 Skill 目录：

.skills/
└── code-refactor-agent/
├── SKILL.md              # Skill 入口，按需加载到上下文
├── rules/
│   ├── python-style.md   # Python 代码规范
│   └── refactor-patterns.md # 重构模式库
├── tools/
│   ├── analyze_code.py   # 代码分析工具
│   ├── run_tests.sh      # 测试执行包装器
│   └── rollback.py       # 安全回滚工具
└── templates/
└── refactor_plan.md  # 重构计划模板

SKILL.md 核心内容（也可以是agents.md)

这是 Harness 的核心之一。不同于一次性 Prompt（1000页的说明书），它采用渐进式加载指引（一张地图）：

# Code Refactor Agent Skill
## 激活条件
当用户要求"优化代码"、"重构遗留代码"或"改进代码质量"时激活。
## 系统原则
1. **最小破坏原则**：每次只重构一个函数/类，确保测试通过后再继续
2. **状态持久化**：每次会话结束必须更新 `progress.json`，记录已完成和待办
3. **失败熔断**：如果测试连续失败 3 次，立即停止并请求人工干预
## 工具使用规范
- 代码分析：优先使用 `analyze_code.py`，而非让 LLM 直接读文件
- 测试验证：必须通过 `run_tests.sh` 验证，禁止假设"应该没问题"
- 版本控制：每次成功重构后自动提交，提交信息格式：`[Refactor] {变更描述}`
## 渐进式知识库
- 需要 Python 规范时：读取 `rules/python-style.md`
- 需要重构模式时：读取 `rules/refactor-patterns.md`
- 生成分阶段计划时：使用 `templates/refactor_plan.md`
## 安全边界（Guardrails）
- 禁止修改 `requirements.txt` 和配置文件
- 禁止删除已有测试文件
- 遇到 `FIXME` 或 `HACK` 注释时，必须标记为需要人工审查

Harness Engineering 的另一个核心是工具化验证，而非让 LLM"目测"：

关键工具实现：analyze_code.py

class CodeAnalyzer:
def __init__(self, file_path: str):
self.file_path = Path(file_path)
self.issues = []
def analyze(self) -> Dict:
"""执行静态分析，返回结构化报告"""
source = self.file_path.read_text(encoding='utf-8')
tree = ast.parse(source)
# 1. 检查函数长度（圈复杂度代理指标）
for node in ast.walk(tree):
if isinstance(node, ast.FunctionDef):
lines = node.end_lineno - node.lineno if node.end_lineno else 50
if lines > 30:
self.issues.append({
"type": "long_function",
"line": node.lineno,
"name": node.name,
"lines": lines,
"severity": "high",
"suggestion": f"函数 {node.name} 过长({lines}行)，建议拆分为多个小函数"
})
# 2. 检查是否缺少类型注解
if not node.returns and not all(
arg.annotation for arg in node.args.args
):
self.issues.append({
"type": "missing_types",
"line": node.lineno,
"name": node.name,
"severity": "medium",
"suggestion": f"为 {node.name} 添加类型注解"
})
# 3. 检查魔法数字
for node in ast.walk(tree):
if isinstance(node, ast.Num if hasattr(ast, 'Num') else ast.Constant):
if isinstance(node.n if hasattr(node, 'n') else node.value, (int, float)):
if node.n if hasattr(node, 'n') else node.value not in [0, 1, -1]:
self.issues.append({
"type": "magic_number",
"line": node.lineno,
"value": node.n if hasattr(node, 'n') else node.value,
"severity": "low",
"suggestion": "将魔法数字提取为命名常量"
})
return {
"file": str(self.file_path),
"total_issues": len(self.issues),
"issues": sorted(self.issues, key=lambda x: x['severity'], reverse=True),
"suggested_order": self._prioritize_refactoring()
}
def _prioritize_refactoring(self) -> List[str]:
"""生成重构优先级列表（Agent 的执行计划依据）"""
high = [i for i in self.issues if i['severity'] == 'high']
return [f"修复 {i['name']} (第{i['line']}行): {i['suggestion']}"
for i in high[:3]]  # 一次最多 3 个，防止 Agent 贪多

Harness 让 Agent 具备跨会话记忆：

状态管理：`progress.json`

{
"session_id": "refactor-legacy-001",
"target_file": "legacy_module.py",
"completed": [
{
"function": "process_data",
"commit": "a1b2c3d",
"timestamp": "2026-03-20T10:00:00Z",
"tests_passed": true
}
],
"pending": [
"optimize_query_builder",
"extract_constants_from_config"
],
"current_focus": "optimize_query_builder",
"attempt_count": 0,
"last_error": null
}

Agent 的自治工作流

当这个 Skill 被激活后，Agent 会进入Initializer-Executor 模式：

初始化阶段（仅执行一次）：

读取 SKILL.md 和 progress.json
运行 analyze_code.py 生成问题清单
写入 progress.json 制定分阶段计划

执行阶段（循环执行，可跨会话）：

加载 progress.json 恢复状态
选取下一个 pending 任务
实施重构 → 运行 run_tests.sh 验证
如果测试通过：git commit + 更新 progress.json
如果测试失败：查看错误输出 → 重试（最多 3 次）
优雅退出，保存状态供下次会话继续

开发者转型：从"码农"到"AI 系统架构师"

Harness Engineering 正在重新定义开发者的角色：

不再写代码，而是设计"能写代码的系统"。

学AI大模型的正确顺序，千万不要搞错了

🤔2026年AI风口已来！各行各业的AI渗透肉眼可见，超多公司要么转型做AI相关产品，要么高薪挖AI技术人才，机遇直接摆在眼前！

有往AI方向发展，或者本身有后端编程基础的朋友，直接冲AI大模型应用开发转岗超合适！

就算暂时不打算转岗，了解大模型、RAG、Prompt、Agent这些热门概念，能上手做简单项目，也绝对是求职加分王🔋

在这里插入图片描述

📝给大家整理了超全最新的AI大模型应用开发学习清单和资料，手把手帮你快速入门！👇👇

学习路线:

✅大模型基础认知—大模型核心原理、发展历程、主流模型（GPT、文心一言等）特点解析
✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑
✅开发基础能力—Python进阶、API接口调用、大模型开发框架（LangChain等）实操
✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用
✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代
✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经

以上6大模块，看似清晰好上手，实则每个部分都有扎实的核心内容需要吃透！

我把大模型的学习全流程已经整理📚好了！抓住AI时代风口，轻松解锁职业新可能，希望大家都能把握机遇，实现薪资/职业跃迁～