Harness Engineering 配方

我在 Next.js 全栈仓库里实践 agent 自动驾驶的一套配方，包括 issue 获取、方案分析、红绿灯 TDD、测试、浏览器验证、Git workflow、文档系统和环境变量约束。

Harness Engineering 配方

这篇文档是我当前在 Next.js 全栈仓库里实践 Harness Engineering 的整理版。

这个说法我重新认真看，是因为 OpenAI 那篇 Harness Engineering。我最认同的一点很简单：如果你希望 agent 真正参与软件开发，关键不只在模型，而在你有没有把仓库、工具、验证链路和反馈回路接起来。

我现在主要是在 Next.js 全栈应用里做这件事。对我来说，harness 不是一个脚本，也不是某个 CLI 的开关。它更像一套工作系统，目标是让 agent 真能接住真实工程任务。

如果换成我自己的定义，harness engineering 指的是在代码仓库或者项目仓库的开发任务里，agent 能调用的一组工具、能约束代码行为的一组规则，以及 agent 能遵循的一组上下文说明。这样做的目的，是让 agent 能实时评估自己生成的代码质量、检验功能是否完整，并把结果尽量拉回到开发者团队真正期望的方向上。

这套配方要解决什么

如果只是让 agent “读代码然后改代码”，它通常只能停在一次性助手的层级：

回答问题
生成补丁
补一点测试

这些当然有用，但还不够。

我更在意的是：在一个真实的 Next.js 全栈仓库里，agent 拿到任务后，能不能沿着一条明确的轨道持续往前推。

至少要把下面这些环节接起来：

获取任务来源，比如 GitHub issue 或待办任务
先分析方案，再进入实现
尽可能按红绿灯 TDD 推进
跑单测、集成测试、端到端测试，必要时真的打开浏览器
按可追踪的 Git workflow 提交、合并、回滚
把关键背景、约束和长期知识沉淀进文档系统

这些环节一旦接起来，agent 才会从“偶尔帮忙”变成“能持续交付”。

我现在的自动驾驶链路

从 issue 开始

我更喜欢让 agent 从明确的问题入口开始工作，比如：

GitHub issue
仓库里的任务描述
PR review comment

这样做的好处很直接：

任务边界更清楚
后面的提交、PR 和文档更新都有明确回指

先分析，再实现

我会要求 agent 在动手前先拆问题：

影响了哪些模块
哪些是关键路径
哪些可以并行
风险点在哪里
需要什么验证手段

很多失败并不是写不出代码，而是开始得太快，改得太散，最后测试和提交都很难收。

红绿灯 TDD

在适合写测试的模块里，我还是偏向红绿灯 TDD：

先写一个失败的测试
再补最小实现让它变绿
最后做重构和命名收敛

我不会把 TDD 当成教条，但在 harness 里，它能给 agent 一个稳定的推进节奏，也更容易定位问题。

三层验证

在 Next.js 仓库里，我通常会给 harness 接上三层验证：

单测：验证纯逻辑、工具函数、状态变换
集成测试：验证模块之间拼起来是否成立
端到端测试：验证真实页面、路由、表单、接口和浏览器交互

端到端测试尤其重要。很多问题只有真的打开浏览器才会暴露，比如 hydration、表单提交流断裂、状态不同步、按钮不可点或者样式遮挡。

在操作浏览器这件事上，我自己的配方也比较明确：

优先用 openclaw browser start 开浏览器，这样能复用浏览器里已经记住的登录凭证
页面读取和后续交互优先交给 agent-browser
如果场景比较简单，直接用 agent-browser 打开浏览器也可以

Git workflow

我把 Git workflow 直接算进 harness 里，而不是留到开发结束再补。

最基本的要求包括：

在明确分支上工作
提交信息有稳定风格
合并前确认工作区干净
必要时通过 PR 合流，而不是把所有实验直接扔到主分支

文档系统

文档系统负责承接长期知识。

很多约束不在代码里，但会反复影响后面的开发，比如：

仓库结构约定
环境变量使用规则
重点回归页面
某个模块的历史坑点
文档、文章、组件的维护惯例

