复刻 Claude Code 项目御马术缰绳系统 harness engineering 落地蓝图

可以。下面我直接给你一版面向你自己 harness 项目的落地蓝图 。它不是"复刻 Claude Code"，而是把前面研究里最值钱的部分，翻成一个适合你做 vibe coding / agentic coding 的可实施架构：先追求成功率、稳定性、可评估 ，再追求花哨能力。这个方向和 Anthropic 近几篇工程文的核心一致：agent 的表现，很大程度取决于 harness、context engineering、tools、hooks 和 eval，而不只是模型本身。(Claude)

一、先定目标：你的 harness 要解决什么

你这个项目的第一目标，不是"让 agent 会写更多代码"，而是让它在真实项目里更经常地做到下面四件事：

正确理解任务边界。
在长流程里不跑偏。
能靠验证闭环自己修复一部分错误。
失败时能留下可恢复的状态，而不是整段会话作废。

这正是 Anthropic 对长任务 harness、上下文工程和 agent eval 的主线：上下文是稀缺资源，长任务必须靠更好的组织、切分、交接和验证，而不是单会话硬扛。(Anthropic)

二、你的最小强版本架构

我建议你把第一版做成 6 层：

1. Intent 层

负责把用户一句模糊需求，变成可执行工单。

输入：

用户自然语言目标
项目上下文
约束条件
验收标准

输出：

task brief
done criteria
risk level
推荐工作流

这层的作用，是防止一上来就"开始写代码"。Anthropic 对 agent 的实践一直强调：成功系统通常是简单、可组合的模式，而不是一上来进入复杂自治。(Anthropic)

2. Memory 层

负责上下文组织，而不是简单存东西。

它不该是"项目知识大仓库"，而应是：

常驻规则
按需专题知识
当前任务工作集
历史经验沉淀

Claude Code 文档明确说明每次 session 都是新的 context window，跨会话依赖的是 CLAUDE.md 一类持久指令和 auto memory，这本质上就是"受控加载"而非"全量记忆"。(Claude)

3. Agent 层

不要单体万能 agent。拆成最少 3 个角色：

Planner
Builder
Evaluator

复杂一点再加：

Researcher
Refactorer
Release Guardian

Anthropic 的多 agent 与 long-running harness 文章都指向同一个设计：不同角色在不同上下文里工作，再通过结构化产物交接。(Anthropic)

4. Tool 层

工具不是越多越好，而是越可筛选、越省 context 越好。

最低配工具：

代码搜索
文件读写
shell/sandbox
lint/typecheck/build
test runner
browser/e2e
截图/视觉检查
git diff / commit draft

Anthropic 关于 tool design 的建议非常明确：工具定义要清晰、工具边界要明确、返回值要 token-efficient。(Anthropic)

5. Orchestration 层

这里放 hooks、permissions、状态切换、压缩、handoff、审计。

Claude Code 文档把 hooks 放得很核心，因为很多高质量行为不是 prompt 写出来的，而是生命周期里"在正确时机拦一下、补一下、记一下"。(Claude)

6. Eval 层

没有 eval，harness 永远只是在"感觉上变好"。

Anthropic 的 eval 文章说得很直接：没有 eval，很容易陷入 reactive loop，线上出问题后再修，修一个坏一个。(Anthropic)

三、建议的目录结构

下面这版结构适合你先做 MVP：

text 复制代码

harness/
  apps/
    cli/
    api/
    dashboard/
  agents/
    planner/
      prompt.md
      policy.yaml
      output_schema.json
    builder/
      prompt.md
      policy.yaml
      output_schema.json
    evaluator/
      prompt.md
      policy.yaml
      output_schema.json
    researcher/
      prompt.md
      policy.yaml
      output_schema.json
  memory/
    global/
      constitution.md
      coding_standards.md
      tech_stack.md
      evaluation_policy.md
    project/
      project_brief.md
      architecture.md
      constraints.md
      acceptance_criteria.md
    topics/
      frontend.md
      backend.md
      database.md
      auth.md
      deployment.md
      testing.md
    runs/
      <run_id>/
        task_brief.json
        plan.json
        progress.log
        findings.md
        decisions.md
        diffs/
        screenshots/
        eval/
        handoff.json
    lessons/
      patterns.md
      failures.md
      fixes.md
  workflows/
    feature.yaml
    bugfix.yaml
    refactor.yaml
    migrate.yaml
    spike.yaml
  hooks/
    session_start.py
    pre_tool_use.py
    post_tool_use.py
    task_completed.py
    pre_compact.py
    session_end.py
  tools/
    code_search.py
    file_ops.py
    shell_runner.py
    test_runner.py
    browser_runner.py
    visual_check.py
    git_tools.py
    doc_search.py
  policies/
    permissions.yaml
    risk_tiers.yaml
    write_boundaries.yaml
    network_policy.yaml
  state/
    state_machine.py
    models.py
  evals/
    datasets/
    scorers/
    regression/
    dashboards/
  logs/
  configs/
    models.yaml
    routing.yaml
    hooks.yaml
    memory.yaml

