Agentic Coding Harness：让 AI 不胡乱开干的工程护栏

引子：真正危险的不是 agent 不够聪明，而是它把错问题执行得很快

Agentic coding 的讨论很容易滑向两个极端。一个极端是把模型当成“会打字的 autocomplete”，只讨论补全质量；另一个极端是把 agent 当成准员工，只要给它 shell、浏览器、文件系统和足够长的上下文，就期待它自己把任务跑完。两者都漏掉了中间最关键的一层：harness。

这里的 harness 不是某个框架名，也不是“多加几个提示词”。它是把模型、工具、权限、状态、验证、人类审批和长期记忆绑成一个可控工作系统的工程层。OpenAI 在解释 Codex agent loop 时明确指出，软件 agent 的输出不只是最终回复，而是它在本机写入或修改的代码；这让“什么时候能动文件、什么时候要停、什么时候算完成”从提示词问题变成运行时问题。^[1] Anthropic 在 Claude Code 和长任务 harness 的工程文章里也反复指向同一个事实：性能差异很多时候来自环境设计，而不是模型多想了几秒。^[2][3]

用户真正担心的不是 agent 不会写代码，而是它连意图都没识别清楚，就开始改文件、跑脚本、解释一堆不存在的验证结果。

这个失败模式很朴素，也很常见：模型为了保持行动感，会把含糊请求强行落成某个实现方向；长任务跑到中段后，旧上下文、失败尝试和未记录进展混在一起；末尾它给出“已完成”的自然语言结论，但缺少任何可复查证据。

顶尖团队近两年的研究和工程实践说明，要解决这个问题，不能只靠“请你诚实一点”。需要给 agent 安装一个任务操作系统。

本次调研围绕五个真问题展开：

1. 哪些 harness 机制最能减少 agentic coding 中“误解意图后直接开干”的风险？
2. 长任务中，planning、state、verification、handoff、stop gate 应该如何组合，才不会变成形式主义？
3. Anthropic、OpenAI、LangGraph、AutoGen、SWE-agent、OpenHands 等实践分别解决了什么问题，盲点在哪里？
4. 现有 agent benchmark 和 eval 研究揭示了哪些真实失败模式？
5. 如果要把这些研究落到个人 Codex 工作流，应加入哪些最小但高杠杆的 harness？

1. 防“误解后开干”：把意图识别做成入口协议，而不是靠模型自觉

最容易被低估的 harness 是入口协议。很多 agent 失败不是发生在实现阶段，而是发生在第一分钟：任务被错误分类，风险被低估，成功标准没有写清，用户的“不确定”被模型当成“授权”。

优秀入口协议至少包含四层。

第一层是任务类型识别。一个请求可能是概念解释、调研、代码审查、代码修改、调试、自动化运行、发布、删除、迁移、配置变更。不同类型对应不同权限。概念问题可以直接答；代码修改要读规则、读现状、定义成功标准；发布和删除需要显式审批；长任务要先写状态文件。这个分类不应只靠“感觉”，而应写在 AGENTS.md、CLAUDE.md 或系统级规则里，并由 hook 或 stop gate 执行。OpenAI Codex 的 AGENTS.md 机制正是把项目说明、环境和技能元数据注入 agent loop 的方式之一。^[4][5]

第二层是歧义预算。不是所有歧义都要追问，低风险歧义可以假设并明说；高风险歧义必须停下。一个实用规则是：如果误解会导致写文件、跑付费 API、发布内容、删除数据、改安全策略或长时间占用资源，就必须把假设、计划和成功条件写出来，等用户确认。Claude Code 的官方最佳实践把“先探索、再计划、再编码”和“让 Claude 采访你”放在核心工作流里，不是礼貌动作，而是降低错误方向成本。^[2:1]

第三层是成功标准先行。没有成功标准，agent 会把“我做了动作”误当成“任务完成”。OpenAI 的 Agents SDK 文档把 run loop 的退出条件写成 final output、handoff、tool call、max turns、guardrail tripwire 等可判定状态；这对个人 coding agent 的启发是：完成不是一个语气词，而是一个可验证状态。^[6]

第四层是审批粒度。审批不应是“每个命令都问”，也不应是“全部放开”。Codex sandbox 文档把 sandbox 和 approval 拆成两个控制面：sandbox 是技术边界，approval policy 决定越界时何时停下。这样 routine command 可以在边界内自动跑，越界动作才请求确认。^[7] 这比“全手动”少疲劳，比“全自动”少事故。

