Harness Engineering：当程序员不再写代码

2026/3/23

AIAgent软件工程Harness Engineering

Harness Engineering：当程序员不再写代码

程序员不写一行代码。当 AI 写出不好的代码时，第一要务不是指导它改，而是排查环境中哪一环出了问题，修复环境。

软件工程的三种模式

阶段模式程序员做什么
1Prompt Engineering写提示词，指导 AI 输出
2Agentic Engineering设计工作流，让 Agent 自主执行
3Harness Engineering设计环境约束，让 Agent 在安全边界内自主完成所有编程工作

Harness Engineering 是第三阶段的核心：程序员从”写代码”转变为”设计让 Agent 能正确写代码的环境”。

核心理念

环境设计五要素

┌─────────────────────────────────────────────────────┐
│                   Harness（安全带）                   │
│  ┌───────────────────────────────────────────────┐  │
│  │                                               │  │
│  │    强约束    可观测    可评估    可反馈    可回退   │  │
│  │      │        │        │        │        │    │  │
│  │      ▼        ▼        ▼        ▼        ▼    │  │
│  │   ┌─────────────────────────────────────┐    │  │
│  │   │          Coding Agent               │    │  │
│  │   │      （自主完成所有编程工作）           │    │  │
│  │   └─────────────────────────────────────┘    │  │
│  │                                               │  │
│  └───────────────────────────────────────────────┘  │
│                                                     │
└─────────────────────────────────────────────────────┘
要素含义具体实现
强约束限制 Agent 能做什么沙箱、权限、工具白名单
可观测知道 Agent 做了什么日志、追踪、状态监控
可评估判断做得对不对测试、类型检查、Linter
可反馈把评估结果告诉 Agent错误信息、测试报告
可回退出错能恢复Git、快照、版本控制

原始资料与理论依据

1. Anthropic: Building Effective Agents (2025)

Anthropic 在与数十个团队的合作中发现：

“The most successful implementations weren’t using complex frameworks or specialized libraries. Instead, they were building with simple, composable patterns.”

核心贡献：Agent-Computer Interface (ACI)

就像人类需要 HCI（人机交互界面），Agent 需要 ACI（Agent-Computer Interface）：

# ❌ 糟糕的 ACI：让 Agent 写 diff
# Agent 需要知道修改了多少行才能写 chunk header
edit_file(file="app.py", diff="@@ -10,3 +10,4 @@...")

# ✅ 好的 ACI：让 Agent 重写整个文件
# Agent 只需要关注内容本身
edit_file(file="app.py", content="...")

“We actually spent more time optimizing our tools than the overall prompt.” — Anthropic, 在 SWE-bench 项目中

Evaluator-Optimizer 模式：

┌──────────┐     ┌──────────┐
│ Generator │ ──▶ │ Evaluator │ ──┐
│  (执行者)  │     │  (评估者)  │   │
└──────────┘     └──────────┘   │
     ▲                          │
     └──────────────────────────┘
              反馈循环

这是 Harness Engineering 的理论基础：分离执行和评估。

参考：https://www.anthropic.com/research/building-effective-agents

2. Lilian Weng: LLM Powered Autonomous Agents (2023)

这篇经典文章定义了 Agent 的三大组件：

          ┌─────────────────────────────────────┐
          │            Agent System             │
          │                                     │
┌─────────┴─────────┬───────────────┬───────────┴─────────┐
│                   │               │                     │
│     Planning      │    Memory     │     Tool Use       │
│   (规划与反思)      │   (记忆系统)    │    (工具使用)       │
│                   │               │                     │
│  • 任务分解        │  • 短期记忆     │  • API 调用         │
│  • 自我反思        │  • 长期记忆     │  • 代码执行         │
│  • 计划调整        │  • 向量检索     │  • 外部服务         │
│                   │               │                     │
└───────────────────┴───────────────┴─────────────────────┘

对应到 Harness Engineering：

Agent 组件Harness 要素
Planning + Reflection可反馈 - 评估结果驱动规划调整
Memory可观测 - 日志和状态追踪
Tool Use强约束 - 工具白名单和权限控制

关键洞见：

“Self-reflection is a vital aspect that allows autonomous agents to improve iteratively by refining past action decisions and correcting previous mistakes.”

这对应 可反馈：Agent 需要从环境中获得明确的反馈才能改进。

参考：https://lilianweng.github.io/posts/2023-06-23-agent/

3. Simon Willison: Embracing the Parallel Coding Agent Lifestyle (2025)