这套结构的关键不是"文件摆得整齐"，而是把 Anthropic 文档里分散的几个概念落到硬边界上：持久指令、扩展层、工具层、hooks、memory、eval。Claude Code 官方也明确区分了 CLAUDE.md、skills/subagents、hooks、MCP/工具等不同扩展职责，不是把所有逻辑塞进一个 prompt。(Claude)

四、Memory 设计：这是你项目成功率最关键的一层

我建议你用 4 层 memory。

A. Constitution Memory

最稳定、最少改。

内容：

代码风格
默认工作原则
风险策略
不允许做的事
默认验证要求

这层类似长期常驻规则。Claude Code 的项目记忆也是通过持久指令文件影响后续所有会话。(Claude)

B. Project Memory

只描述"这个项目是什么"。

内容：

项目目标
当前架构
技术栈
已知模块
关键约束
业务优先级

这层像项目级 CLAUDE.md，让 agent 不用每次重新猜项目背景。官方文档明确推荐先从项目约定入手，再逐步加其他扩展能力。(Claude)

C. Topic Memory

按需加载。

例如：

frontend.md
database.md
auth.md
deployment.md

原则：

不进入当前任务就不要加载
每个专题控制长度
只放高密度经验，不放可从代码现推的事实

这符合 Anthropic 的 context engineering 原则：上下文是有限资源，应精心策展，而不是堆满。(Anthropic)

D. Run Memory

每个 run 独立。

包含：

当前目标
当前 plan
已修改文件
失败日志
测试结果
阻塞点
下一步

这层非常重要，因为长任务里真正需要随时更新的是运行态，不是长期知识。Anthropic 的长任务 harness 文章强调通过结构化中间产物在多个上下文窗口之间交接。(Anthropic)

Memory 加载策略

你可以直接实现成：

启动必载：constitution + project brief
进入某领域任务：动态加载对应 topic
每次 agent 切换：加载该角色所需最小上下文
compact 前：把 run memory 压成 handoff
session 结束：只沉淀 lessons，不把整段聊天塞进长期记忆

这和 Claude Code 的"fresh context + persistent instructions + auto memory"思路是一致的。(Claude)

五、Agent 分工：不要做万能工，做装配线

1. Planner

职责：

理解任务
拆分步骤
定义 done criteria
识别风险
选择 workflow
决定是否需要 researcher / evaluator 参与

输出建议：

json 复制代码

{
  "task_type": "feature|bugfix|refactor|spike",
  "goal": "...",
  "constraints": ["..."],
  "done_criteria": ["..."],
  "plan_steps": [
    {"id": "p1", "desc": "...", "owner": "builder"},
    {"id": "p2", "desc": "...", "owner": "evaluator"}
  ],
  "risks": ["..."],
  "required_tools": ["code_search", "test_runner"]
}

2. Builder

职责：

读相关代码
最小修改实现
产生 patch
跑基础验证
输出修改说明

Builder 不负责解释业务，也不负责主导架构争议。它只做实现。这样可以减少单 agent 的角色冲突。(Anthropic)

3. Evaluator

职责：

跑 lint/typecheck/build/test
跑 E2E / browser checks
检查 done criteria
判断是否回退 Builder 修复

Anthropic 在长任务文章里专门强调测试工具能显著改善 agent 表现，因为 agent 能通过验证发现代码表面上看不到的问题。(Anthropic)

4. Researcher

