跳到主要内容
Harness Architecture

build-your-own-agent · 配套 Skill

§1 · 这个 Skill 是什么

Section titled “§1 · 这个 Skill 是什么”

本书的姐妹工程产物。把 22 章工程结论压成一个 Claude Code 或 Cursor 可直接 load skill 的 build-your-own-agent，干两件事：

  1. Build：从零搭一个生产级 agent harness；
  2. Diagnose & Optimize：审计或优化既有 agent，按 10 条铁律找问题、按 9 个 anti-pattern 给修复方案。

两条路径共享同一套词汇（10 铁律加 8 axes），底层指向 Codex、Claude Code、OpenClaw、Hermes 的源码级参考实现。

  • 1 个 SKILL.md 入口：进门读本，含 10 条铁律加 8 维度光谱表加 Build/Diagnose 双流程导航；
  • 9 个 reference 文档：按需加载，对应构建流程、诊断流程、选型、写代码、重构、安全、部署、面试、跨 skill 组合九大子任务；
  • 3 个可执行脚本：init-agent-project.py 标准初始化，lint-agent-design.py 静态 10 铁律检查 + progress advisory，diagnose-agent.py 运行时 9 个 anti-pattern 检测（读 rollout.jsonl）；
  • assets 模板 + assets/scaffold/ 单一来源：AGENTS.md.template、pyproject.toml.template、README.md.template、.gitignore.template、ci-lint-diagnose.yml.template 和生成项目源码模板，新项目从同一套模板落地。
build-your-own-agent/
├── SKILL.md                              # 入口：10 铁律 + Build/Diagnose 双流程
├── LICENSE.txt                           # MIT + 致谢
├── references/
│   ├── build-agent-workflow.md          # 5 阶段端到端 Build 流程
│   ├── diagnose-agent.md                # 4 个诊断流程 + AP 修复地图
│   ├── picking-from-spectrum.md         # 选型决策树（8 axes）
│   ├── agent-scaffold.md                # 标准 Python 脚手架
│   ├── migration-guide.md               # 10 阶段旧 agent 重构
│   ├── security-checklist.md            # 5 层安全防御栈
│   ├── production-deployment.md         # 7 阶段生产部署
│   ├── interview-prep.md                # 20 道高价值面试题
│   └── skill-interop.md                 # 与 mcp-builder / frontend-design 等组合
├── scripts/
│   ├── init-agent-project.py            # 新 agent 项目标准初始化
│   ├── lint-agent-design.py             # 10 铁律静态检查（text/json/--rules 子集）
│   └── diagnose-agent.py                # 9 个 anti-pattern 运行时检测
└── assets/
    ├── AGENTS.md.template               # 新 agent 项目架构文档骨架
    ├── pyproject.toml.template          # 依赖加 ruff/pytest/mypy 配置
    ├── README.md.template               # 项目说明骨架
    ├── .gitignore.template              # 运行时/缓存/secret 排除
    ├── ci-lint-diagnose.yml.template    # GitHub Actions 流水线
    └── scaffold/                        # 生成项目源码单一来源

§2 · 安装方法

Section titled “§2 · 安装方法”

skill 已随仓库一起开源。两种安装方式：

选 A · Claude Code（推荐）

Section titled “选 A · Claude Code（推荐）”
Terminal window
git clone https://github.com/veithly/build-your-own-agent.git ~/.claude/skills/build-your-own-agent
# 重启 Claude Code 后即可在 skill 选择器看到

选 B · 项目内嵌

Section titled “选 B · 项目内嵌”
Terminal window
git clone https://github.com/veithly/build-your-own-agent.git ./skills/build-your-own-agent
# 在 AGENTS.md / CLAUDE.md 里声明：
# "When designing an agent, load skill at ./skills/build-your-own-agent/SKILL.md."

§3 · 一句话调用模式

Section titled “§3 · 一句话调用模式”

skill 按需加载，不污染上下文。日常用法分 Build 和 Diagnose 两条主线：

维度 你的提示加载内容产出何时用
想做 coding agent "我要做 Codex 那种带 sandbox 的 coding agent"SKILL.md + build-agent-workflow.md + agent-scaffold.md5 阶段 Build 流程 + 初始化脚本 + 标准 Python scaffold + 每步源码参考从 0 起步
架构选型卡住了 "loop 用 Codex 的 rollout 还是 Claude Code 的 7 transitions"SKILL.md + picking-from-spectrum.md8 axes 决策树 + 三个 worked example 对照Phase 1 决策中
任务进度面选型 "todo list 用 Codex update_plan 还是 Claude Code TodoWrite"SKILL.md + picking-from-spectrum.md第 8 轴：approval plan / execution todo / durable task 分层建议设计运行时进度面
执行状态面路由 "tool progress、todo、away summary 应该分别显示到哪里"SKILL.md + picking-from-spectrum.md + docs-site §22execution state router：source / audience / lifetime / context policy设计多层进度面
已有 agent 要诊断 "我的 agent 慢 / 贵 / 漏 / loop / 不安全"SKILL.md + diagnose-agent.md + scripts/diagnose-agent.py4 个诊断流程 + 9 个 anti-pattern → 最佳修复地图生产出问题时
已有 agent 要升级 "lint 失败 8/10，怎么渐进式重构"SKILL.md + migration-guide.md10 阶段重构计划，每阶段 1-3 天，每条铁律对应一个阶段已上线 1 年的旧 agent
上线前 review "下周上线，最后一道关卡"security-checklist.md + production-deployment.md + lint + diagnose5 层安全栈 + 7 阶段部署 + 双脚本作 CI gate上线前 3 天
面试准备 "面试 agent infra 岗，重点考什么"SKILL.md + interview-prep.md20 道高频题 + 章节定位 + 三段式答题面试前 1 周
按 sub-task 加载，平均一次只看 SKILL.md + 1-2 个 reference。Build 和 Diagnose 两条主线，加载分明。