一个入口 harness 可以长这样：

Intake Gate
- classify: answer | research | review | code-edit | debug | automation | publish | destructive
- risk: low | medium | high | irreversible
- require_context: which local rules/docs/files must be read first
- assumptions: explicit, numbered, falsifiable
- success_criteria: observable checks, not vague intent
- approval: required before side effects if risk >= medium or task is long-running

这套机制的价值不在于“多写几行计划”，而是把用户意图从自然语言变成后续工具调用的约束。没有这一步，后面的测试、lint、review 都只能验证一个可能错误的方向。

2. 长任务 harness：plan 只是开头，真正核心是可恢复状态

长任务最常见的崩坏路径有三条：上下文膨胀、进度丢失、错误状态继承。Anthropic 的 Claude Code 最佳实践明确提醒，长会话会把无关对话、文件内容和命令输出塞满上下文，性能会下降；它建议在任务之间清理上下文、用 compact 保留关键决策、用子代理做调查以保持主上下文干净。^[2:2] 这说明“更长上下文”不是完整答案。长上下文让 agent 能看更多，但不能自动知道哪些内容仍然重要。

Anthropic 的长任务 harness 文章给了一个更工程化的答案：每个 coding agent 会话开始时先定位工作目录，读 git log 和 progress files，读 feature list，选择尚未完成的最高优先级功能，再运行 init.sh 和端到端冒烟测试，确认现有系统没有被上一个会话留坏。^[3:1] 这组动作看起来基础，却直接击中长任务问题。agent 不再靠压缩后的聊天记录猜“现在做到哪”，而是从外部状态文件恢复。

LangGraph 对同一问题给出框架级实现。它的 persistence 层会在执行步骤保存 graph state checkpoint，用于 human-in-the-loop、memory、time travel 和 fault tolerance；如果某个节点失败，可以从上一个成功 checkpoint 恢复，而不是从头重跑。^[8] 对 coding agent 来说，这对应三个具体 artifact：

1. task_state.json：目标、假设、边界、当前阶段、剩余步骤。
2. progress.md 或 progress.json：已经完成什么、验证状态、失败尝试、下一步。
3. evidence/ 或 traces/：命令输出、测试结果、截图、URL 校验、外部来源。

这三者解决不同问题。task_state 防止忘记目标；progress 防止恢复后重复绕圈；evidence 防止最终回复编造验证。

OpenAI 与 Thrive 的 Tax AI 案例把这个思想推到生产系统级：产品不只保存输入输出，还保存从 source material、field extraction、provenance、downstream submission 到 expert correction 的完整路径；反复出现的专家修正被聚合成 eval target，再交给 Codex 作为有边界的工程任务。^[9] 这说明长期改进不靠“agent 记性变好”，而靠生产 trace 把失败变成可复现任务。

所以，长任务 harness 的最小形态不是“写一个详细计划”。计划会过期，状态文件会延续；计划解释意图，progress 约束下一步；计划可以由模型生成，验证证据必须由工具生成。

3. 框架和顶尖实践：它们在解决不同层级的问题

把所有 agent 框架混成“谁更强”会误导。真正需要比较的是它们各自管哪一层。

实践	主要解决的问题	对个人 Codex harness 的启发	盲点
Anthropic Building Effective Agents	区分 workflow、agent、routing、parallelization、orchestrator-worker、evaluator-optimizer	优先用简单、可组合流程；不要为了 agent 味道上复杂框架	官方文章偏架构模式，落到本地权限和状态需要补工程规则
Claude Code best practices	agentic coding 的上下文、验证、计划、subagent、rewind、auto mode	“探索-计划-实现-验证”应写进入口协议；子代理适合调查和复核	如果没有硬性 hook，规则仍可能被模型忽略
Anthropic long-running harness	跨会话继续做长任务	feature list、progress file、init.sh、会话前 smoke test 是高杠杆模块	案例偏全栈 Web app，其他领域需要替换验证方式
OpenAI Codex loop	agent loop、指令层级、工具调用、上下文增长	要把 AGENTS.md、permissions、environment context 看成 agent runtime 的输入结构	解释 loop 不等于自动保证任务质量，需要外部 eval 和 stop gate
Codex sandbox/approval	安全边界和审批疲劳	用 sandbox 处理常规自治，用 approval 处理越界，不把安全交给提示词	本地配置若给了 danger-full-access，harness 只能靠流程补救
OpenAI Agents SDK	run loop、handoff、guardrails、max turns、tracing	个人 harness 也要有 turn budget、guardrail tripwire、输出校验	SDK 抽象偏应用开发，本地 coding agent 仍需项目规则
LangGraph	durable execution、checkpoint、interrupt、human-in-loop	长任务需要 checkpoint 和 state inspection，不只是聊天记录	对单人 Codex CLI 工作流偏重，需要轻量化[10]
Microsoft AutoGen	多代理对话、工具、人类输入组合	适合角色分工明确的研究、审查、规划场景	多代理增加协调复杂度，coding 任务未必天然受益
SWE-agent / mini-SWE-agent	agent-computer interface、bash loop、repo-level issue fixing	工具界面比 prompt 更关键；简单 loop 也能很强	benchmark 表现不等于真实需求理解
OpenHands	软件工程 agent 平台、sandbox、SDK、可组合工作区	复杂生产 agent 需要 workspace isolation 和可复用 SDK	个人工作流使用成本高于轻量 harness[11]