职责：

只负责搜资料
搜代码库
搜设计文档
搜 issue / 约束
输出摘要，不直接改代码

Researcher 可以大幅降低 Builder 的上下文噪声。

5. Refactorer

职责：

只在"实现已通但质量不足"时介入
重构局部模块
提升可维护性
不扩大 scope

6. Release Guardian

职责：

检查部署风险
检查环境变量
检查 migration
检查回滚策略
检查变更说明

六、Hook 点位：这是让系统"稳下来"的关键

Claude Code 的 hooks 文档已经给了很好的启发：在不同生命周期点插入策略、自动化、审计和上下文注入。(Claude)

你自己的最小 hooks 设计

1. SessionStart

做什么：

加载 constitution memory
加载 project brief
初始化 run_id
检查 repo 状态
注入当前分支、未提交变更、环境可用性

目标：

防止一开始就信息缺失。

2. UserPromptSubmit

做什么：

把模糊需求标准化
抽取任务类型、约束和 done criteria
如果缺验收标准，自动生成默认标准

目标：

把自然语言变成工单。

3. PreToolUse

做什么：

风险分级
阻止危险命令
限制写入范围
检查是否超出目标文件夹
网络白名单
对 destructive 命令要求更高权限

Anthropic 的 hooks 和工具拦截机制就是为这种"工具前治理"设计的。(Claude Platform)

4. PostToolUse

做什么：

记录文件改动
抽取关键输出
更新 run memory
如果输出太长，做摘要而非全文入上下文

这和 Anthropic 对工具 token 效率的要求一致。(Anthropic)

5. PostToolUseFailure

做什么：

分类失败类型
记录失败原因
生成下一步修复建议
避免同样错误重复三次以上

6. TaskCompleted

做什么：

生成 handoff artifact
更新 lessons learned
写入 eval 指标
标记任务完成状态

7. PreCompact

做什么：

压缩 run memory
只保留目标、已完成、阻塞点、关键文件、验证结果、下一步
删除冗余输出

Anthropic 对 context engineering 的核心就是这个：压缩时保留"继续成功所需的信息"，不是机械总结。(Anthropic)

8. SessionEnd

做什么：

写 lessons
保存最终状态
输出下次恢复入口

七、任务状态机：不要只靠聊天流推进

你应该显式建一个状态机。

转移逻辑

INTAKE -> PLANNING

当任务被标准化，明确 goal / constraints / done criteria。
PLANNING -> RESEARCHING

当缺少架构知识、接口信息、依赖细节。
PLANNING -> IMPLEMENTING

当问题边界足够清晰。
IMPLEMENTING -> VERIFYING

代码改动完成。
VERIFYING -> REPAIRING

任一验证失败。
REPAIRING -> VERIFYING

修复后再次验证。
VERIFYING -> REVIEWING

所有自动验证通过。
REVIEWING -> HANDOFF

生成变更说明、风险说明、后续建议。
HANDOFF -> DONE

产物齐全。
任意状态 -> BLOCKED

缺权限、缺依赖、环境坏、需求冲突。

这类显式状态机很适合长任务，因为它把"当前到底在做什么"从聊天隐含状态变成系统状态。Anthropic 的长任务 harness 文章实际上就是在解决这种跨多阶段、多上下文窗口的协调问题。(Anthropic)

每个状态的标准产物

INTAKE：task_brief.json
PLANNING：plan.json
RESEARCHING：findings.md
IMPLEMENTING：diff_summary.md
VERIFYING：eval/results.json
REPAIRING：repair_log.md
REVIEWING：review_notes.md
HANDOFF：handoff.json

八、工具设计：按"省上下文"来设计，而不是按"像人类 IDE"来设计

Anthropic 对 tools 的建议很适合你直接照搬原则。(Anthropic)

建议的工具集合

检索类

search_code(query, scope, limit)
search_docs(query, source, limit)
find_symbol(name, file_hint)
list_changed_files(range)

规则：

默认返回摘要 + 指针，不回整份全文。

操作类

read_file(path, start, end)
write_patch(path, diff)
create_file(path, content)
move_file(src, dst)

规则：

优先 patch，不优先整文件重写。

执行类