§3.1 · 一行命令：CI / 本地巡检

Section titled “§3.1 · 一行命令：CI / 本地巡检”
Terminal window
# 标准初始化新 agent 项目
python ~/.claude/skills/build-your-own-agent/scripts/init-agent-project.py ./my-agent \
    --profile coding-cli \
    --test-cmd "python -m pytest -ra"


# 静态 lint 10 铁律（适合 CI gate）
python ~/.claude/skills/build-your-own-agent/scripts/lint-agent-design.py /path/to/agent
python ~/.claude/skills/build-your-own-agent/scripts/lint-agent-design.py /path/to/agent --format json


# 运行时 9 个 anti-pattern 检测（适合每周巡检）
python ~/.claude/skills/build-your-own-agent/scripts/diagnose-agent.py /path/to/rollouts/ --allow-empty
python ~/.claude/skills/build-your-own-agent/scripts/diagnose-agent.py /path/to/rollouts/ \
    --metrics /path/to/metrics.jsonl \
    --agent-src /path/to/agent \
    --format json

退出码 0 表示通过，1 表示有 finding。JSON 格式稳定，可直接喂 GitHub Actions / Jenkins / GitLab CI。assets/ci-lint-diagnose.yml.template 是一个开箱即用的 CI 流水线骨架。

§4 · 10 条铁律一览

Section titled “§4 · 10 条铁律一览”

这 10 条是 skill 的核心。摘自全书 4 系统对比，4 家全部遵守才进表。

10 Iron Laws of Agent Harness

  1. Turn is the source of truth
    一切落盘、重试、回滚都发生在 turn 边界。Day 1 定义清楚 turn，永远不破。
  2. Context has a cache boundary
    Layer 1-N 冻结、Layer N+1 每轮重算。memory snapshot 在上面，timestamp 在下面。
  3. Prompt is data, never instructions
    外部内容（web fetch、email、tool output）一律 <external_content_{nonce}> 包起来。攻击者伪造不了 nonce。
  4. Three verifier tiers always
    Hard（外部 exit code）+ Soft（token budget）+ Give-up（model self-stop）。生产至少要前两层。
  5. Sandbox first, then trust
    OS-level sandbox 是运行时防御的硬边界。LLM-layer trust 是补充。默认 network=deny + fs_write=restricted。
  6. Redact at import time, not at log time
    redact 配置 import 时快照定下来。否则 LLM 中途 `export FOO=` 可绕过。
  7. fail_open beats fail_closed at default
    默认严格 → 用户禁掉所有 safety。默认 fail_open，让生产显式 opt-in fail_closed。
  8. Memory writes need a frozen snapshot
    memory 入 prompt 时是 turn-start 时的 freeze，不是 live ref。否则缓存失效 + 中途 mutation。
  9. Skills are content, but loadable code is supply chain
    内置 allowlist + scanner + 签名是生产底线。用户安装的 skill 要 4 阶 × 3 信任矩阵。
  10. Audit trail is the last mile
    rollout.jsonl / trajectory / SecurityAuditReport。没有这个，出事查不到。

每条都对应一章详尽案例。想知道 Codex、Claude Code、OpenClaw、Hermes 具体怎么落地这条规则，去对应章节的 §11 面试题段落。

§5 · 与本书的对照

Section titled “§5 · 与本书的对照”

skill 不替代本书。是读完本书后随手能用的工具箱。两者关系：

本书 22 章 (深度 + 案例 + 对比)
   │
   ├─ 提炼 10 铁律 ───────────► SKILL.md (入口)
   ├─ 整理 8 axes 光谱 ───────► picking-from-spectrum.md
   ├─ 抽出 220 道题 top 20 ───► interview-prep.md
   └─ 工程结论沉淀 ─────────► scaffold / migration / security / production

读 skill 时某条铁律觉得没说透，跳回本书对应章。写 agent 时记不清「Codex 那条转换怎么写」，让 skill 替你找出处。

§6 · 路线图

Section titled “§6 · 路线图”

skill 跟本书同步更新。如果新增 reference 或修改规则，会在仓库 CHANGELOG.md 中记录。欢迎在 issues 里贡献：

  • 你做了一个 agent，哪些铁律实际遇到坑、怎么调；
  • 哪些 use case 没在第 5 节的对照表里；
  • 某条 reference 文档跑你的真实项目时漏了什么。

Codex 标签只是颜色复用。这些路径都在本仓库 skills/ 下，仓库公开后即可直链。