如果这些信息只留在聊天记录里，agent 每次都得重新摸路。

我常放进仓库里的工具和配置

`superpowers`

obra/superpowers

我主要用在两个地方：

新建项目时，尽快把一套更适合 agent 协作的开发习惯带进来
实现过程中，把红绿灯 TDD、调试、验证和计划拉回到更稳定的轨道上

`biome` 或 `ultracite`

这类工具我会当成仓库里的低摩擦规范器。

格式化、基础 lint 和风格收敛如果没有统一标准，很快就会变成大量低价值往返。biome 和 ultracite 的意义，就是尽量把这类问题往前收掉。

project docs system

multicul-silver-wolf/agent-docs-system-skill

这块我现在越来越看重。只靠 README 和零散注释，撑不起长期的 agent 协作。

我更偏向把文档系统拆成几层：

面向 agent 的入口说明
项目长期记忆
模块级、领域级、流程级文档

Vercel 环境变量约束

如果项目跑在 Vercel 上，我会尽量把环境变量管理收口到 Vercel 这一套里。

我的偏好很明确：

用 vercel env run 跑命令
用 Vercel 作为环境变量的唯一事实来源
避免本地各处散落、互相漂移的 .env.* 变体

这对 harness 很关键。agent 一旦在错误的环境变量集合里工作，后面的测试、调试和部署结论都会开始跑偏。

给新 agent 的启动 prompt

如果我要把这套东西搬到一个新的 Next.js 仓库里，我通常不会从头解释一遍，而是直接把下面这段 prompt 交给一个新的 agent。

You are integrating a Harness Engineering workflow into a new Next.js full-stack repository.

Goal:
- Turn this repository into an agent-friendly engineering system, not just a normal app repo.
- The workflow should support issue intake, planning, red-green-refactor TDD, unit/integration/e2e testing, browser-based validation, git workflow discipline, and a layered documentation system.

Project assumptions:
- Stack: Next.js full-stack app
- Package manager: prefer pnpm unless the repo already standardizes on something else
- Validation should include browser-based checks when the task touches UI
- For browser work, prefer starting the browser with `openclaw browser start` so existing login state can be reused; use `agent-browser` to read and interact with pages, and use it to open the browser directly when that is sufficient
- Environment variables should use Vercel as the single source of truth

What to set up:
1. Add or align repository guidance files for agent collaboration.
2. Add a layered docs / memory system for long-lived project knowledge.
3. Integrate a practical red-green-refactor workflow suitable for agents.
4. Add or align formatting and linting with Biome or Ultracite, whichever fits the repo better.
5. Ensure the repo has a clear testing strategy:
   - unit tests
   - integration tests
   - end-to-end tests
   - browser-opening validation when needed
6. Make Git workflow explicit:
   - branch strategy
   - commit message conventions
   - clean working tree requirement before final handoff
7. Make Vercel environment handling explicit:
   - prefer `vercel env run <command>`
   - treat Vercel-managed env vars as the single source of truth
8. If useful, integrate skill-driven workflows inspired by superpowers and a project docs system.

Execution rules:
- Do not just describe the setup; implement it in the repo.
- Inspect existing structure first and preserve established conventions where reasonable.
- Prefer small, reviewable commits.
- Run verification after meaningful changes.
- Update documentation whenever you introduce a durable workflow rule.

Deliverables:
- The repository changes
- A short explanation of the harness design
- Validation results
- Any remaining gaps or recommended follow-up work

这套配方里最重要的几件事

如果把它压成一句话，大概就是：

我想做的，不是让 agent 偶尔帮我写代码，而是把 Next.js 仓库改造成一个 agent 能持续交付的工程环境。

这套配方里最关键的环节是：

任务输入
方案分析
TDD 推进
自动验证
浏览器验证
Git 交付
文档沉淀

这份 docs 会继续更新

我先把现在能跑通、也确实在用的这一版记下来。

后面只要我的实践变了，这篇 docs 就会跟着改：

增加新的验证环路
替换不再合适的工具
用更好的实践重写旧内容

Harness Engineering 配方