run_shell(cmd, cwd, timeout, risk_tier)
run_tests(target, mode)
run_build(target)
run_lint(scope)
run_typecheck(scope)

规则：

stdout/stderr 自动摘要，长日志落盘。

交互验证类

open_page(route)
click(selector)
fill(selector, value)
screenshot(label)
assert_visible(text_or_selector)

规则：

让 Evaluator 真正"看见"前端。

Git 类

git_diff()
git_status()
git_commit_draft()

规则：

默认先生成 commit draft，不自动 push。

工具返回格式建议

json 复制代码

{
  "status": "ok|error|blocked",
  "summary": "一句话结论",
  "highlights": ["..."],
  "artifacts": [
    {"type": "log", "path": "..."},
    {"type": "screenshot", "path": "..."}
  ],
  "next_actions": ["..."]
}

这样能避免把海量原始输出灌进模型上下文，符合 Anthropic 的 token-efficient tool 原则。(Anthropic)

九、适合 vibe coding 的 workflow 模板

1. Feature Workflow

适合"做新功能"。

流程：

Intake
Planner 产出 scope
Researcher 查现有模块和接口
Builder 小步实现
Evaluator 跑 build + tests + browser
Handoff 生成说明

2. Bugfix Workflow

适合"修 bug"。

流程：

Intake
Researcher 定位复现路径
Evaluator 先复现失败
Builder 修复
Evaluator 回归
记录 regression case

3. Refactor Workflow

适合"重构而不变行为"。

流程：

Planner 定义不变条件
Evaluator 先生成 baseline
Builder 分阶段重构
Evaluator 对比行为和截图
Handoff 标记风险

4. Spike Workflow

适合"探索方案"。

流程：

Planner 定问题
Researcher 搜方案
Builder 做最小 PoC
Evaluator 只验可行性
输出决策文档，不直接合入主实现

这和 Anthropic 提倡的"简单、可组合模式优于复杂万能代理"一致。(Anthropic)

十、评测指标体系：这是你最该认真做的部分

Anthropic 的 eval 文章很值得你借鉴：eval 不只是看最终答对没有，而是要看 agent 在多轮工具使用和状态变化中的表现。(Anthropic)

A. Outcome 指标

最直观。

任务完成率
首轮完成率
自动完成率
人工介入率
最终验收通过率

B. Efficiency 指标

看成本。

平均 token 消耗
平均工具调用数
平均修复轮次
平均用时
上下文压缩次数

C. Reliability 指标

看稳定性。

重复错误率
幻觉修改率
无关文件改动率
失败后可恢复率
回归引入率

D. Quality 指标

看代码质量。

lint/typecheck 通过率
build 通过率
单测通过率
E2E 通过率
视觉一致率
架构约束符合率

E. Process 指标

看 harness 自身是否工作正常。

Planner 输出合格率
handoff artifact 完整率
hook 触发成功率
memory 命中率
工具失败后恢复成功率

F. Human Experience 指标

对 vibe coding 很重要。

用户补充澄清次数
用户手动纠偏次数
用户对变更解释满意度
用户接受 patch 比例

十一、你应该怎么做 eval 数据集

先别追求大，先做 30~50 个高质量真实任务集：

分类：

10 个 feature
10 个 bugfix
10 个 refactor
5 个 UI polish
5 个 infra / config

每个任务都要有：

输入目标
初始代码快照
done criteria
禁止事项
自动验证脚本
人工审查标准

Anthropic 强调 eval 的意义就在于：它能让行为变化可见，而不是靠印象判断"这版好像更聪明"。(Anthropic)

十二、适合你项目的默认策略

这是我建议你在第一版里直接写死的默认原则。

默认原则 1：先计划，再改代码

没有 plan.json 不允许 Builder 开写。

默认原则 2：每次改动必须有验证

最少跑：

lint
typecheck 或 build
与任务相关的测试

Anthropic 长任务文章里对"给 agent 测试工具"带来的提升讲得很明确。(Anthropic)

默认原则 3：每次失败都要留下结构化原因

不要把失败只留在聊天记录里。

默认原则 4：任何长输出都先摘要后入上下文

工具原始输出落文件，模型只看结论和指针。(Anthropic)

默认原则 5：改动范围最小化

防止 vibe coding 常见的"顺手重构半个项目"。

