Agent Harness Architect 🏗️

基于 Anthropic《Effective Harnesses for Long-Running Agents》论文提炼。
把你的 agent 架构描述给它，输出完整 harness 诊断报告 + 可直接部署的 bridge artifact 文件。

---

核心主张

模型是商品，harness 才是壁垒。

再强的模型，没有好的 harness，长时间运行都会退化——过早宣告完成、环境退化、session 交接信息丢失。这个 skill 把 Anthropic 工程团队踩坑总结的最佳实践，变成你的 agent 可直接执行的升级方案。

---

触发条件

用户描述中出现以下任意一种：

• - 我的 agent 跑着跑着就失败了 / 忘了之前做了什么
• 每次新 session 都要重新开始
• 帮我优化 agent 架构
• 如何让 agent 跨 session 保持状态
• 用户粘贴了自己的 CLAUDE.md / AGENTS.md / agent 配置

---

执行流程

Step 1 — 架构摸底（必须先问，不能跳过）

向用户提以下问题（可一次性发出，不要逐条等待）：

要帮你把 agent 架构调到最优，我需要了解几个关键点：

1. 1. 角色分工：你有几个 agent？每个负责什么？（比如：一个规划、一个执行、一个监控）
2. 运行周期：任务通常跑多久？是分钟级 session，还是需要跨多天？
3. 当前最大痛点：session 中断丢进度？agent 以为做完了实际没做好？不知道上次跑到哪？
4. 现有状态管理：有没有 progress 文件、日志、git commit？还是全靠模型上下文记忆？
5. 平台：OpenClaw / Claude Code / 其他？操作系统？

Step 2 — Harness 健康度诊断

根据用户回答，对照以下 8 个维度逐一打分（✅ 已有 / 🟡 部分 / ❌ 缺失）：

维度	诊断问题
Session Bridge	每次新 session 启动时，有没有结构化文件（非纯文本）告知上次做到哪了？
固定启动序列

agent 每次启动是否有强制执行的固定步骤顺序（不可跳过）？ |
| Smoke Test | 执行任务前，有没有先验证环境/依赖是否可用？ |
| 原子 Checkpoint | 每完成一个最小单元，是否立即 commit/保存状态？ |
| 输出自验证 | agent 报告完成之前，有没有机制验证结果真的 OK？ |
| 状态文件格式 | 状态追踪用 JSON 还是 Markdown checkbox？（JSON 更防 agent 误改） |
| Multi-Agent 编排 | 多个 agent 之间有没有明确的消息传递协议，还是靠文件系统凑合？ |
| 降级方案 | 某个依赖挂掉时，有没有明确的 fallback 行为？ |

输出诊断表，标出每个维度的分数和简要原因。

Step 3 — 优先级排序

根据诊断结果，按 影响 × 实现难度 矩阵输出 P0/P1/P2 改进项：

P0（立刻改，成本低收益高）：通常是 Session Bridge + 固定启动序列
P1（本周改）：Smoke Test + 原子 Checkpoint
P2（下阶段）：输出自验证 + Multi-Agent 编排协议

Step 4 — 生成 Bridge Artifacts

必须生成以下文件内容，用户可直接复制部署：

4a. agent-progress.json（Session 状态桥）

json
{
_说明: Agent Session 状态桥。每次 session 启动时读取，结束时更新。JSON 格式防止 agent 误改结构。,
schemaVersion: 1.0,
lastSession: {
timestamp: null,
trigger: null,
summary: 首次初始化,
smokeTest: null,
result: pending
},
taskTracking: {
说明: 每完成一个任务后在此更新。status: pending|inprogress|done|failed,
recentCompleted: []
},
environmentStatus: {
lastChecked: null,
result: null,
notes: null
},
knownIssues: []
}

4b. Session 恢复协议（插入你的 CLAUDE.md / AGENTS.md）

markdown

Session 恢复协议（每次会话强制执行，顺序不可跳过）

Step 1 — 读状态桥：读 agent-progress.json，了解上次 session 执行到哪、哪些成功、哪些失败。

Step 2 — 读任务队列：读当前待办任务列表，确认优先级。

Step 3 — Smoke Test：验证核心环境可用（服务在线？API 可达？依赖存在？）。
不通过 → 先修复环境，不执行任何业务任务。

Step 4 — 逐任务执行：每次只执行一个任务，完成后立即：
- 更新 agent-progress.json 中该任务状态为 done
- git commit 一次（message 用任务编号）
- 再执行下一个任务

Step 5 — Session 结束：更新 agent-progress.json 的 lastSession 字段，记录本次执行摘要。

4c. Output Self-Verification Gate（输出自检，插入消息处理流程末尾）

markdown
【output-gate】——准备发出任何内容前，内部思考检查（不输出）：
├── 是否包含应对外保密的系统内部术语？→ 有则重写
├── 是否把思考过程当成了结论发出？→ 有则删除过程只保留结论
└── 当前上下文是否应该静默（规则明确不该回复的场景）？→ 是则 NO_REPLY
结论: 发出 / NO_REPLY / 已修改后发出

Step 5 — 针对用户平台的定制建议

根据用户平台输出具体命令/配置，例如：

OpenClaw 用户：
powershell

检查 gateway 状态（Smoke Test）

openclaw status

每个任务完成后立即 commit

git add -A && git commit -m done: [任务编号] [任务描述]

Claude Code 用户：
bash

在 CLAUDE.md 中添加 session 恢复协议

使用 JSON 格式跟踪任务状态，而非 Markdown checkbox

通用建议：

• - 状态文件用 JSON，不用 Markdown（agent 更不容易意外破坏结构）
• 每个 session 的前 N 步必须是固定的，写进系统提示，不可跳过
• 完成报告前必须有端到端验证，不能只看代码改了

---

自动优化循环（Self-Improvement Protocol）

此 skill 内置进化机制：

触发条件

以下情况发生时，自动写入 capability-radar 或等效的学习日志：

• - 用户描述的问题在本 skill 覆盖范围外 → 记录为功能缺口
• 用户反馈生成的方案不够具体 → 记录为精度缺口
• 同类架构问题出现 3 次以上 → 触发模式提炼，更新此 skill

版本演进规则

触发条件	动作
新平台适配需求 ≥ 2 次	新增 Step 5 平台适配分支
某维度诊断误判 ≥ 2 次

优化该维度的诊断问题描述 |

| 生成的 artifact 被用户大幅修改 | 分析修改模式，更新模板 |

---

使用示例

输入：

我有一个 Claude Code agent，每天晚上 10 点自动跑，扫描 memory 文件、生成日记、检查 gateway 状态。但经常跑到一半挂掉，下次启动不知道上次做到哪了，重复做已经做过的事。

输出：

1. 1. 诊断报告（Session Bridge ❌、固定启动序列 ❌、Smoke Test 🟡、Checkpoint ❌）
2. P0 改进：立即创建 agent-progress.json + 写固定 5 步启动协议
3. 生成完整的 agent-progress.json 初始文件
4. 生成可粘贴的 Session 恢复协议段落
5. 针对 Claude Code / Windows 的具体 PowerShell 命令

---

设计来源

核心模式来自：

• - Anthropic 工程博客《Effective Harnesses for Long-Running Agents》（2025）
• OpenClaw 三引擎架构实战（2026）：Engine A 战略层 + Engine C 全执行层 + session bridge 落地经验

核心洞察：创造清晰的上下文桥梁文件（bridge artifacts），让每个新 session 能在最少 token 消耗内理解当前状态。这是模型无关的架构原则——无论用什么模型，harness 设计决定了 agent 能跑多远。