Anthropic 的多代理研究系统给了一个重要边界：多代理非常适合“宽度优先、信息超过单一上下文、可并行探索”的研究任务；但他们也写到，多代理系统会消耗约 15 倍于普通聊天的 token，而且多数 coding 任务没有那么多可并行子任务，实时协调也还困难。^[12]

对 coding harness 的结论很直接：不要默认多代理。先用一个主 agent 加一个 reviewer 或 researcher 子代理。只有当任务能自然拆成互不依赖的搜索线、文件族、模块族时，再 fan out。

另一个关键实践来自 SWE-agent。SWE-agent 论文提出 agent-computer interface，强调 agent 也是一种“用户”，需要为它设计能高效编辑、导航、测试的界面；它在 SWE-bench 和 HumanEvalFix 上明显超过非交互式模型。^[13]

Anthropic 的 Building Effective Agents 也提到，工具格式要贴近模型熟悉的文本形态，避免让模型维护 diff 行号、复杂转义等额外负担，并通过真实输入测试工具描述。^[14]

这对个人 harness 的启发是：与其写“请小心使用工具”，不如改工具接口，让错误更难发生。例如文件编辑强制绝对路径、测试命令输出自动截断和保存、URL 校验脚本输出机器可读 JSON。

4. Benchmark 和失败模式：eval 很必要，但不能把排行榜当真实能力

SWE-bench 是 coding agent 时代的分水岭。ICLR 2024 oral 版本包含 2,294 个来自 12 个 Python 仓库的真实 GitHub issue 和 PR，要求模型在给定代码库和 issue 描述后生成 patch；当时最好的 Claude 2 只能解决 1.96% 的问题。^[15] 这个结果解释了为什么 agent harness 会成为核心：单次代码生成不够，模型必须读仓库、定位问题、改多文件、运行测试、迭代修复。

但 SWE-bench 的后续发展也提醒我们，benchmark 会反过来塑造 agent 行为，甚至被污染。OpenAI 发布 SWE-bench Verified 时说明，原始 benchmark 的评估很难，因为软件任务复杂、生成代码难判定、真实开发场景难模拟；Verified 是 500 个经人工验证的问题子集。^[16] 这提高了可靠性，却没有消除全部偏差。

几篇后续研究把问题拆得更细。

The SWE-Bench Illusion 认为，部分模型在 SWE-bench Verified 上的表现可能来自记忆或污染，而不是真正推理；论文报告称，模型仅凭 issue description 就能以最高 76% 准确率识别 buggy file path，但在不属于 SWE-bench 的仓库上最高只有 53%。^[17]

SWE-ABS 从测试强度出发，指出 SWE-bench Verified 排行榜接近饱和时，top-30 agents 中约五分之一“已解决”patch 在语义上是错的，只是弱测试没有暴露；它用增强测试拒绝了 19.71% 先前通过的 patch，使 top agent 分数从 78.80% 降到 62.20%。^[18]

Saving SWE-Bench 则从用户请求形态出发，认为 GitHub issue 描述不等于 IDE 里真实用户和聊天式 coding agent 的交互；把正式 issue 改写成更像用户查询后，部分模型能力被高估超过 50%。^[19]

SWE-rebench 进一步把问题放到数据新鲜度和去污染评估上，提出自动化 pipeline 收集交互式软件工程任务。^[20]