默认原则 6：默认不自动部署、不自动 push

高风险操作单独授权。

十三、一个你可以直接实现的 handoff 格式

json 复制代码

{
  "run_id": "2026-04-02-001",
  "task": "Add password reset flow",
  "status": "reviewing",
  "goal": "Implement password reset with email token flow",
  "done_criteria": [
    "User can request reset email",
    "Token validation works",
    "Password can be updated",
    "Tests pass"
  ],
  "completed": [
    "Added reset request endpoint",
    "Added token persistence",
    "Built reset UI page"
  ],
  "changed_files": [
    "src/api/auth/reset.ts",
    "src/pages/reset-password.tsx",
    "src/lib/token.ts"
  ],
  "verification": {
    "lint": "pass",
    "typecheck": "pass",
    "unit_tests": "pass",
    "e2e": "pending"
  },
  "open_risks": [
    "Email provider integration mocked only"
  ],
  "next_step": "Run browser E2E against reset flow"
}

这类结构化 handoff 正是长任务跨上下文继续成功的关键。(Anthropic)

十四、第一版 MVP 的建议范围

别一口气做全。第一版只做这 8 个东西：

Planner / Builder / Evaluator 三角色
4 层 memory
显式状态机
6 个基础 hooks
8 个核心工具
handoff artifact
30 个真实任务 eval 集
dashboard 展示成功率与失败原因

这已经足够把"纯 vibe coding"提升到"有组织的 agentic coding"。

十五、我对你的最终建议

你真正该做的，不是"一个更会输出代码的 agent"，而是"一个更会组织上下文、切任务、跑验证、留状态、做复盘的 harness"。这和 Anthropic 对 Claude Code 的公开表述高度一致：Claude Code 作为 harness，负责工具、上下文管理和执行环境；而扩展层则通过记忆、hooks、subagents、tools 等机制把模型能力变成稳定的工程能力。(Claude)

下一步最有价值的是：我直接继续给你输出一份可开工的 v1 技术设计文档 ，包括 memory.yaml、hooks.yaml、状态机定义、agent I/O schema，和一版 Python/TypeScript 的目录脚手架。

复刻 Claude Code 项目御马术缰绳系统 harness engineering 落地蓝图

一、先定目标：你的 harness 要解决什么

二、你的最小强版本架构

1. Intent 层

2. Memory 层

3. Agent 层

4. Tool 层

5. Orchestration 层

6. Eval 层

三、建议的目录结构

四、Memory 设计：这是你项目成功率最关键的一层

A. Constitution Memory

B. Project Memory

C. Topic Memory

D. Run Memory

Memory 加载策略

五、Agent 分工：不要做万能工，做装配线

1. Planner

2. Builder

3. Evaluator

4. Researcher

5. Refactorer

6. Release Guardian

六、Hook 点位：这是让系统"稳下来"的关键

你自己的最小 hooks 设计

1. SessionStart

2. UserPromptSubmit

3. PreToolUse

4. PostToolUse

5. PostToolUseFailure

6. TaskCompleted

7. PreCompact

8. SessionEnd

七、任务状态机：不要只靠聊天流推进

推荐状态

转移逻辑

每个状态的标准产物

八、工具设计：按"省上下文"来设计，而不是按"像人类 IDE"来设计

建议的工具集合

检索类

操作类

执行类

交互验证类

Git 类

工具返回格式建议

九、适合 vibe coding 的 workflow 模板

1. Feature Workflow

2. Bugfix Workflow

3. Refactor Workflow

4. Spike Workflow

十、评测指标体系：这是你最该认真做的部分

A. Outcome 指标

B. Efficiency 指标

C. Reliability 指标

D. Quality 指标

E. Process 指标

F. Human Experience 指标

十一、你应该怎么做 eval 数据集

十二、适合你项目的默认策略

默认原则 1：先计划，再改代码

默认原则 2：每次改动必须有验证

默认原则 3：每次失败都要留下结构化原因

默认原则 4：任何长输出都先摘要后入上下文

默认原则 5：改动范围最小化

默认原则 6：默认不自动部署、不自动 push

十三、一个你可以直接实现的 handoff 格式

十四、第一版 MVP 的建议范围

十五、我对你的最终建议