1. 为什么 Agent 总在同一个坑里反复翻车如果你带过 AI Agent 做真实项目大概率见过这个循环Agent 接到任务思考几秒开始写代码一口气生成 200 行。你让它跑一下 lint直接失败——类型定义文件 import 了配置包违反了架构分层约束。Agent 不知道这条规则因为你也没告诉它。于是它开始修移动代码、调整依赖、重新组织。再跑 lint又冒出一个新问题。循环三次之后上下文窗口被错误日志和 diff 塞满Agent 开始忘记最初的任务目标。你让它加个用户认证功能它却在那儿纠结一个完全不相关的 import 路径问题。这不是 Agent 不够聪明是 Agent 看不见。同一个项目昨天的 AI 还记得你们的架构约定今天开个新会话又全忘了。每次协作都要重新解释背景、分层规则、命名规范。AI 生成的代码能跑但完全不符合团队规范code review 时才发现一堆问题。让它修 bug结果引入了新 bug——没有自动验证全靠人肉检查。换成一个新入职的工程师他可能也不熟悉代码库但至少会问一句这个文件应该放在哪个目录这样 import 可以吗他在行动前寻求验证。AI Agent 不会它直接干。问题出在哪Prompt 写得再好也没法穷尽代码库的所有隐式规则。上下文窗口再大也装不下整个仓库的架构决策。教得更好这条路有天花板——写更详细的 system prompt提供更多示例规则会随代码演进变化你永远追不上。规范文档放在钉钉或 Notion 上AI 读不到依赖 AI 的常识不同模型表现差异大不可靠。Harness Engineering 的思路不一样与其教 Agent 怎么做不如让它自己验证做得对不对。靠代码、linter、测试来保证正确性而不是靠 LLM 的直觉。这些机械化检查不会出错不会遗忘也不会被上下文压缩掉。就像 CI/CD 对人类开发者的作用——自动拦截问题。只不过这次拦截的时机更早不是合并前而是写代码前。仓库是 Agent 的操作系统。CPU 很强大但没有操作系统它就是一块高速却无方向的芯片——不知道硬盘在哪、网络协议是什么、哪些内存地址可以写。LLM 也一样。它推理能力很强但它不知道你的internal/types/不能 importinternal/config/不知道新文件该放哪个目录。Harness 就是给它装的操作系统。这个类比背后有几条关键原则。首先仓库是唯一的事实来源。讨论群里的结论、会议上的口头约定、架构师脑子里的蓝图这些对 Agent 来说都不存在。不在仓库里Agent 就看不见看不见就会违反。所以第一步是把一切编码到仓库中架构决策、层级约束、命名规范。不是写在 Wiki 里不是发在群里而是作为版本化的文件提交到 Git。这样知识跟着代码一起走新人 clone 仓库就能拿到全部上下文Agent 打开项目就能读到一切。但编码到仓库不意味着把所有东西塞进一个文件。很多团队的第一反应是写一份巨大的 AGENTS.md500 行什么都有。问题是当一切都重要时什么都不重要。500 行的指令文件挤占了 Agent 宝贵的上下文窗口留给实际任务的空间反而少了。AGENTS.md 应该是地图不是手册——控制在 100 行左右只做索引和指路详细内容放在docs/目录里按需加载。要改 auth 模块先读 AGENTS.md 找到路再读docs/design-docs/auth.md拿细节。用不上的文档根本不加载。保持短小精悍还有一个好处不容易腐烂巨大的指令文件会迅速过时。然后是约束的粒度。Harness 不规定你必须用这个设计模式或函数必须这样写它只管架构边界。大多数代码库的包和模块之间存在自然的依赖方向类型定义被所有人 import、业务逻辑依赖类型但不依赖 HTTP 层、HTTP handler 依赖业务逻辑。Harness 把这种自然方向编码为层级编号——Layer 0 是类型定义不 import 任何内部包Layer 1-2 是工具函数和配置只依赖更低层Layer 3 是业务逻辑Layer 4 是 HTTP handler 和 CLI 命令。规则就一条高层可以 import 低层反过来不行。在这个边界之内怎么实现随便。跟管理大型平台团队一样中心化约束本地自治。最后一条原则关乎人的角色。以前是人写代码、AI 辅助补全现在反过来了——人设计系统架构、约束、验证规则Agent 在系统内执行。人的价值从写出正确的代码变成了设计出让 Agent 能可靠产出正确代码的环境。你不再需要自己拧每一颗螺丝但你得确保流水线是对的。2. 用 AGENTS.md 做约束入口从零搭出可执行的验证管道说了这么多理念具体怎么落地Harness 靠两个引擎协作harness-creator 负责分析代码库、生成基础设施文档、lint 脚本、目录结构harness-executor 在这套基础设施中执行开发任务。它们的关系很简单——executor 启动时先看 AGENTS.md 在不在不在就自动喊 creator 来搭搭完再继续干活。所以任何项目都能直接用 executor 起步。creator 首次运行时会审计项目现状按文档覆盖率、lint 规则覆盖率等维度打出 0-100 分。0-20 分基本是裸奔状态从零搭建全套21-70 分说明有基础但有缺口针对性补充71 分以上已经比较健康微调就行。executor 的工作流是检测环境 → 加载上下文 → 制定计划 → 人类批准 → 执行 → 验证 → 完成。注意人类批准这一步不是走过场——对于非简单任务executor 会创建一个执行计划文件包含任务目标、影响范围、分阶段步骤、验证方式和回退策略。你扫一眼就知道 Agent 打算怎么干觉得不对可以直接改方向。一个装备了 Harness 的项目大致长这样my-project/ ├── AGENTS.md ← 导航地图~100行 ├── docs/ │ ├── ARCHITECTURE.md ← 架构、层级、依赖规则 │ ├── DEVELOPMENT.md ← 构建/测试/lint 命令 │ ├── PRODUCT_SENSE.md ← 业务上下文 │ ├── design-docs/ ← 组件设计文档 │ └── exec-plans/ ← 执行计划active / completed ├── scripts/ │ ├── lint-deps.* ← 层级依赖检查 │ ├── lint-quality.* ← 代码质量规则 │ ├── verify/ ← 端到端功能验证 │ └── validate.py ← 统一验证管道 ├── harness/ │ ├── tasks/ ← 任务状态和检查点 │ ├── trace/ ← 执行轨迹和失败记录 │ └── memory/ ← 经验教训存储 └── [业务代码...]每一部分在执行过程中都有用文档提供知识脚本提供验证harness/提供状态管理和学习能力。其中scripts/下面的机械执法层是核心——它把团队约定从希望被遵守变成不遵守就报错。在动手之前先问能不能做。Harness 里的验证分几类。最核心的是依赖方向检查lint-deps——core/不能 importui/api/和cli/不能互相引用。对应的就是前面说的层级规则靠扫描源码里的 import 语句来检查。其次是质量规则检查lint-quality强制一些编码规范单文件不超过 500 行禁止console.log/print()要求用结构化日志禁止硬编码品牌字符串。这些规则说起来都是常识但 Agent 不提醒就不会遵守。lint 脚本有 Go、TypeScript、Python 三个版本creator 会根据你的项目类型自动生成。但重点不是事后检查而是事前预防。Agent 通常的工作流是写代码、跑测试、发现错误、修复、再跑测试。当一个层级违反在 50 行代码写完后才被 linter 抓到修复代价很大——撤销改动、重新设计差不多要消耗 10 次 tool call。而如果在写代码前先问一句这样做合法吗两次交互就够了python3 scripts/verify_action.py --action create file internal/types/user.go # ✓ VALID: internal/types/ is Layer 0, user.go follows naming convention python3 scripts/verify_action.py --action import internal/core from internal/handler # ✗ INVALID: internal/handler (L4) cannot import internal/core (L3) # Fix: handler should depend on core through interfaces不是每个操作都需要预验证。改个函数体不需要加个测试文件不需要。但只要涉及在新位置创建文件或添加跨包 import就该先验证。层级违反是 Agent 翻车的头号原因。这里有一个容易被忽视但影响很大的细节linter 的错误信息质量直接决定了 Agent 能不能自愈。一条Forbidden import in core/types/user.go看完不知道怎么办但如果改成core/types/user.go imports core/config (Layer 0 → Layer 2). Layer 0 packages must have NO internal dependencies. Fix: Move config-dependent logic to a higher layer, or pass the config value as a parameter.——什么规则违反了、为什么是问题、怎么修全在里面。一条好的报错本身就是一次教学。Harness 不鼓励 Agent 直接跑go build或go test而是提供统一验证入口validate.py因为验证通过在每个项目里含义不同。验证顺序有讲究先 build编译都不过就别往下了再 lint-arch架构约束然后 test功能正确性最后还有一步容易被漏掉——verify。build → lint-arch → test → verify │ │ │ │ │ │ │ └─ 端到端功能验证 │ │ └─ 单元/集成测试 │ └─ 架构和质量合规 └─ 代码能否编译build lint test 能覆盖大部分问题但有一类问题它们抓不到功能层面的正确性。测试通过了不代表功能是对的——测试本身可能覆盖不全或者 Agent 写的测试恰好绕过了关键路径。verify 步骤是项目级别的端到端功能验证——不是函数返回值对不对而是用户执行这个操作最终结果对不对。比如一个 CLI 工具verify 会实际运行几个典型命令检查输出一个 Web API会发几个真实请求验证响应。很多项目一开始并不具备端到端 verify 的能力。这时候 Harness 会引导你创建 verify skill——一组针对项目的可复用验证脚本。思路是先识别核心用户路径比如创建用户→登录→查看资料然后把每条路径编码成可执行的验证脚本。creator 分析项目时会自动生成骨架放在scripts/verify/下面你填充具体的断言逻辑就行。这让验证闭环从代码能跑提升到了功能正确。验证挂了怎么办executor 会自动进入修复循环——分析错误、改代码、重新跑验证一般 1-3 轮就收敛。如果同一个错误转了 3 圈还没过就别让 Agent 继续挣扎了停下来交给人。不是它一定修不好而是再转下去上下文窗口就要爆了。几条踩过坑之后的经验故意引入违规来测试 lint加一个跨层 import 确认能被检测到如果 lint 没报错说明护栏是纸糊的永远不要禁用 lint 规则来解决问题Agent 有时候会想绕过规则比如注释掉 lint 配置应该改代码而不是改规则测试不需要每次跑全量executor 支持只跑受影响的包速度快很多。3. 可复制的 AGENTS.md 与 lint 配置片段理论讲完了。好在 Harness 不是全有或全无的——哪怕不搭完整的六层基础设施一个 AGENTS.md 就能让 AI 协作体验好一截。这套方法适用于任何能跑 shell 命令的 coding agentQodercli、Claude Code、Codex 等都行。多人协作、有明确分层的中大型项目收益最明显个人项目或原型阶段一个 AGENTS.md 加个简单的 lint 脚本就够了。新项目最简单——告诉 creator 你要做什么它会问几个基本问题然后直接生成全套基础设施。老项目也不难creator 会扫描代码库、分析 import 关系、推断层级映射生成反映代码现状的文档。随着项目演进定期跑一次 Improve 模式做体检creator 输出审计报告指出哪些包没被 linter 覆盖、哪些文档没跟上代码变化然后 executor 来实施修复。不管哪种情况最小起步都一样——在项目根目录创建 AGENTS.md# [项目名] Agent Guide ## 快速链接 - [架构总览](docs/ARCHITECTURE.md) — 分层规则、数据流 - [开发指南](docs/DEVELOPMENT.md) — 构建、测试、lint 命令 ## 构建命令 make build # 构建项目 make test # 运行测试 make lint-arch # 运行架构 lint ## 分层规则 Layer 0: types/ → 纯类型定义无内部依赖 Layer 1: utils/ → 工具函数仅依赖 Layer 0 Layer 2: config/ → 配置依赖 Layer 0-1 Layer 3: core/services/ → 业务逻辑依赖 Layer 0-2 Layer 4: api/ cli/ ui/ → 接口层依赖 Layer 0-3彼此不互相引用 ## 质量标准 - 结构化日志禁止 console.log / print() - 单文件不超过 500 行 - PascalCase类型、camelCase函数、kebab-case文件名为什么叫 AGENTS.md这个文件名是业界标准Agent 打开项目时会自动查找并读取它作为了解项目的起点。类似于 README.md 是给人看的AGENTS.md 是给 Agent 看的。接下来是 lint 规则清单。以 TypeScript 项目为例scripts/lint-deps.ts的核心逻辑是扫描 import 语句并对照层级映射表// scripts/lint-deps.ts import { readFileSync, readdirSync, statSync } from fs; import { join, relative } from path; const LAYER_MAP: Recordstring, number { src/types: 0, src/utils: 1, src/config: 2, src/core: 3, src/api: 4, src/cli: 4, src/ui: 4, }; function getLayer(filePath: string): number | null { for (const [prefix, layer] of Object.entries(LAYER_MAP)) { if (filePath.startsWith(prefix)) return layer; } return null; } function checkFile(filePath: string): string[] { const errors: string[] []; const sourceLayer getLayer(filePath); if (sourceLayer null) return errors; const content readFileSync(filePath, utf-8); const importRegex /from\s[](.?)[]/g; let match; while ((match importRegex.exec(content)) ! null) { const importPath match[1]; if (!importPath.startsWith(.) !importPath.startsWith(/)) continue; const resolved importPath.replace(/, src/); const targetLayer getLayer(resolved); if (targetLayer null) continue; if (targetLayer sourceLayer) { errors.push( ${filePath} imports ${resolved} (Layer ${sourceLayer} → Layer ${targetLayer}). Layer ${sourceLayer} packages must NOT depend on Layer ${targetLayer}. Fix: Move the dependent logic to a higher layer, or pass the value as a parameter. ); } } return errors; }对应的scripts/lint-quality.ts检查质量规则// scripts/lint-quality.ts const RULES [ { name: max-file-lines, check: (content: string) content.split(\n).length 500, message: File exceeds 500 lines. Split into smaller modules., }, { name: no-console-log, check: (content: string) !/console\.(log|warn|error)\(/.test(content), message: Use structured logger instead of console.log., }, { name: no-hardcoded-brand, check: (content: string) !/[]MyBrand[]/.test(content), message: Brand strings must come from config, not hardcoded., }, ];统一验证入口scripts/validate.py把各步骤串起来#!/usr/bin/env python3 Unified validation pipeline: build → lint-arch → test → verify import subprocess import sys STEPS [ (build, [make, build]), (lint-arch, [make, lint-arch]), (test, [make, test]), (verify, [python3, scripts/verify/run_all.py]), ] def run_pipeline(): for name, cmd in STEPS: print(f\n{*50}) print(f[{name}] Running: { .join(cmd)}) print(f{*50}) result subprocess.run(cmd, capture_outputTrue, textTrue) if result.returncode ! 0: print(f[{name}] FAILED) print(result.stdout) print(result.stderr) sys.exit(1) print(f[{name}] PASSED) print(\n✓ All validation steps passed.) if __name__ __main__: run_pipeline()如果你用的是 Claude Code可以在项目根目录的.claude/settings.json里配置验证钩子让每次文件修改后自动触发 lint{ hooks: { PostToolUse: [ { matcher: Edit|Write, command: python3 scripts/validate.py --quick, description: Run quick validation after file changes } ] } }--quick模式只跑 lint-arch 和受影响的测试不跑全量 build响应更快。完整验证留给提交前或 CI 阶段。如果你用的是 Cline可以在.cline/settings.json里配置 MCP 工具链把验证脚本暴露成 MCP tool{ mcpServers: { harness-verify: { command: python3, args: [scripts/mcp_server.py], env: { PROJECT_ROOT: . } } } }这样 Agent 在写代码前就能调用verify_action工具做预检查而不是等写完再跑 lint。对于 Codex 用户~/.codex/auth.json里配置好 API 端点后可以在项目根目录的codex.toml里指定验证命令[project] name my-project validation_command python3 scripts/validate.py pre_action_command python3 scripts/verify_action.py --action [model] provider openai model_id gpt-5.3-codex base_url https://taotoken.net/api这里的关键是三件套必须写全Base URL、API Key、Model ID。缺任何一个都会导致 401 或连接失败。API Key 建议通过环境变量注入不要硬编码在配置文件里。4. 验证请求与成功结果一次从失败到通过的完整动作配置写好了接下来跑一次完整的验证流程看看从失败到通过的全过程。假设 Agent 接到任务在internal/handler/user.go里添加一个用户查询接口。它先读 AGENTS.md找到架构文档然后列出执行计划。你批准后它开始写代码。第一版代码写完了跑python3 scripts/validate.py [build] Running: make build [build] PASSED [lint-arch] Running: make lint-arch [lint-arch] FAILED src/handler/user.go imports src/core/user (Layer 4 → Layer 3). Layer 4 packages must NOT depend on Layer 3 directly. Fix: handler should depend on core through interfaces defined in Layer 0.Agent 看到这条报错知道问题在哪了。它没有直接改代码而是先跑预验证python3 scripts/verify_action.py --action import src/core/user from src/handler # ✗ INVALID: src/handler (L4) cannot import src/core/user (L3) # Fix: Define an interface in src/types/ and inject the implementation.根据提示Agent 在src/types/里定义了一个UserService接口然后让 handler 依赖这个接口而不是具体实现。改完再跑验证 [build] Running: make build [build] PASSED [lint-arch] Running: make lint-arch [lint-arch] PASSED [test] Running: make test [test] PASSED (12 tests, 0 failures) [verify] Running: python3 scripts/verify/run_all.py [verify] Running: verify_user_query.py → GET /api/users/123 ... 200 OK → Response contains id: 123, name: Alice → PASSED [verify] All 1 verification scripts passed. ✓ All validation steps passed.整个过程 Agent 只用了 4 次 tool call 就收敛了。如果没有预验证它可能会先写完 50 行代码跑 lint 失败再撤销重写消耗 10 次以上的 tool call。验证通过后另一个模型的子代理做交叉 reviewreview_result Agent( descriptionReview: user query handler, modelcodex, promptf Review the following changes for: 1. Logic correctness and edge cases 2. Consistency with architecture (see ARCHITECTURE.md) 3. Naming clarity and code readability 4. Performance implications Changes: {coding_result.diff} Task context: {task_description} )Review 子代理输出通过或需修改。如果需修改回到编码子代理修复再过一轮 review。Review 中发现的问题会被记录到harness/trace/里。如果某类问题反复出现说明应该把它编码成新的 lint 规则——把 review 中的软知识逐渐转化成验证管道中的硬规则。中等以上的任务还会设检查点。每完成一个阶段、跑过验证就存档包括已有的架构决策。任务中断了下一个 Agent 能从检查点恢复不会做出跟前面矛盾的选择。检查点携带架构决策这一点很重要——没有它新 Agent 可能走一条完全不同的路引入微妙的不一致。5. 常见报错排查401、local proxy failed、reading choices、OAuth配置验证管道的过程中最容易卡住的不是 lint 规则本身而是接入层的报错。下面这几类错误我见过太多次逐个拆解。401 Unauthorized这是最常见的接入错误。报错长这样Error: 401 Unauthorized {error: {message: Invalid API key provided, type: invalid_request_error}}原因通常是三件套没写全或写错了。检查清单检查项正确写法常见错误Base URLhttps://taotoken.net/api多了/v1或少了/apiAPI Keysk-开头从控制台复制复制时带了空格或换行Model IDgpt-5.3-codex等完整 ID写成了gpt-5或codex如果你用的是 Codex~/.codex/auth.json里应该是这样{ api_key: sk-your-key-here, base_url: https://taotoken.net/api, model: gpt-5.3-codex }注意base_url不要加尾部斜杠也不要加/v1。有些工具会自动拼接路径多写了反而 404。local proxy failedError: local proxy failed to start: listen tcp 127.0.0.1:8080: bind: address already in use这个报错说明端口被占了。两种解法换端口或者杀掉占用端口的进程。# 查看谁占了 8080 lsof -i :8080 # 杀掉进程 kill -9 PID # 或者换个端口启动 export PROXY_PORT8081如果你在 Docker 里跑检查一下端口映射有没有冲突。docker ps看看有没有其他容器占了同一个端口。reading choices 报错Error: reading choices: unexpected end of JSON input这个报错通常出现在流式响应解析时。原因可能是网络中断导致响应体不完整或者代理层做了缓冲导致 chunk 边界错乱。排查步骤先确认是不是偶发。重试一次如果好了就是网络抖动。如果每次都报检查你的 HTTP 客户端有没有正确设置Accept: text/event-stream。有些工具默认用 JSON 解析器处理 SSE 流遇到不完整的 chunk 就崩了。# 用 curl 直接测试流式接口 curl -N -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $API_KEY \ -H Content-Type: application/json \ -H Accept: text/event-stream \ -d {model:gpt-5.3-codex,stream:true,messages:[{role:user,content:hi}]}如果 curl 能正常流式输出说明服务端没问题是你用的客户端配置有误。检查客户端的超时设置流式请求需要更长的 read timeout。OAuth 相关报错Error: OAuth token exchange failed: invalid_grant如果你用的是 Claude Code 的 OAuth 登录流程这个报错说明 token 过期或刷新失败。Claude Code 的配置在~/.claude/settings.json{ apiProvider: anthropic, apiKey: sk-your-key-here, baseURL: https://taotoken.net/api, model: claude-opus-4-6 }注意 Claude Code 的配置字段名和 Codex 不同baseURL而不是base_urlapiKey而不是api_key。写错了不会报字段错误而是直接 401。如果 OAuth 流程走不通可以改用 API Key 直连模式。在 Claude Code 里设置环境变量export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-your-key-here然后启动时加--api-key参数跳过 OAuth。lint 脚本本身报错SyntaxError: Unexpected token export如果你用 Node.js 跑 TypeScript 写的 lint 脚本需要先编译或者用ts-nodenpx ts-node scripts/lint-deps.ts # 或者 npx tsc scripts/lint-deps.ts node scripts/lint-deps.jsPython 脚本的话注意 shebang 和文件权限chmod x scripts/validate.py ./scripts/validate.py如果报ModuleNotFoundError检查依赖有没有装pip install -r scripts/requirements.txt验证管道卡住不返回有时候validate.py跑着跑着就卡住了没有任何输出。大概率是某个子进程在等输入。检查你的 build 或 test 命令有没有交互式提示。加个超时result subprocess.run(cmd, capture_outputTrue, textTrue, timeout300)超时后捕获TimeoutExpired异常打印当前步骤名方便定位。6. 让 Harness 自己长大从静态规则到自我进化前面讲的 Harness 还是静态的——人定规则Agent 遵守。但真正有意思的地方在于Harness 能从 Agent 的失败里学东西。想想看每次 Agent 犯错都是一个信号。如果同一类错误反复出现说明 Harness 本身有缺口——要么某个包没被 linter 覆盖要么某条规则的错误信息写得不够清楚要么某个场景缺少文档。与其靠人去发现这些缺口不如让系统自己分析。每次验证失败都被结构化地保存到harness/trace/failures/。Critic 脚本定期分析这些记录找出模式和根因——比如发现internal/cache被 7 次违规 import根因是它没被加入层级映射表建议修复是把它加入 Layer 1。然后 Refiner 根据建议去更新 Harness把遗漏的包加入 linter 规则改写含糊的错误信息补上缺失的文档。整个循环跑起来就是Agent 执行 → 验证抓到问题 → Critic 分析模式 → Refiner 更新规则 → 下一个 Agent 受益。Harness 还维护着三种记忆。情景记忆记录具体事件和教训比如macOS 下/var是/private/var的符号链接会导致工作区路径比较失败——这类教训可能只要 10 秒加载却能省下一整个重试循环。程序记忆记录成功的操作步骤比如添加 API 端点的标准五步流程成功率 90%新的子代理执行同类任务时会先查这里。失败记忆专门供 Critic 分析用。每次任务开始时executor 会查询相关记忆这些记忆的价值随着项目演进不断累积。这套闭环走到极致会出现一个很有意思的东西轨迹编译。当同一类任务被成功执行了三次以上而且步骤高度一致——比如添加 API 端点每次都是创建类型文件、写服务方法、加 handler、注册路由、写测试——这个模式就可以被编译成一个确定性脚本像make add-endpoint NAMEfoo这样。以后再做同类任务直接跑脚本LLM 都省了。脚本失败了再回退到 Agent 模式就好。这是个棘轮效应每一个被编译的成功模式都变成了永久基础设施Agent 被释放去处理真正需要创造力的新问题。整个系统的运行成本越来越低能力越来越强。回到开头那个场景。装了 Harness 之后同样的任务会变成这样Agent 启动读 AGENTS.md 找到相关文档列出执行计划你扫一眼批准子代理开始写代码每个结构性操作前先跑预验证层级违反在写代码前就被拦住了完成后另一个模型的子代理做交叉 review抓出机械验证发现不了的逻辑问题每个阶段存检查点、跑验证任务做完经验教训记下来下一个 Agent 接着用。Agent 不需要更聪明——它只是能看见更多了。说到底环境设计的投入回报远高于 prompt 调优。一套好的 Harness 能让普通模型产出可靠的代码而没有 Harness 的顶级模型照样会在同样的坑里反复栽。搭建的前期成本不高——一个下午就能建好基本的 AGENTS.md 和 lint 脚本。但它的价值会随着时间复利式增长记忆越来越丰富lint 规则越来越完善越来越多的操作模式被编译成确定性脚本。半年后回头看你的仓库已经变成了一个高度适配你们团队工作方式的 Agent 运行环境任何新加入的人或新会话的 Agent都能立刻进入状态。如果你还没开始建议的节奏是今天先把 AGENTS.md 建出来这周加一个 lint-deps 脚本把层级规则定下来这个月搭完整的验证管道之后开启 Critic → Refiner 反馈循环让 Harness 跟着代码一起长。最佳实践是先用 creator 把 Harness 建到 70 分以上再开始用 executor 日常开发。需要 API Key 和接入文档的话可以从 TaoToken API Keys 拿接入细节看 TaoToken 接入文档。想先验证模型效果去 模型对话 试几轮。长期跑编码 Agent 的话Coding Plan 更划算。Claude Code 用户可以直接参考 Claude Code 接入指南。竞争优势不再是 Prompt而是 Trajectory。这些积累换个模型复制不来。 Harness Engineering 工程实践：用 AGENTS.md 与 lint 搭建 AI Agent 验证管道
1. 为什么 Agent 总在同一个坑里反复翻车如果你带过 AI Agent 做真实项目大概率见过这个循环Agent 接到任务思考几秒开始写代码一口气生成 200 行。你让它跑一下 lint直接失败——类型定义文件 import 了配置包违反了架构分层约束。Agent 不知道这条规则因为你也没告诉它。于是它开始修移动代码、调整依赖、重新组织。再跑 lint又冒出一个新问题。循环三次之后上下文窗口被错误日志和 diff 塞满Agent 开始忘记最初的任务目标。你让它加个用户认证功能它却在那儿纠结一个完全不相关的 import 路径问题。这不是 Agent 不够聪明是 Agent 看不见。同一个项目昨天的 AI 还记得你们的架构约定今天开个新会话又全忘了。每次协作都要重新解释背景、分层规则、命名规范。AI 生成的代码能跑但完全不符合团队规范code review 时才发现一堆问题。让它修 bug结果引入了新 bug——没有自动验证全靠人肉检查。换成一个新入职的工程师他可能也不熟悉代码库但至少会问一句这个文件应该放在哪个目录这样 import 可以吗他在行动前寻求验证。AI Agent 不会它直接干。问题出在哪Prompt 写得再好也没法穷尽代码库的所有隐式规则。上下文窗口再大也装不下整个仓库的架构决策。教得更好这条路有天花板——写更详细的 system prompt提供更多示例规则会随代码演进变化你永远追不上。规范文档放在钉钉或 Notion 上AI 读不到依赖 AI 的常识不同模型表现差异大不可靠。Harness Engineering 的思路不一样与其教 Agent 怎么做不如让它自己验证做得对不对。靠代码、linter、测试来保证正确性而不是靠 LLM 的直觉。这些机械化检查不会出错不会遗忘也不会被上下文压缩掉。就像 CI/CD 对人类开发者的作用——自动拦截问题。只不过这次拦截的时机更早不是合并前而是写代码前。仓库是 Agent 的操作系统。CPU 很强大但没有操作系统它就是一块高速却无方向的芯片——不知道硬盘在哪、网络协议是什么、哪些内存地址可以写。LLM 也一样。它推理能力很强但它不知道你的internal/types/不能 importinternal/config/不知道新文件该放哪个目录。Harness 就是给它装的操作系统。这个类比背后有几条关键原则。首先仓库是唯一的事实来源。讨论群里的结论、会议上的口头约定、架构师脑子里的蓝图这些对 Agent 来说都不存在。不在仓库里Agent 就看不见看不见就会违反。所以第一步是把一切编码到仓库中架构决策、层级约束、命名规范。不是写在 Wiki 里不是发在群里而是作为版本化的文件提交到 Git。这样知识跟着代码一起走新人 clone 仓库就能拿到全部上下文Agent 打开项目就能读到一切。但编码到仓库不意味着把所有东西塞进一个文件。很多团队的第一反应是写一份巨大的 AGENTS.md500 行什么都有。问题是当一切都重要时什么都不重要。500 行的指令文件挤占了 Agent 宝贵的上下文窗口留给实际任务的空间反而少了。AGENTS.md 应该是地图不是手册——控制在 100 行左右只做索引和指路详细内容放在docs/目录里按需加载。要改 auth 模块先读 AGENTS.md 找到路再读docs/design-docs/auth.md拿细节。用不上的文档根本不加载。保持短小精悍还有一个好处不容易腐烂巨大的指令文件会迅速过时。然后是约束的粒度。Harness 不规定你必须用这个设计模式或函数必须这样写它只管架构边界。大多数代码库的包和模块之间存在自然的依赖方向类型定义被所有人 import、业务逻辑依赖类型但不依赖 HTTP 层、HTTP handler 依赖业务逻辑。Harness 把这种自然方向编码为层级编号——Layer 0 是类型定义不 import 任何内部包Layer 1-2 是工具函数和配置只依赖更低层Layer 3 是业务逻辑Layer 4 是 HTTP handler 和 CLI 命令。规则就一条高层可以 import 低层反过来不行。在这个边界之内怎么实现随便。跟管理大型平台团队一样中心化约束本地自治。最后一条原则关乎人的角色。以前是人写代码、AI 辅助补全现在反过来了——人设计系统架构、约束、验证规则Agent 在系统内执行。人的价值从写出正确的代码变成了设计出让 Agent 能可靠产出正确代码的环境。你不再需要自己拧每一颗螺丝但你得确保流水线是对的。2. 用 AGENTS.md 做约束入口从零搭出可执行的验证管道说了这么多理念具体怎么落地Harness 靠两个引擎协作harness-creator 负责分析代码库、生成基础设施文档、lint 脚本、目录结构harness-executor 在这套基础设施中执行开发任务。它们的关系很简单——executor 启动时先看 AGENTS.md 在不在不在就自动喊 creator 来搭搭完再继续干活。所以任何项目都能直接用 executor 起步。creator 首次运行时会审计项目现状按文档覆盖率、lint 规则覆盖率等维度打出 0-100 分。0-20 分基本是裸奔状态从零搭建全套21-70 分说明有基础但有缺口针对性补充71 分以上已经比较健康微调就行。executor 的工作流是检测环境 → 加载上下文 → 制定计划 → 人类批准 → 执行 → 验证 → 完成。注意人类批准这一步不是走过场——对于非简单任务executor 会创建一个执行计划文件包含任务目标、影响范围、分阶段步骤、验证方式和回退策略。你扫一眼就知道 Agent 打算怎么干觉得不对可以直接改方向。一个装备了 Harness 的项目大致长这样my-project/ ├── AGENTS.md ← 导航地图~100行 ├── docs/ │ ├── ARCHITECTURE.md ← 架构、层级、依赖规则 │ ├── DEVELOPMENT.md ← 构建/测试/lint 命令 │ ├── PRODUCT_SENSE.md ← 业务上下文 │ ├── design-docs/ ← 组件设计文档 │ └── exec-plans/ ← 执行计划active / completed ├── scripts/ │ ├── lint-deps.* ← 层级依赖检查 │ ├── lint-quality.* ← 代码质量规则 │ ├── verify/ ← 端到端功能验证 │ └── validate.py ← 统一验证管道 ├── harness/ │ ├── tasks/ ← 任务状态和检查点 │ ├── trace/ ← 执行轨迹和失败记录 │ └── memory/ ← 经验教训存储 └── [业务代码...]每一部分在执行过程中都有用文档提供知识脚本提供验证harness/提供状态管理和学习能力。其中scripts/下面的机械执法层是核心——它把团队约定从希望被遵守变成不遵守就报错。在动手之前先问能不能做。Harness 里的验证分几类。最核心的是依赖方向检查lint-deps——core/不能 importui/api/和cli/不能互相引用。对应的就是前面说的层级规则靠扫描源码里的 import 语句来检查。其次是质量规则检查lint-quality强制一些编码规范单文件不超过 500 行禁止console.log/print()要求用结构化日志禁止硬编码品牌字符串。这些规则说起来都是常识但 Agent 不提醒就不会遵守。lint 脚本有 Go、TypeScript、Python 三个版本creator 会根据你的项目类型自动生成。但重点不是事后检查而是事前预防。Agent 通常的工作流是写代码、跑测试、发现错误、修复、再跑测试。当一个层级违反在 50 行代码写完后才被 linter 抓到修复代价很大——撤销改动、重新设计差不多要消耗 10 次 tool call。而如果在写代码前先问一句这样做合法吗两次交互就够了python3 scripts/verify_action.py --action create file internal/types/user.go # ✓ VALID: internal/types/ is Layer 0, user.go follows naming convention python3 scripts/verify_action.py --action import internal/core from internal/handler # ✗ INVALID: internal/handler (L4) cannot import internal/core (L3) # Fix: handler should depend on core through interfaces不是每个操作都需要预验证。改个函数体不需要加个测试文件不需要。但只要涉及在新位置创建文件或添加跨包 import就该先验证。层级违反是 Agent 翻车的头号原因。这里有一个容易被忽视但影响很大的细节linter 的错误信息质量直接决定了 Agent 能不能自愈。一条Forbidden import in core/types/user.go看完不知道怎么办但如果改成core/types/user.go imports core/config (Layer 0 → Layer 2). Layer 0 packages must have NO internal dependencies. Fix: Move config-dependent logic to a higher layer, or pass the config value as a parameter.——什么规则违反了、为什么是问题、怎么修全在里面。一条好的报错本身就是一次教学。Harness 不鼓励 Agent 直接跑go build或go test而是提供统一验证入口validate.py因为验证通过在每个项目里含义不同。验证顺序有讲究先 build编译都不过就别往下了再 lint-arch架构约束然后 test功能正确性最后还有一步容易被漏掉——verify。build → lint-arch → test → verify │ │ │ │ │ │ │ └─ 端到端功能验证 │ │ └─ 单元/集成测试 │ └─ 架构和质量合规 └─ 代码能否编译build lint test 能覆盖大部分问题但有一类问题它们抓不到功能层面的正确性。测试通过了不代表功能是对的——测试本身可能覆盖不全或者 Agent 写的测试恰好绕过了关键路径。verify 步骤是项目级别的端到端功能验证——不是函数返回值对不对而是用户执行这个操作最终结果对不对。比如一个 CLI 工具verify 会实际运行几个典型命令检查输出一个 Web API会发几个真实请求验证响应。很多项目一开始并不具备端到端 verify 的能力。这时候 Harness 会引导你创建 verify skill——一组针对项目的可复用验证脚本。思路是先识别核心用户路径比如创建用户→登录→查看资料然后把每条路径编码成可执行的验证脚本。creator 分析项目时会自动生成骨架放在scripts/verify/下面你填充具体的断言逻辑就行。这让验证闭环从代码能跑提升到了功能正确。验证挂了怎么办executor 会自动进入修复循环——分析错误、改代码、重新跑验证一般 1-3 轮就收敛。如果同一个错误转了 3 圈还没过就别让 Agent 继续挣扎了停下来交给人。不是它一定修不好而是再转下去上下文窗口就要爆了。几条踩过坑之后的经验故意引入违规来测试 lint加一个跨层 import 确认能被检测到如果 lint 没报错说明护栏是纸糊的永远不要禁用 lint 规则来解决问题Agent 有时候会想绕过规则比如注释掉 lint 配置应该改代码而不是改规则测试不需要每次跑全量executor 支持只跑受影响的包速度快很多。3. 可复制的 AGENTS.md 与 lint 配置片段理论讲完了。好在 Harness 不是全有或全无的——哪怕不搭完整的六层基础设施一个 AGENTS.md 就能让 AI 协作体验好一截。这套方法适用于任何能跑 shell 命令的 coding agentQodercli、Claude Code、Codex 等都行。多人协作、有明确分层的中大型项目收益最明显个人项目或原型阶段一个 AGENTS.md 加个简单的 lint 脚本就够了。新项目最简单——告诉 creator 你要做什么它会问几个基本问题然后直接生成全套基础设施。老项目也不难creator 会扫描代码库、分析 import 关系、推断层级映射生成反映代码现状的文档。随着项目演进定期跑一次 Improve 模式做体检creator 输出审计报告指出哪些包没被 linter 覆盖、哪些文档没跟上代码变化然后 executor 来实施修复。不管哪种情况最小起步都一样——在项目根目录创建 AGENTS.md# [项目名] Agent Guide ## 快速链接 - [架构总览](docs/ARCHITECTURE.md) — 分层规则、数据流 - [开发指南](docs/DEVELOPMENT.md) — 构建、测试、lint 命令 ## 构建命令 make build # 构建项目 make test # 运行测试 make lint-arch # 运行架构 lint ## 分层规则 Layer 0: types/ → 纯类型定义无内部依赖 Layer 1: utils/ → 工具函数仅依赖 Layer 0 Layer 2: config/ → 配置依赖 Layer 0-1 Layer 3: core/services/ → 业务逻辑依赖 Layer 0-2 Layer 4: api/ cli/ ui/ → 接口层依赖 Layer 0-3彼此不互相引用 ## 质量标准 - 结构化日志禁止 console.log / print() - 单文件不超过 500 行 - PascalCase类型、camelCase函数、kebab-case文件名为什么叫 AGENTS.md这个文件名是业界标准Agent 打开项目时会自动查找并读取它作为了解项目的起点。类似于 README.md 是给人看的AGENTS.md 是给 Agent 看的。接下来是 lint 规则清单。以 TypeScript 项目为例scripts/lint-deps.ts的核心逻辑是扫描 import 语句并对照层级映射表// scripts/lint-deps.ts import { readFileSync, readdirSync, statSync } from fs; import { join, relative } from path; const LAYER_MAP: Recordstring, number { src/types: 0, src/utils: 1, src/config: 2, src/core: 3, src/api: 4, src/cli: 4, src/ui: 4, }; function getLayer(filePath: string): number | null { for (const [prefix, layer] of Object.entries(LAYER_MAP)) { if (filePath.startsWith(prefix)) return layer; } return null; } function checkFile(filePath: string): string[] { const errors: string[] []; const sourceLayer getLayer(filePath); if (sourceLayer null) return errors; const content readFileSync(filePath, utf-8); const importRegex /from\s[](.?)[]/g; let match; while ((match importRegex.exec(content)) ! null) { const importPath match[1]; if (!importPath.startsWith(.) !importPath.startsWith(/)) continue; const resolved importPath.replace(/, src/); const targetLayer getLayer(resolved); if (targetLayer null) continue; if (targetLayer sourceLayer) { errors.push( ${filePath} imports ${resolved} (Layer ${sourceLayer} → Layer ${targetLayer}). Layer ${sourceLayer} packages must NOT depend on Layer ${targetLayer}. Fix: Move the dependent logic to a higher layer, or pass the value as a parameter. ); } } return errors; }对应的scripts/lint-quality.ts检查质量规则// scripts/lint-quality.ts const RULES [ { name: max-file-lines, check: (content: string) content.split(\n).length 500, message: File exceeds 500 lines. Split into smaller modules., }, { name: no-console-log, check: (content: string) !/console\.(log|warn|error)\(/.test(content), message: Use structured logger instead of console.log., }, { name: no-hardcoded-brand, check: (content: string) !/[]MyBrand[]/.test(content), message: Brand strings must come from config, not hardcoded., }, ];统一验证入口scripts/validate.py把各步骤串起来#!/usr/bin/env python3 Unified validation pipeline: build → lint-arch → test → verify import subprocess import sys STEPS [ (build, [make, build]), (lint-arch, [make, lint-arch]), (test, [make, test]), (verify, [python3, scripts/verify/run_all.py]), ] def run_pipeline(): for name, cmd in STEPS: print(f\n{*50}) print(f[{name}] Running: { .join(cmd)}) print(f{*50}) result subprocess.run(cmd, capture_outputTrue, textTrue) if result.returncode ! 0: print(f[{name}] FAILED) print(result.stdout) print(result.stderr) sys.exit(1) print(f[{name}] PASSED) print(\n✓ All validation steps passed.) if __name__ __main__: run_pipeline()如果你用的是 Claude Code可以在项目根目录的.claude/settings.json里配置验证钩子让每次文件修改后自动触发 lint{ hooks: { PostToolUse: [ { matcher: Edit|Write, command: python3 scripts/validate.py --quick, description: Run quick validation after file changes } ] } }--quick模式只跑 lint-arch 和受影响的测试不跑全量 build响应更快。完整验证留给提交前或 CI 阶段。如果你用的是 Cline可以在.cline/settings.json里配置 MCP 工具链把验证脚本暴露成 MCP tool{ mcpServers: { harness-verify: { command: python3, args: [scripts/mcp_server.py], env: { PROJECT_ROOT: . } } } }这样 Agent 在写代码前就能调用verify_action工具做预检查而不是等写完再跑 lint。对于 Codex 用户~/.codex/auth.json里配置好 API 端点后可以在项目根目录的codex.toml里指定验证命令[project] name my-project validation_command python3 scripts/validate.py pre_action_command python3 scripts/verify_action.py --action [model] provider openai model_id gpt-5.3-codex base_url https://taotoken.net/api这里的关键是三件套必须写全Base URL、API Key、Model ID。缺任何一个都会导致 401 或连接失败。API Key 建议通过环境变量注入不要硬编码在配置文件里。4. 验证请求与成功结果一次从失败到通过的完整动作配置写好了接下来跑一次完整的验证流程看看从失败到通过的全过程。假设 Agent 接到任务在internal/handler/user.go里添加一个用户查询接口。它先读 AGENTS.md找到架构文档然后列出执行计划。你批准后它开始写代码。第一版代码写完了跑python3 scripts/validate.py [build] Running: make build [build] PASSED [lint-arch] Running: make lint-arch [lint-arch] FAILED src/handler/user.go imports src/core/user (Layer 4 → Layer 3). Layer 4 packages must NOT depend on Layer 3 directly. Fix: handler should depend on core through interfaces defined in Layer 0.Agent 看到这条报错知道问题在哪了。它没有直接改代码而是先跑预验证python3 scripts/verify_action.py --action import src/core/user from src/handler # ✗ INVALID: src/handler (L4) cannot import src/core/user (L3) # Fix: Define an interface in src/types/ and inject the implementation.根据提示Agent 在src/types/里定义了一个UserService接口然后让 handler 依赖这个接口而不是具体实现。改完再跑验证 [build] Running: make build [build] PASSED [lint-arch] Running: make lint-arch [lint-arch] PASSED [test] Running: make test [test] PASSED (12 tests, 0 failures) [verify] Running: python3 scripts/verify/run_all.py [verify] Running: verify_user_query.py → GET /api/users/123 ... 200 OK → Response contains id: 123, name: Alice → PASSED [verify] All 1 verification scripts passed. ✓ All validation steps passed.整个过程 Agent 只用了 4 次 tool call 就收敛了。如果没有预验证它可能会先写完 50 行代码跑 lint 失败再撤销重写消耗 10 次以上的 tool call。验证通过后另一个模型的子代理做交叉 reviewreview_result Agent( descriptionReview: user query handler, modelcodex, promptf Review the following changes for: 1. Logic correctness and edge cases 2. Consistency with architecture (see ARCHITECTURE.md) 3. Naming clarity and code readability 4. Performance implications Changes: {coding_result.diff} Task context: {task_description} )Review 子代理输出通过或需修改。如果需修改回到编码子代理修复再过一轮 review。Review 中发现的问题会被记录到harness/trace/里。如果某类问题反复出现说明应该把它编码成新的 lint 规则——把 review 中的软知识逐渐转化成验证管道中的硬规则。中等以上的任务还会设检查点。每完成一个阶段、跑过验证就存档包括已有的架构决策。任务中断了下一个 Agent 能从检查点恢复不会做出跟前面矛盾的选择。检查点携带架构决策这一点很重要——没有它新 Agent 可能走一条完全不同的路引入微妙的不一致。5. 常见报错排查401、local proxy failed、reading choices、OAuth配置验证管道的过程中最容易卡住的不是 lint 规则本身而是接入层的报错。下面这几类错误我见过太多次逐个拆解。401 Unauthorized这是最常见的接入错误。报错长这样Error: 401 Unauthorized {error: {message: Invalid API key provided, type: invalid_request_error}}原因通常是三件套没写全或写错了。检查清单检查项正确写法常见错误Base URLhttps://taotoken.net/api多了/v1或少了/apiAPI Keysk-开头从控制台复制复制时带了空格或换行Model IDgpt-5.3-codex等完整 ID写成了gpt-5或codex如果你用的是 Codex~/.codex/auth.json里应该是这样{ api_key: sk-your-key-here, base_url: https://taotoken.net/api, model: gpt-5.3-codex }注意base_url不要加尾部斜杠也不要加/v1。有些工具会自动拼接路径多写了反而 404。local proxy failedError: local proxy failed to start: listen tcp 127.0.0.1:8080: bind: address already in use这个报错说明端口被占了。两种解法换端口或者杀掉占用端口的进程。# 查看谁占了 8080 lsof -i :8080 # 杀掉进程 kill -9 PID # 或者换个端口启动 export PROXY_PORT8081如果你在 Docker 里跑检查一下端口映射有没有冲突。docker ps看看有没有其他容器占了同一个端口。reading choices 报错Error: reading choices: unexpected end of JSON input这个报错通常出现在流式响应解析时。原因可能是网络中断导致响应体不完整或者代理层做了缓冲导致 chunk 边界错乱。排查步骤先确认是不是偶发。重试一次如果好了就是网络抖动。如果每次都报检查你的 HTTP 客户端有没有正确设置Accept: text/event-stream。有些工具默认用 JSON 解析器处理 SSE 流遇到不完整的 chunk 就崩了。# 用 curl 直接测试流式接口 curl -N -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $API_KEY \ -H Content-Type: application/json \ -H Accept: text/event-stream \ -d {model:gpt-5.3-codex,stream:true,messages:[{role:user,content:hi}]}如果 curl 能正常流式输出说明服务端没问题是你用的客户端配置有误。检查客户端的超时设置流式请求需要更长的 read timeout。OAuth 相关报错Error: OAuth token exchange failed: invalid_grant如果你用的是 Claude Code 的 OAuth 登录流程这个报错说明 token 过期或刷新失败。Claude Code 的配置在~/.claude/settings.json{ apiProvider: anthropic, apiKey: sk-your-key-here, baseURL: https://taotoken.net/api, model: claude-opus-4-6 }注意 Claude Code 的配置字段名和 Codex 不同baseURL而不是base_urlapiKey而不是api_key。写错了不会报字段错误而是直接 401。如果 OAuth 流程走不通可以改用 API Key 直连模式。在 Claude Code 里设置环境变量export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-your-key-here然后启动时加--api-key参数跳过 OAuth。lint 脚本本身报错SyntaxError: Unexpected token export如果你用 Node.js 跑 TypeScript 写的 lint 脚本需要先编译或者用ts-nodenpx ts-node scripts/lint-deps.ts # 或者 npx tsc scripts/lint-deps.ts node scripts/lint-deps.jsPython 脚本的话注意 shebang 和文件权限chmod x scripts/validate.py ./scripts/validate.py如果报ModuleNotFoundError检查依赖有没有装pip install -r scripts/requirements.txt验证管道卡住不返回有时候validate.py跑着跑着就卡住了没有任何输出。大概率是某个子进程在等输入。检查你的 build 或 test 命令有没有交互式提示。加个超时result subprocess.run(cmd, capture_outputTrue, textTrue, timeout300)超时后捕获TimeoutExpired异常打印当前步骤名方便定位。6. 让 Harness 自己长大从静态规则到自我进化前面讲的 Harness 还是静态的——人定规则Agent 遵守。但真正有意思的地方在于Harness 能从 Agent 的失败里学东西。想想看每次 Agent 犯错都是一个信号。如果同一类错误反复出现说明 Harness 本身有缺口——要么某个包没被 linter 覆盖要么某条规则的错误信息写得不够清楚要么某个场景缺少文档。与其靠人去发现这些缺口不如让系统自己分析。每次验证失败都被结构化地保存到harness/trace/failures/。Critic 脚本定期分析这些记录找出模式和根因——比如发现internal/cache被 7 次违规 import根因是它没被加入层级映射表建议修复是把它加入 Layer 1。然后 Refiner 根据建议去更新 Harness把遗漏的包加入 linter 规则改写含糊的错误信息补上缺失的文档。整个循环跑起来就是Agent 执行 → 验证抓到问题 → Critic 分析模式 → Refiner 更新规则 → 下一个 Agent 受益。Harness 还维护着三种记忆。情景记忆记录具体事件和教训比如macOS 下/var是/private/var的符号链接会导致工作区路径比较失败——这类教训可能只要 10 秒加载却能省下一整个重试循环。程序记忆记录成功的操作步骤比如添加 API 端点的标准五步流程成功率 90%新的子代理执行同类任务时会先查这里。失败记忆专门供 Critic 分析用。每次任务开始时executor 会查询相关记忆这些记忆的价值随着项目演进不断累积。这套闭环走到极致会出现一个很有意思的东西轨迹编译。当同一类任务被成功执行了三次以上而且步骤高度一致——比如添加 API 端点每次都是创建类型文件、写服务方法、加 handler、注册路由、写测试——这个模式就可以被编译成一个确定性脚本像make add-endpoint NAMEfoo这样。以后再做同类任务直接跑脚本LLM 都省了。脚本失败了再回退到 Agent 模式就好。这是个棘轮效应每一个被编译的成功模式都变成了永久基础设施Agent 被释放去处理真正需要创造力的新问题。整个系统的运行成本越来越低能力越来越强。回到开头那个场景。装了 Harness 之后同样的任务会变成这样Agent 启动读 AGENTS.md 找到相关文档列出执行计划你扫一眼批准子代理开始写代码每个结构性操作前先跑预验证层级违反在写代码前就被拦住了完成后另一个模型的子代理做交叉 review抓出机械验证发现不了的逻辑问题每个阶段存检查点、跑验证任务做完经验教训记下来下一个 Agent 接着用。Agent 不需要更聪明——它只是能看见更多了。说到底环境设计的投入回报远高于 prompt 调优。一套好的 Harness 能让普通模型产出可靠的代码而没有 Harness 的顶级模型照样会在同样的坑里反复栽。搭建的前期成本不高——一个下午就能建好基本的 AGENTS.md 和 lint 脚本。但它的价值会随着时间复利式增长记忆越来越丰富lint 规则越来越完善越来越多的操作模式被编译成确定性脚本。半年后回头看你的仓库已经变成了一个高度适配你们团队工作方式的 Agent 运行环境任何新加入的人或新会话的 Agent都能立刻进入状态。如果你还没开始建议的节奏是今天先把 AGENTS.md 建出来这周加一个 lint-deps 脚本把层级规则定下来这个月搭完整的验证管道之后开启 Critic → Refiner 反馈循环让 Harness 跟着代码一起长。最佳实践是先用 creator 把 Harness 建到 70 分以上再开始用 executor 日常开发。需要 API Key 和接入文档的话可以从 TaoToken API Keys 拿接入细节看 TaoToken 接入文档。想先验证模型效果去 模型对话 试几轮。长期跑编码 Agent 的话Coding Plan 更划算。Claude Code 用户可以直接参考 Claude Code 接入指南。竞争优势不再是 Prompt而是 Trajectory。这些积累换个模型复制不来。