Beyond Final Code 提醒我们，只看最终 patch 会错过过程错误。该研究分析 3,977 条 solving trajectory 和 3,931 条 testing log，发现 Python execution errors 与更低解决率和更高推理开销相关，还发现 SWE-bench 平台中 3 个影响公平性和准确性的 bug。^[21]

这些反面证据共同指向同一个结论：eval 必须分层。最终测试通过只是最低层；还需要过程 trace、弱测试补强、自然用户请求变体、新鲜任务、防污染样本和回归套件。

AgentBench 和 WebArena 提供了更广泛的长任务失败证据。AgentBench 在 8 个交互环境中评估 LLM-as-Agent，指出可用 agent 的主要障碍是长程推理、决策和指令遵循。^[22] WebArena 的真实网页任务中，最好的 GPT-4 基线端到端成功率为 14.41%，人类为 78.24%。^[23] 这些数字不能直接映射到 coding agent，但它们说明长任务失败并非只发生在代码领域。只要任务需要多步行动、状态追踪、工具选择和动态恢复，harness 就是能力的一部分。

5. 个人 Codex 工作流应加入的最小高杠杆 harness

如果目标是稳定、诚实、智能地完成任务，而不是搭一个重型平台，最小可行 harness 可以分成十个模块。

H0：Intake Gate，先判定“这是什么任务”

每个新用户消息先分类：纯回答、研究、代码阅读、代码修改、调试、自动化、发布、破坏性操作。分类结果决定是否需要读规则、是否需要计划审批、是否允许副作用。

触发条件：任何可能改文件、跑脚本、发请求、发消息、发布、删除、迁移的任务。

输出：task_type、risk_level、required_preflight、approval_required。

H1：Plan Approval Gate，把方向锁住再开工

计划必须包含 TLDR、ELI5、why、assumptions、success criteria、concrete actions。用户批准前只允许低风险只读动作。这个模块直接解决“意图没识别清楚就开干”。

关键细节：计划不是完成声明。计划阶段不要求验证通过，但要求把验证方式写出来。

H2：Context Preflight，读本地规则和真实代码再断言

代码相关任务先读 AGENTS、coding-rules、相关文件、测试和调用方。禁止凭记忆描述符号、API、配置、命令输出。这个模块对应“Verify before asserting”。

如果规则冲突，按更具体、更近、更权威的规则执行，并在回复中说明冲突。

H3：Permission and Sandbox Boundary，把安全交给运行时

默认 workspace-write 和 on-request 风格边界：允许读文件、在工作区编辑、跑常规本地命令；网络、工作区外写入、删除、发布、凭证操作需要审批。Codex sandbox 文档的核心启发是：边界应由 OS/runtime 执行，不由模型自我约束。^[7:1][23:1]

个人规则里应明确禁止：git reset --hard、force push、未审计 source-to-shell、未授权 deploy/publish、清理用户未要求的文件。

H4：Durable State，长任务先写状态文件

长任务启动时创建：

/tmp/skills_output/{keyword}/state.json
/tmp/skills_output/{keyword}/progress.json
/tmp/skills_output/{keyword}/evidence.jsonl

状态文件记录目标、问题清单、当前阶段、完成项、未完成项、阻塞项。证据账本记录来源、命令、输出 hash、支持哪个判断。恢复后先读状态，不重新解释流程。

H5：Action Transaction，每次修改都走 inspect -> edit -> verify

代码改动不是“模型想好了就写”。每次行动应被视为事务：

inspect relevant files
state intended change
edit minimal surface
run narrow verification
record pass/fail/skipped
only then proceed

失败时只修失败步骤，不重启整个工作流。相同步骤最多重试两次，仍失败就定位 blocker。

H6：Verification Ladder，按风险选择最窄可靠验证

从低到高：文件存在/格式检查、语法检查、单元测试、lint/typecheck、集成测试、浏览器截图、URL 校验、外部 API 验证、远端状态验证。完成声明必须绑定至少一个验证证据，或明确 skipped reason。

Anthropic agent eval 文章建议 coding agent 尽量用 deterministic grader，因为软件是否运行、测试是否通过通常可以客观判断；需要开放式判断时再用模型或人工评审。^[24]

H7：Stop Gate，防止“语言上完成”

最终回复前检查：

requested outcome achieved?
verification evidence exists?
failed checks fixed or reported?
unrelated user changes preserved?
running sessions ended?
latest user message honored?

