我怎么给 Next.js 全栈仓库接上 Agent 自动驾驶

这段时间，我一直在用一个词概括自己在仓库里折腾的那套 agent 工作流：Harness Engineering。

我重新认真看这个概念，是因为 OpenAI 那篇 Harness Engineering。文章里最打动我的地方很直接：如果你真想让 agent 参与软件开发，重点不只在模型强不强，还在你有没有把仓库、工具、验证链路和反馈回路接起来。

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

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

这篇先把我现在这套配方记下来。后面我肯定还会改，因为很多细节还在变。等我踩到新的坑，或者找到更顺手的做法，我会直接回头改写。

我理解的 Harness Engineering，到底在解决什么

如果只是让 agent “读代码然后改代码”，它很容易停在一次性助手这个层级：

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

这些当然有用，但离“自动驾驶”还差得远。

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

至少得把下面这些事做稳：

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

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

我在 Next.js 全栈应用里落地的自动驾驶链路

我现在这套做法，本质上就是把任务输入、实现、验证和交付接成一条线。

1. 从 issue 开始，而不是从“写点代码”开始

我更喜欢让 agent 从明确的问题入口开始干活，比如 GitHub issue、仓库里的任务描述，或者 PR review comment。

这样做的好处很实际：

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

任务入口一旦模糊，agent 很容易变成那种“看起来一直在忙，但没有把事情真正做完”的状态。

2. 先做方案分析，再进入实现

我会要求 agent 先把问题拆开：

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

这一步一点都不炫，但很值钱。很多时候不是写不出代码，而是上来改得太快、太散，最后测试难补，提交也难收。

3. 尽量按红绿灯 TDD 推进

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

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

我不会把 TDD 当成宗教，但放进 harness 里，它真的很有用。它给 agent 一个清楚的推进节奏，也更容易定位问题。跟“先改一堆，再统一跑看看”比起来，这种方式更适合拆任务，也更适合多人或多 agent 协作。

4. 单测、集成测试和端到端测试都要进环

我不想要“代码看起来应该没问题”。我想要的是验证链路真的覆盖到用户行为。

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

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

端到端这一层尤其重要。很多问题不打开浏览器，你根本碰不到，比如：

• hydration 问题
• 表单提交流断裂
• 客户端状态和服务端状态不一致
• 样式遮挡、交互失焦、按钮不可点

在操作浏览器这件事上，我自己的偏好也很固定：

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

如果 harness 不把浏览器纳入验证环，我很难相信它真的覆盖了前端体验。

5. Git workflow 不是收尾动作，而是 harness 的一部分

我会把 Git workflow 直接算进 harness 里，而不是留到开发结束再顺手处理。

最基本的要求包括：

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

这会直接影响 agent 的可靠性。Git 流程一乱，后面的追踪、回滚、审查和自动化很容易一起变形。

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

我很看重文档系统，尤其是在 agent 长期参与维护时。

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

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

这些信息如果只留在聊天记录里，agent 每次都像新同事进组一样重新摸路。文档系统的作用，就是把这些约束变成可以反复调用的工程记忆。

我为了让 harness 更稳，常放进 Next.js 仓库里的工具和配置

工具当然不是目的，但工具选得对，摩擦会小很多。

superpowers

项目地址：obra/superpowers

这套东西我主要用在两个地方：

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

我喜欢它，不是因为“多了一个 skill 包”，而是因为它会逼你把很多本来容易被跳过的工程动作走完整。

biome 或 ultracite

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

在 agent 驱动开发里，格式化、基础 lint、风格收敛这些事如果没有统一标准，最后就会变成大量低价值往返。biome 和 ultracite 的意义，就是尽量把这类问题往前收掉。

project docs system

项目地址：multicul-silver-wolf/agent-docs-system-skill

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

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

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

这样做之后，agent 才能慢慢积累“这个仓库到底有哪些特殊规则”，而不是每次都从零重新推理。

Vercel 集成和环境变量约束

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

我的偏好很明确：

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

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

一份我会给新 agent 的启动 prompt

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

它当然不是万能模板，但拿来起一套同风格的 harness，基本够用了。后面再让 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 交付
• 文档沉淀

少掉其中一环，agent 也不是完全不能用。但一旦这些环节都接起来，稳定性会明显好很多。

延伸阅读

• OpenAI: Harness Engineering
• Awesome list: walkinglabs/awesome-harness-engineering
• Superpowers: obra/superpowers
• Project docs system: multicul-silver-wolf/agent-docs-system-skill

这篇我会一直改下去

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

但这东西不会停在这里。后面只要我的实践变了，这篇就会跟着改。

大概会在这些地方持续变：

• 当我的 harness 增加了新的验证环路，我会补进来
• 当某个工具不再适合，我会把它换掉
• 当更好的实践出现，我会直接改写这篇文章

只要我还在 Next.js 全栈应用里继续折腾 agent 自动驾驶，这篇文章和相关目录就不会是定稿。