Agent Harness 14 步路线图

一句话：Harness 是 Loop 的地基。一个坏 harness 上的好 loop，是大规模生产垃圾的最快方法。14 步从单 Agent 搭到自我进化系统。

作者：Codez (@0xCodez) · 2026-06-16 · 原文：X 长文 互动：likes 564 / retweets 87 / bookmarks 993 / views 84,721 与既存文档关系：

• 概念体系见 [[harness-engineering]]（Rule/Skill/Subagent/Workflow/Scripts/MCP 六件套）
• 工程实现细节见 [[Harness工程AgentLoop]]（生命周期/上下文/工具/容错/调度）
• 上层 Loop 范式见 [[Addy-Osmani-Loop-Engineering]]（Loop 是 Harness 套上 timer）

本文定位：从 0 到 self-improving 的具体路径与顺序。

核心公式

1
Self-Improving System = Harness + Loop + Memory（且顺序不能反）

关键反直觉：

• 模型从来没变过，变的是它周围的 harness —— “自我进化”是 harness 在累积，不是模型在学。
• Loop 没有加 intelligence，只是把 harness 套了个定时器。Harness 没搭好就上 loop，复利是双向腐烂。
• Harness = 模型 + 工具 + 权限 + 上下文。其他一切（subagents/hooks/memory）都是这四件的形状变体。

三层不要混

实操分类原则：

• 事实 → CLAUDE.md（每 session 都要的）
• 流程 → skills（多步操作）
• 单文件夹规则 → rules/
• 强制约束 → hooks（不能依赖模型”听话”）
• 隔离任务 → subagents

14 步路线图（3 段）

Part 1 · What Harness is（01-04）

Part 2 · Build the foundation（05-09）

Part 3 · Make it compound（10-14）

顺序就是教训（重点）

一次手动跑通 → 加 context/permission → 加 reviewer subagent → 加 memory → 最后才上 loop。

错位代价：loop 跑得越勤，harness 的问题放大得越快。

.claude/ 目录速查

1
2
3
4
5
6
7
8
.claude/
├─ CLAUDE.md          # 事实，每次 session 必读（≤500 tokens）
├─ settings.json      # 权限、模型、hooks
├─ .mcp.json          # 外部工具连接
├─ rules/             # 路径级行为（tests.md / python-types.md）
├─ agents/            # 子 agent 定义（reviewer.md / eval-runner.md）
├─ skills/            # 可复用流程（pr-checklist/SKILL.md）
└─ agent-memory/      # 跨 run 记忆（STATE.md）

判别原则：能讲清每个文件为什么存在；讲不清的，删。

settings.json 模板

1
2
3
4
5
6
7
{
  "model": "claude-sonnet-4-6",
  "permissions": {
    "autoApprove": ["Read(*)", "Grep(*)", "Bash(npm test)", "Bash(git status)"],
    "deny": ["Bash(rm -rf*)", "Bash(git push*)", "Edit(.env*)", "Edit(secrets/*)"]
  }
}

放行/禁止判断标准：弄错了多难撤销？

• 撤销便宜（读、grep、测试）→ autoApprove
• 撤销昂贵（rm -rf、force-push、读 secrets）→ always deny or prompt
• 中间地带 → autoApprove + 记日志

Hooks 模板（最值钱的两个）

1
2
3
4
5
6
7
8
9
10
11
"hooks": {
  "PreToolUse": [{
    "matcher": "Bash",
    "command": "./.claude/hooks/block-dangerous.sh"
    // exit 2 = 阻断，模型无法"礼貌忽略"
  }],
  "PostToolUse": [{
    "matcher": "Edit|Write",
    "command": "prettier --write \"$CLAUDE_FILE_PATH\""
  }]
}

反模式：20 个 hooks。一个好 harness 只有 1-2 个锋利 hook；判断题留给模型，强制题交给 hooks。

STATE.md 模板

1
2
3
4
5
6
7
8
9
10
11
12
# Project memory

## Verified facts   # stop guessing about these
- prc is in dollars, not cents (checked via SELECT MIN/MAX)
- auth middleware order: rate_limit -> jwt -> rbac

## Lessons learned  # distill the general ones into skills
- Windows CI runners fail TLS 1.2 in PowerShell — use bash
- Migrations on tables >1M rows must batch in 10k chunks

## Last session     # resume, don't restart
2026-06-11 · 3 fixes merged, 2 escalated. Next: verify rate-limit fix.

Memory 复利三动作：

1. Write before walking away —— 每次跑完更新 state file
2. Read at the start —— 每次开局先读 state + 相关 skills
3. Distill into skills —— 一般化教训（”Windows runner 用 bash”）从 state 升格为 skill

8 个 Harness 反模式（check list）

对 Seetong 团队的 5 个优先动作

1. 梳理/新建 .claude/：CLAUDE.md 限 500 tokens / rules/ 按模块分 / skills/ 装 PR checklist / agents/ 装 reviewer
2. 加 PreToolUse 安全 hook：挡 rm -rf / 改 .env / push 到 master / main（监控类 APP 误删代价极高）
3. 加 reviewer subagent：让独立 context 检查主 agent 改动（Seetong 历史代码量大，主 agent 容易”自我宽容”）
4. 建 .claude/agent-memory/STATE.md：每次跑完更新 verified facts（pod install 顺序/pch 路径依赖）/ lessons（push 前要 pod repo update）
5. 警惕”loop on bad harness”：harness 没搭好之前不上 /loop 或 Routines。复利是双向的：好 harness 复利加速，烂 harness 复利腐烂

金句卡

“所有人都在聊 loop，但几乎没人聊 loop 跑在什么上面。” —— 0xCodez

“Loop engineering sits one floor above the harness.” —— Addy Osmani（被 0xCodez 引用）

“CLAUDE.md 是建议，hooks 是强制。” —— 区分软硬约束的本质

“Workflow 是指挥家，harness 是管弦乐队。” —— workflow 与子组件的关系

“模型从来没变过，变的是它周围的 harness。” —— 自我进化的真相

“Loop 拿走所有掌声，harness 干所有活。” —— 哲学升华

相关链接

• 原文 raw：../../raw/2026-06-17-0xCodez-Agent-Harness-14-Steps.md
• 拆解 digest：../../raw/2026-06-17-0xCodez-Agent-Harness-14-Steps-digest.md
• 同主题 wiki：./harness-engineering.md（6 核心概念体系）
• 同主题 wiki：./Harness工程AgentLoop.md（工程实现细节）
• 同主题 wiki：./HarnessEngineering企业级实战.md
• 上层 Loop 范式：../02-ai-coding/Addy-Osmani-Loop-Engineering.md
• 作者 Substack：https://movez.substack.com/

标签：#主题/AIAgent #主题/AI-Coding #手法/体系框架 #手法/工程实践 #场景/X长文 #场景/ClaudeCode