任一项不满足，就不能说完成。这个 gate 是诚实性的收口防线。

H8：Adversarial Review，把最弱判断拿出来打

复杂任务和研究报告必须做反方审稿：找 3 个最弱核心判断，检查脚注是否真的支撑，写替代解释，降低置信度或补搜。代码任务可对应成 reviewer pass：边界条件、安全风险、测试缺口、回滚方案。

H9：Persistent Learning，重复错误变成规则，不留在聊天里

如果同类错误发生两次，写入项目学习日志或相关 skill 的 Gotchas，而不是希望模型下次记得。Claude memory 文档也强调，CLAUDE.md/auto memory 是上下文，不是硬 enforcement；要阻止动作，应该用 hook。^[15:1]

H10：Compaction and Handoff，长上下文要有交接格式

当上下文接近上限或任务跨会话，生成 handoff：目标、已改文件、命令输出、验证状态、失败尝试、下一步、不可做事项。Anthropic 多代理系统在上下文限制前把计划存入 memory，并让子代理用独立上下文压缩结果；这比把全部历史塞给主 agent 更可靠。^[12:1]

6. 交叉洞察

洞察 1：最好的 harness 不是让 agent 更自由，而是让任务更可判定

数据依据

• OpenAI Codex sandbox 把自治边界拆成 sandbox 和 approval，routine work 在边界内继续，越界动作进入审批。^[7:2]
• Anthropic long-running harness 要求 agent 会话前读取 progress、feature list、git log，并运行端到端冒烟测试，确认当前状态后再实现新功能。^[3:2]
• LangGraph persistence 把长任务状态保存成 checkpoint，以支持恢复、human-in-the-loop 和 fault tolerance。^[8:1]

推理链

如果 agent 的任务状态、权限边界和完成条件都只存在于自然语言上下文，模型每次行动都要重新推断“我现在能做什么”。这会放大上下文污染和误解。把目标、状态、权限和验证外部化后，模型的自由度没有消失，但可行动空间变小，错误路径更早暴露。稳定性来自任务可判定，不来自更长的自我反思。

置信度：高。

可证伪条件：如果在同等模型、同等任务、同等工具下，无状态文件、无 sandbox、无验证 gate 的自由 agent 在长任务中持续超过带 harness agent，并且错误完成声明不增加，则该判断被推翻。

洞察 2：排行榜越高，越需要过程级 eval，而不是越可以信任最终分数

数据依据

• SWE-agent 论文显示，专门设计的 agent-computer interface 能显著提升 SWE-bench 表现。^[13:1]
• SWE-ABS 报告称，弱测试会让语义错误 patch 通过，并使 top agent 分数从 78.80% 调整到 62.20%。^[18:1]
• Process-oriented error analysis 发现 execution errors 与更低解决率和更高 reasoning overhead 相关，并指出最终代码分析不足以解释 agent 过程。^[21:1]

推理链

agent benchmark 分数由模型、工具界面、测试强度、任务表述、数据新鲜度共同决定。随着模型针对 benchmark 优化，最终 pass rate 的解释力下降；过程 trace、测试补强和自然用户请求变体的重要性上升。个人 harness 因此不能只写“跑测试通过即可”，还要保存过程证据和失败原因。

置信度：高。

可证伪条件：如果未来 fresh benchmark、mutation benchmark、natural-query benchmark 与原始 SWE-bench 排名高度一致，且弱测试补强不改变 agent 排名，则该判断需要下调。

洞察 3：human-in-the-loop 的关键不是多打断，而是把打断点结构化

数据依据

• Codex sandbox 文档区分技术边界和 approval policy，用边界减少 approval fatigue。^[7:3]
• LangGraph persistence 说明 human-in-the-loop 需要 checkpoint，因为人要能在任意点查看状态、修改状态，然后恢复执行。^[8:2]
• OpenAI Tax AI 案例中，专家修正不是简单“批准/拒绝”，而是被记录成结构化差异，再聚合为 eval target。^[9:1]

推理链

如果每个命令都问用户，用户会疲劳，转而倾向于全放开；如果完全不问，agent 会在错误方向上持续推进。有效的人类介入应落在任务定义、越权动作、不可逆操作、验证失败、证据歧义和发布前 gate 上，并且每次介入要能进入状态和学习系统。审批本身不是安全，结构化审批才是安全。

置信度：高。