Simon Willison 是最早实践并行 Agent 工作流的工程师之一。他的实践直接体现了 Harness Engineering：

环境隔离（强约束 + 可回退）：

“I need to start habitually running my local agents in Docker containers to further limit the blast radius if something goes wrong.”

# 隔离环境实践
/tmp/
  ├── project-a/    # Agent 1 工作目录
  ├── project-b/    # Agent 2 工作目录
  └── project-c/    # Agent 3 工作目录

YOLO Mode（可观测 + 可评估）：

“I frequently have multiple terminal windows open running different coding agents… in YOLO mode (no approvals) for tasks where I’m confident malicious instructions can’t sneak into the context.”

YOLO Mode 的前提是：

  1. 环境已隔离（Docker）
  2. 任务风险可控
  3. 有回退机制（Git）

风险分级：

风险等级环境要求Agent 类型
低（文档、测试）本地目录Claude Code / Codex CLI
中（代码修改）Git worktree本地 Agent + 人工审查
高（生产部署）隔离环境Codex Cloud（异步）

参考：https://simonwillison.net/2025/Oct/5/parallel-coding-agents/

4. Pragmatic Engineer: 工程实践建议 (2025)

Gergely Orosz 总结了使用 Agent 的最佳实践：

“AI agents are non-deterministic and to some extent unreliable; these practices make them a lot more reliable and usable.”

五大实践：

1. Testing:
   - 所有项目必须有单元测试
   - "mandating" engineering practices like having the agent pass all tests before continuing

2. Small, descriptive tasks:
   - 任务粒度要小，说明要清晰
   - 给出具体示例

3. Refactoring:
   - 每隔 3-4 个任务让 Agent 重构
   - extract into a method, move to a new class

4. Review:
   - 跟踪 Agent 做了什么
   - 保持对代码库的认知

5. Do small things personally:
   - 几行的小改动自己动手
   - so I stay aware of the codebase

这些实践的本质：建立可评估、可反馈的环境。

参考：https://blog.pragmaticengineer.com/new-trend-programming-by-kicking-off-parallel-ai-agents/

5. Andrew Ng: Context Hub (2025)

吴恩达指出了一个关键问题：

“Coding agents built using LLMs that learned from old code examples often use incorrect or outdated APIs.”

问题：Agent 的训练数据过时，会使用错误的 API。

解决方案：Context Hub (chub)

# 为 Agent 提供最新的 API 文档
chub install react
chub install next.js

# Agent 现在能访问最新文档
claude-code "Create a Next.js app with App Router"

这对应 Harness 的可评估：环境要提供正确的上下文，Agent 才能做出正确的决策。

更进一步：Agent 反馈

“If an agent obtains a piece of documentation, tries it out, and discovers a bug… feedback reflecting these learnings can be very useful for humans updating the documentation.”

Agent 的反馈可以反过来改进环境 —— 这是 可反馈 的闭环。

参考：https://github.com/andrewyng/context-hub

6. 学术研究：自我反思与改进

ReAct (Yao et al. 2023)

将推理和行动结合：

Thought: 我需要查找用户数据
Action: search("users table schema")
Observation: 找到 users 表，包含 id, name, email
Thought: 现在我可以查询特定用户
Action: query("SELECT * FROM users WHERE id = 1")
...

对应 Harness：

  • Thought → 可观测（记录推理过程）
  • Action → 强约束（限制可用 Action）
  • Observation → 可反馈（环境返回结果）

参考：https://arxiv.org/abs/2210.03629

Reflexion (Shinn & Labash 2023)

Agent 从失败中学习：

# 失败轨迹 + 理想反思 → 改进未来决策
trajectory = [
    ("search", "found nothing"),
    ("query", "syntax error"),
    ("retry", "still failed")
]

reflection = """
之前失败是因为：
1. 搜索关键词不准确
2. SQL 语法错误

下次应该：
1. 使用更具体的搜索词
2. 先检查 SQL 语法
"""

对应 Harness：可反馈 需要结构化的反思机制。

参考：https://arxiv.org/abs/2303.11366

Harness Engineering 实践框架

环境设计清单

强约束:
  - [ ] 沙箱环境（Docker / VM / 隔离目录）
  - [ ] 文件系统权限控制
  - [ ] 网络访问白名单
  - [ ] 工具调用白名单
  - [ ] 资源使用限制（CPU/内存/时间）