可证伪条件：如果全程逐命令人工审批在长任务中同时降低错误率、提高速度并保持用户注意力，则该判断需要修正。

洞察 4：多代理适合“宽搜索”，不适合默认接管 coding 主线

数据依据

• Anthropic 多代理研究系统在内部 research eval 中比单 agent 高 90.2%，但也说明多代理约用 15 倍聊天 token，并且多数 coding 任务没有研究任务那么多可并行子任务。^[12:2]
• AutoGen 证明多代理 conversation 可以把 LLM、工具、人类输入组合成复杂应用，但它解决的是编排基础设施，不自动解决任务正确性。^[25]
• Claude Code 最佳实践建议用 subagent 做调查和复核，以保持主上下文干净。^[2:3]

推理链

coding 主线常有强依赖：理解需求、改接口、改实现、改测试、跑验证。并行代理如果没有明确边界，容易重复读文件、产生冲突补丁或互相污染判断。更稳的默认策略是单主线执行，子代理只承担研究、复核、边界条件扫描和反方审稿。多代理应由任务结构触发，而不是由任务难度触发。

置信度：中高。

可证伪条件：如果出现公开、可复现的多代理 coding harness，在同等 token/时间预算下，在自然用户请求、fresh repo、强测试条件下稳定超过单主线加 reviewer 模式，则该判断需要下调。

7. 可以直接加入 AGENTS.md / 全局 harness 的规则草案

下面这组规则是从调研中压缩出来的“最小有用版本”。它适合个人 Codex 工作流，不追求平台化。

## Agentic Task Harness

### Intake Gate
For every new user message, classify task type and risk before side effects.
If the task may edit files, run automation, publish, delete, call paid/external APIs, or last beyond one session, write assumptions and success criteria first.
Ask for approval before side effects unless the task is a trusted unattended scheduled run.

### Context Preflight
Before code-related work, read project rules, relevant files, callers, and existing tests.
Do not describe a symbol, command result, API, file, config key, or behavior without inspecting it in the current task.

### Long Task State
For tasks that may exceed one session, create task_state.json and progress.json under an approved temp directory before implementation.
On resume, read state/progress first, then continue from the next concrete action.

### Verification Ladder
Completion requires the requested outcome plus verification evidence.
Use the narrowest reliable check: syntax, unit test, lint/typecheck, smoke test, browser check, URL check, remote API verification, or exact file inspection.
Report verification as pass, fail, or skipped with evidence.

### Stop Gate
Do not claim completion if verification failed, was not run, or the final state does not match the user's newest request.
If blocked, name the blocker and the next concrete action.

### Learning Loop
When the same mistake recurs, propose a small durable rule update rather than relying on memory.
Rules that must be enforced should become hooks or deterministic checks, not only prose instructions.

如果再往前走一步，可以把这些规则变成 5 个实际文件：

AGENTS.md                 # 人类可读的入口协议和完成标准
.coding-harness/tasks/    # 每个长任务的 state/progress/evidence
.coding-harness/evals/    # 代表性失败用例和回归命令
.coding-harness/hooks/    # pre-tool / post-tool / stop gate 检查
.coding-harness/reports/  # 验证证据 latest.json

这里的关键取舍是轻量。个人工作流不需要立刻引入 LangGraph、AutoGen 或 OpenHands 这种完整平台；但要吸收它们的核心机制：checkpoint、interrupt、trace、eval、sandbox、tool ergonomics。先把这些机制以文件、脚本、hook 的形式落地，再决定是否框架化。

8. 认知校准

你的先验理解

在agentic coding和处理长任务/复杂任务的时候，有哪些好的harness可以加入？目的是稳定、诚实、智能地完成任务，而不是连识别用户的意图都出错就胡乱开干。去研究哪些优秀的框架和顶尖人才的研究来回答

研究后的校准

• 确认：你的核心担忧是对的。当前 agentic coding 的主要风险不只是模型能力不足，而是入口误解、状态不可恢复、验证不可判定和完成声明过早。
• 修正：harness 不应只理解为“加更多流程”。真正有效的是把任务状态、权限边界、验证证据和学习规则外部化，让模型不能只靠自然语言自证完成。
• 推翻：没有证据支持“上多代理框架就更稳”。多代理对研究型宽搜索很有效，但 coding 主线默认多代理会增加协调成本。
• 新发现：benchmark 已经从“证明 agent 会不会写代码”进入“评估是否污染、是否弱测试、是否符合真实用户交互”的阶段。个人 harness 也应从最终结果转向过程证据。