可观测:
  - [ ] 所有操作记录日志
  - [ ] 文件变更追踪
  - [ ] 工具调用链追踪
  - [ ] 状态快照

可评估:
  - [ ] 单元测试必须通过
  - [ ] 类型检查（TypeScript/mypy）
  - [ ] Linter 检查
  - [ ] 构建必须成功
  - [ ] 自定义验证规则

可反馈:
  - [ ] 测试失败信息清晰
  - [ ] 错误信息结构化
  - [ ] 评估结果可被 Agent 理解
  - [ ] 支持迭代修复

可回退:
  - [ ] Git 版本控制
  - [ ] 变更前自动 commit
  - [ ] 支持一键回滚
  - [ ] 多版本并行（git worktree）

问题排查流程

当 Agent 写出不好的代码时：

┌─────────────────────────────────────────────────────────────┐
│                      Agent 出错了                            │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  ❌ 错误反应：指导 Agent 修改代码                              │
│  ✅ 正确反应：排查环境哪一环出了问题                            │
└─────────────────────────────────────────────────────────────┘
                              │
            ┌─────────────────┼─────────────────┐
            ▼                 ▼                 ▼
      ┌──────────┐      ┌──────────┐      ┌──────────┐
      │ 强约束?   │      │ 可观测?   │      │ 可评估?   │
      │          │      │          │      │          │
      │ 权限太宽? │      │ 日志完整? │      │ 测试覆盖? │
      │ 工具不当? │      │ 追踪清晰? │      │ 验证足够? │
      └──────────┘      └──────────┘      └──────────┘
            │                 │                 │
            └─────────────────┼─────────────────┘
                              ▼
                    ┌──────────────────┐
                    │  修复环境，重试    │
                    └──────────────────┘

示例：

# Agent 写了错误的代码
def get_user(id):
    return db.query(f"SELECT * FROM users WHERE id = {id}")  # SQL 注入！

# ❌ 错误反应：告诉 Agent 用参数化查询
# ✅ 正确反应：检查环境
#   - 强约束：是否禁止了字符串拼接 SQL？
#   - 可评估：是否有 SQL 注入检测？
#   - 可反馈：错误信息是否足够清晰？

# 修复环境
SQL_INJECTION_CHECK = True  # 启用 SQL 注入检测
PARAMETERIZED_QUERY_ONLY = True  # 强制参数化查询

工具与实现

推荐工具栈

类别工具用途
AgentClaude Code, Codex CLI, Cursor执行编程任务
隔离Docker, git worktree强约束 + 可回退
测试pytest, Jest, vitest可评估
类型TypeScript, mypy可评估
LinterESLint, Ruff可评估
追踪LangSmith, OpenTelemetry可观测
文档Context Hub (chub)上下文管理

示例配置

# harness.yaml - Harness 配置文件
environment:
  sandbox: docker
  base_image: node:20
  workdir: /app

constraints:
  network:
    allow: ["npm.registry", "github.com"]
  filesystem:
    readonly: ["node_modules"]
    writeonly: ["src", "tests"]

evaluation:
  - name: typecheck
    command: npx tsc --noEmit
    required: true
  
  - name: lint
    command: npx eslint src/
    required: true
  
  - name: test
    command: npx vitest run
    required: true
    timeout: 60s

feedback:
  format: json
  include:
    - test_results
    - lint_errors
    - type_errors

rollback:
  vcs: git
  auto_commit: true
  commit_message: "agent: ${task_name}"

总结

从 Prompt Engineering 到 Harness Engineering

Prompt Engineering
    │
    │  关注：怎么说 AI 才能听懂
    │  方法：优化提示词
    ▼
Agentic Engineering
    │
    │  关注：让 AI 自主完成任务
    │  方法：设计工作流、工具链
    ▼
Harness Engineering
    │
    │  关注：让 AI 在安全边界内自主工作
    │  方法：设计强约束、可观测、可评估、可反馈、可回退的环境
    ▼

核心原则

  1. 程序员不写代码 —— 设计环境让 Agent 写
  2. Agent 出错先查环境 —— 不是指导修改，而是修复约束
  3. 环境设计五要素 —— 强约束、可观测、可评估、可反馈、可回退
  4. 简单优于复杂 —— 简单的环境更容易调试

参考资源

“The more complex your agent architecture, the harder it is to debug and the more likely it is to fail in unexpected ways.”

— Anthropic, Building Effective Agents

Harness Engineering 的本质：用简单、可调试的环境约束，替代复杂的 Agent 架构。

📝 文章反馈