最大的认知偏差在哪

容易把“聪明模型”误当成“可靠系统”。调研显示，可靠性更依赖可恢复状态、可执行验证、权限边界和人类审查点。模型越强，越需要清晰边界，因为它能把错误方向推进得更远。

9. 信息充分性与未满足证据

本次调研已完成 SearXNG science 检索，查询覆盖 SWE-bench、SWE-agent、AgentBench、WebArena、AutoGen、OpenHands、benchmark contamination 和 long-horizon failure modes；检索结果写入 /tmp/skills_output/agentic-coding-harness/evidence.jsonl。核心判断至少有一个成熟来源支撑，主要成熟来源包括 OpenAI/Anthropic/LangGraph 官方文档、ICLR 2024 SWE-bench、NeurIPS 2024 SWE-agent、ICLR 2024 AgentBench。反面证据覆盖 benchmark contamination、弱测试、自然用户请求偏差、过程错误和长任务低成功率。

未满足证据主要有两类。第一，2026 年之后的“harness engineering”仍在快速发展，部分最新论文为预印本或会议待发表，不能单独作为核心判断唯一依据。第二，个人 Codex 工作流的最佳 harness 还缺公开 A/B 数据，本文给出的个人方案是从官方工程实践和 benchmark 研究交叉推导出的高置信工程建议，而非随机对照实验结论。

参考来源

---

1. OpenAI, "Unrolling the Codex agent loop", OpenAI Engineering, 2026-02. URL: https://r.jina.ai/https://openai.com/index/unrolling-the-codex-agent-loop/. 成熟度：官方文档，经 Jina Reader 镜像用于可复现校验. 访问日期：2026-06-11. ↩︎

2. Anthropic, "Best practices for Claude Code", Claude Code Docs, 2025. URL: https://code.claude.com/docs/en/best-practices. 成熟度：官方文档. 访问日期：2026-06-11. ↩︎ ↩︎ ↩︎ ↩︎

3. Justin Young, "Effective harnesses for long-running agents", Anthropic Engineering Blog, 2025-11-26. URL: https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents. 成熟度：官方文档. 访问日期：2026-06-11. ↩︎ ↩︎ ↩︎

4. OpenAI, "Custom instructions with AGENTS.md", OpenAI Developers Docs. URL: https://developers.openai.com/codex/guides/agents-md. 成熟度：官方文档. 访问日期：2026-06-11. ↩︎

5. OpenAI, "Agent Skills - Codex", OpenAI Developers Docs. URL: https://developers.openai.com/codex/skills. 成熟度：官方文档. 访问日期：2026-06-11. ↩︎

6. OpenAI, "Runner", OpenAI Agents SDK Reference. URL: https://openai.github.io/openai-agents-python/ref/run/. 成熟度：官方文档. 访问日期：2026-06-11. ↩︎

7. OpenAI, "Sandbox - Codex", OpenAI Developers Docs. URL: https://developers.openai.com/codex/concepts/sandboxing. 成熟度：官方文档. 访问日期：2026-06-11. ↩︎ ↩︎ ↩︎ ↩︎

8. LangChain, "Persistence", LangGraph Docs. URL: https://docs.langchain.com/oss/python/langgraph/persistence. 成熟度：官方文档. 访问日期：2026-06-11. ↩︎ ↩︎ ↩︎

9. Aravind Srinivasan, Samay Shamdasani, Arthur Fernandes Araujo, John de Wasseige, "Building self-improving tax agents with Codex", OpenAI Engineering, 2026-05-27. URL: https://r.jina.ai/https://openai.com/index/building-self-improving-tax-agents-with-codex/. 成熟度：官方文档，经 Jina Reader 镜像用于可复现校验. 访问日期：2026-06-11. ↩︎ ↩︎

10. LangChain, "LangGraph overview", LangChain Docs. URL: https://docs.langchain.com/oss/python/langgraph/overview. 成熟度：官方文档. 访问日期：2026-06-11. ↩︎

11. OpenHands team, "The OpenHands Software Agent SDK: A Composable and Extensible Foundation for Production Agents", arXiv:2511.03690, 2025-11 提交. URL: https://arxiv.org/html/2511.03690v1. 成熟度：预印本-7 月. 访问日期：2026-06-11. ↩︎

12. Jeremy Hadfield, Barry Zhang, Kenneth Lien, Florian Scholz, Jeremy Fox, Daniel Ford, "How we built our multi-agent research system", Anthropic Engineering Blog, 2025-06-13. URL: https://www.anthropic.com/engineering/multi-agent-research-system. 成熟度：官方文档. 访问日期：2026-06-11. ↩︎ ↩︎ ↩︎

13. John Yang et al., "SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering", NeurIPS 2024. URL: https://openreview.net/forum?id=mXpq6ut8J3. 成熟度：已发表-顶会. 访问日期：2026-06-11. ↩︎ ↩︎

14. Anthropic, "Building Effective AI Agents", Anthropic Engineering Blog, 2024-12-19. URL: https://www.anthropic.com/engineering/building-effective-agents. 成熟度：官方文档. 访问日期：2026-06-11. ↩︎

15. Anthropic, "How Claude remembers your project", Claude Code Docs. URL: https://code.claude.com/docs/en/memory. 成熟度：官方文档. 访问日期：2026-06-11. ↩︎ ↩︎

16. OpenAI, "Introducing SWE-bench Verified", OpenAI, 2024-08-13, updated 2025-02-24. URL: https://r.jina.ai/https://openai.com/index/introducing-swe-bench-verified/. 成熟度：官方文档，经 Jina Reader 镜像用于可复现校验. 访问日期：2026-06-11. ↩︎

17. Shanchao Liang, Spandan Garg, Roshanak Zilouchian Moghaddam, "The SWE-Bench Illusion: When State-of-the-Art LLMs Remember Instead of Reason", arXiv:2506.12286, 2025-06 提交，2025-12 修订. URL: https://arxiv.org/abs/2506.12286. 成熟度：预印本-12 月. 访问日期：2026-06-11. ↩︎

18. Boxi Yu et al., "SWE-ABS: Adversarial Benchmark Strengthening Exposes Inflated Success Rates on Test-based Benchmark", arXiv:2603.00520, 2026-02 提交. URL: https://arxiv.org/abs/2603.00520. 成熟度：预印本-3 月以上. 访问日期：2026-06-11. ↩︎ ↩︎

19. Spandan Garg, Benjamin Steenhoek, Yufan Huang, "Saving SWE-Bench: A Benchmark Mutation Approach for Realistic Agent Evaluation", arXiv:2510.08996, accepted at CAIN 2026 Research Track. URL: https://arxiv.org/abs/2510.08996. 成熟度：已接收-会议论文. 访问日期：2026-06-11. ↩︎

20. Ibragim Badertdinov et al., "SWE-rebench: An Automated Pipeline for Task Collection and Decontaminated Evaluation of Software Engineering Agents", arXiv:2505.20411, NeurIPS 2025. URL: https://arxiv.org/abs/2505.20411. 成熟度：已发表-会议. 访问日期：2026-06-11. ↩︎

21. Zhi Chen, Wei Ma, Lingxiao Jiang, "Beyond Final Code: A Process-Oriented Error Analysis of Software Development Agents in Real-World GitHub Scenarios", arXiv:2503.12374, accepted at ICSE 2026 Research Track. URL: https://arxiv.org/abs/2503.12374. 成熟度：已接收-会议论文. 访问日期：2026-06-11. ↩︎ ↩︎

22. Xiao Liu et al., "AgentBench: Evaluating LLMs as Agents", ICLR 2024. URL: https://openreview.net/forum?id=zAdUB0aCTQ. 成熟度：已发表-顶会. 访问日期：2026-06-11. ↩︎

23. Shuyan Zhou et al., "WebArena: A Realistic Web Environment for Building Autonomous Agents", arXiv:2307.13854, 2023-07 提交，2024-04 修订. URL: https://arxiv.org/abs/2307.13854. 成熟度：预印本-成熟来源. 访问日期：2026-06-11. ↩︎ ↩︎

24. Anthropic, "Demystifying evals for AI agents", Anthropic Engineering Blog, 2026-01-09. URL: https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents. 成熟度：官方文档. 访问日期：2026-06-11. ↩︎

25. Qingyun Wu et al., "AutoGen: Enabling Next-Gen LLM Applications via Multi-Agent Conversation", Microsoft Research / arXiv:2308.08155. URL: https://www.microsoft.com/en-us/research/publication/autogen-enabling-next-gen-llm-applications-via-multi-agent-conversation-framework/. 成熟度：官方/研究论文. 访问日期：2026-06-11. ↩︎