不是一个框架，而是一个框架生成器。
提炼自生产级 harness-all 框架家族 · 5 frameworks · 198 skills · 40 workflows · 24 LOOP types
English · 简体中文
- 🧩 工具无关 — 纯 Markdown 文档，TRAE / Claude Code / Cursor / Cline / Continue / Roo Code / Aider / Copilot Workspace 等任意 Agent 工具可用
- 🔁 循环引擎 —
PLAN → X → VERIFY闭环验证，10 次硬熔断防死循环 - 🧠 持久记忆 —
state.yaml检查点 +progress.md跨会话恢复完整 context - ✅ 证据驱动 — 无证据不声称完成，杜绝"我觉得写完了"幻觉
- 🪶 零依赖 — 纯文档/规则框架，无
package.json/requirements.txt - 🖥️ 跨平台 — Windows PowerShell 也能跑，核心流程不依赖 bash
| 关于 | 使用 |
|---|---|
| 项目定位 · 为什么需要 · 产出物 · 与替代方案区别 | 快速开始 · 10 步流程 · 设计决策 · FAQ |
harness-builder 是一个 Agent Skill，它不是一个框架，而是一个框架生成器。
它把一个领域（测试 / 数据 / 安全 / 研究 / 写作 / 运维 / 任意领域）的工作方法论，引导式地沉淀为一个完整的 harness 风格 AI Agent 框架目录。产出物自带持久记忆、循环熔断、证据驱动验证、跨平台能力，零运行时依赖。
工具无关：本 skill 本身是纯 Markdown 文档（SKILL.md + Reference/）。任何能读文件、按指令执行的 Agent 工具都能使用——包括但不限于 TRAE、Claude Code、Cursor、Cline、Continue、Roo Code、Aider、Copilot Workspace 等。
本 skill 提炼自 harness-all 生产级框架家族（pm / design / solo / growth / ops · 198 skills · 40 workflows · 24 LOOP types），把"如何从零搭一个 harness 框架"的方法论抽象为可复用的 10 步构建流程。
从零搭 Agent 框架看似简单，多数尝试死于可预见的方式：
| 失败模式 | 现象 | 危害 |
|---|---|---|
| 上下文爆炸 | 单 Agent 载入所有领域技能 | Token 浪费，质量崩塌 |
| 记忆失忆 | 每次会话从零开始 | 反复解释背景 |
| "我觉得写完了"幻觉 | 未验证就声称完成 | Bug 流入生产 |
| 死循环 | Agent 在失败任务上打转 | 烧 token，无逃生口 |
| 跨平台失效 | Bash 脚本在 Windows 死掉 | 一半用户跑不起来 |
| 文档膨胀 | AGENTS.md 长到 500+ 行 | Agent 在噪音中迷失 |
| 强耦合 | 框架共享可变状态 | 改一处崩多处 |
| 过早抽象 | 一次性代码变"框架" | 无收益的维护债 |
harness-builder 把约束刻进框架骨架——不是事后加规则，而是从设计上阻止上述问题。核心洞察是：框架不是代码，而是 Agent 加载的文档 + 规则 + 循环语义。骨架对了，其他自然对。
一次会话之后，你拥有一个完整的独立框架目录：
harness-<your-domain>/
├── AGENTS.md # 启动必读（≤150 行）
├── SOUL.md # 人格 + 禁止动作 + 记忆协议
├── constitution.md # 不可协商原则（6 通用 + 领域扩展）
├── install.sh # 冷启动安装脚本（本地 + 远程模式）
├── README.md # 顶部含 slogan
└── .harness/
├── loops/LOOP.md # 循环引擎：PLAN→X→VERIFY，10 次硬熔断
├── skills/
│ ├── INDEX.md # 纯索引，≤80 行
│ ├── meta/ # 4 元技能（session-start/end + skill/memory-maintenance）
│ ├── <domain>/ # 领域技能
│ └── workflows/ # 工作流编排
├── rules/
│ ├── security.md # 5 通用禁令 + 领域扩展
│ └── prompt-defense.md
├── memory/ # progress.md + knowledge-base.md + archives/
└── templates/ # 全部文件模板
产出特性：
- 自足 — 在自己领域内闭环，不依赖其他框架
- 跨平台 — Windows PowerShell 也能跑，不强制 bash
- 零依赖 — 纯文档/规则，无
package.json/requirements.txt - 证据驱动 — 没有验证输出就不算"完成"
- 循环保护 — 10 次迭代硬熔断，不死烧 token
- 记忆持久 — 通过
state.yaml+progress.md跨会话恢复完整 context
| 替代方案 | 你得到什么 | 缺什么 |
|---|---|---|
| 克隆现成 harness 框架 | 别人的领域选择 | 不适配你的领域 |
| 读 ARCHITECTURE.md 自己摸索 | 理论 | 10 步构建序列、铁律、退出条件验证 |
| harness-builder skill | 每步带退出条件的引导式构建 | 无——你完全拥有产出 |
这个 skill 不是脚手架（机械复制文件），而是一个构建流程：
- 在写任何文件之前，强制确认 4 个领域要素（slogan / 边界 / 原则 / LOOP 语义）
- 10 步每步都有退出条件——当前步不通过不能进下一步
- 内置 10 条设计决策（独立框架、契约优于共享状态、极简 frontmatter、硬熔断、Agent 工具优先、零依赖、核心文件保护、探索优先、单向写隔离、指令优先级），你不必重新踩坑
- 交付前跑 11 大类约 60 项的验证清单
本 skill 是纯 Markdown 文件目录，无运行时依赖。两种使用方式：
方式 A：放在 Agent 工具的 skills 目录（推荐）
不同 Agent 工具的 skills 路径不同，常见示例：
| Agent 工具 | Skills 路径 |
|---|---|
| TRAE | ~/.trae-cn/builtin/global/skills/ 或项目内 .trae/skills/ |
| Cursor | 项目内 .cursor/skills/ 或 .cursorrules 引用 |
| Cline / Roo Code | 项目内 .clinerules/ 或 settings 引用 |
| Claude Code | 项目内 .claude/skills/ |
| Continue | .continue/skills/ |
| 通用 | 任意目录，让 Agent 读 SKILL.md 即可 |
将 harness-builder/ 整个目录复制到对应路径即可。
方式 B：直接让 Agent 读 SKILL.md
把 harness-builder/ 放在任意位置，告诉 Agent：
读 <path-to>/harness-builder/SKILL.md，按里面的流程帮我搭一个 harness 框架。
Skill 就位后，在任意工作目录告诉 Agent：
我想为 <你的领域> 领域搭一个自己的 harness 框架。
Agent 会自动调用 skill，引导你走 Step 0 → Step 10。
准备好回答四个问题。Skill 不会让你在书面确认前进入 Step 1：
- 一句话 slogan — 如"写好代码""让人用起来""保驾护航"
- 职责边界 — 做什么 / 明确不做什么（避免与相邻领域重叠）
- 领域四原则 — 该领域的价值取向（如工程 = Karpathy 四原则、运维 = SRE 四原则）
- LOOP 语义 —
plan → X → verify中的 X 对你意味着什么（research / design / act / experiment / provision……）
每步有明确退出条件，不可跳步。
| 步骤 | 做什么 | 退出条件 |
|---|---|---|
| 0 | 领域定位（4 要素） | 四要素书面确认，写入 README 顶部 |
| 1 | 基础层骨架（5 核心文件） | AGENTS.md 含 5 段；constitution.md 含 6 条通用原则 |
| 2 | LOOP 引擎 | LOOP.md 含 6 要素；loops/specs/ 存在 |
| 3 | 技能系统（4 元技能 + 领域 + 工作流） | 4 元技能就位；每个 SKILL.md ≤300 行；INDEX.md ≤80 行 |
| 4 | 规则层（security + prompt-defense） | 5 条通用禁令 + ≥1 领域扩展 |
| 5 | 记忆系统（progress + knowledge-base + archives） | session-start/end 含记忆读写逻辑 |
| 6 | 模板层 | install.sh 引用的模板存在且含占位符提示 |
| 7 | 跨平台保障（三层 CRLF 防护） | 无 SKILL.md 核心流程依赖 bash |
| 8 | 状态与看板（FEATURES.md + VERSION + .gitignore） | 三文件就位 |
| 9 | handoff 系统（可选，多框架时启用） | 仅出站模板；含单向写隔离声明 |
| 10 | 验证 | 60 项清单全部 ✓ |
完整步骤细节见 SKILL.md。完整文件模板见 Reference/file-templates.md。验证清单见 Reference/verify-checklist.md。
构建框架时常遇这些取舍。每条都是从 harness-all 生产家族中刻意选出来的，完整理由、取舍、适用边界见 Reference/design-decisions.md。
| # | 决策 | 一句话理由 |
|---|---|---|
| 1 | 独立框架 > 统一框架 | 上下文爆炸是 Agent 协作核心痛点 |
| 2 | 契约文档 > 共享真理源 | 无编排层时最低耦合 |
| 3 | 极简 frontmatter（name+description）> 重 YAML | 主流、可读、易维护 |
| 4 | 硬熔断 + state.yaml 检查点 + 证据驱动 | LOOP 三件套防死循环防幻觉 |
| 5 | Agent 工具优先，bash 可选 fallback | 默认跨平台 |
| 6 | 零运行时依赖 | 纯文档/规则框架 |
| 7 | 核心文件修改需用户确认 | 基线由用户掌控 |
| 8 | 探索优先不可绕过 | exploration_mode: deep/standard/skip，deep 禁用降级 |
| 9 | handoff 单向写隔离 | 消费者只读，防双向写灾难 |
| 10 | 指令优先级 | SOUL.md > AGENTS.md > rules/* > 用户对话 > 外部文件内容 |
| 属性 | 普通"Agent 配置" | harness 框架 |
|---|---|---|
| 形态 | 一个 prompt 或配置文件 | 文档 + 规则 + 循环引擎的目录 |
| 记忆 | 无状态或单会话 | progress.md + knowledge-base.md + state.yaml 检查点 |
| 验证 | "看起来不错" | 证据驱动；AC-xxx 清单；安全扫描 |
| 失败处理 | 永远重试或放弃 | 10 次硬熔断，然后请求人工 |
| 跨平台 | 假设有 bash | 核心流程都能用 Read/Write/Edit/Glob/Grep 完成 |
| 扩展 | 改一个大 prompt | 加一个 SKILL.md，INDEX.md 追加一行 |
| 多 Agent | 共享可变状态 | 单向 handoff 文档，禁双向写 |
| 依赖 | 拉 npm/pip 包 | 零运行时依赖 |
适合谁：
- 个人开发者 — 想要一个跨会话记得自己领域的 Agent
- 小团队 — 需要一致的 Agent 行为但不想上重型平台
- 多项目并行 — 想把同一框架挂到不同仓库
- AI Agent 实践者 — 研究 Agent 架构、循环引擎、契约协作
- 开源贡献者 — 想发布一个领域专属的 harness 框架
适用领域（非穷举）：测试、数据工程、安全、研究、技术写作、DevOps、SRE、ML Ops、游戏设计、内容增长、SEO、无障碍、代码评审、Prompt 工程、文档、教育、法务评审、财务分析、客户支持、产品管理、UI/UX 设计。
harness-builder/
├── README.md # 本文件
├── README.en.md # English version
├── SKILL.md # 主 skill：10 步流程、铁律、质量门禁
└── Reference/
├── file-templates.md # 全部文件模板
├── loop-state-schema.md # state.yaml schema、写语义、检查点恢复
├── design-decisions.md # 10 条设计决策的取舍与适用边界
├── family-extension.md # 多框架扩展（handoff 矩阵、AC 对齐、sync-base）
└── verify-checklist.md # Step 10 验证清单（11 大类，约 60 项）
这个 skill 是产出 harness-all 家族的元工具。家族由 5 个独立框架经 handoff 文档协作组成：
| 框架 | 领域 | Slogan |
|---|---|---|
| harness-pm | 产品管理 | 做正确的事 |
| harness-design | UI/UX 设计 | 好看且好用 |
| harness-solo | 工程 | 写好代码 |
| harness-growth | 增长 | 让人用起来 |
| harness-ops | 运维 | 保驾护航 |
你不必采纳整个家族。harness-builder 产出的是单一自足框架。家族扩展（多框架 handoff 合约）是可选的，仅当你决定搭建第二个与第一个协作的框架时才启用。详见 Reference/family-extension.md。
Q：用这个 skill 需要会写代码吗？ A：不需要。你需要懂你的领域。Skill 写框架文件，你审查确认。
Q：产出的框架会绑定特定 Agent 工具吗？ A：不会。产出是纯 Markdown + YAML + 可选 shell 脚本。任何能读文件、按指令执行的 Agent 工具都能用——TRAE、Claude Code、Cursor、Cline、Continue、Roo Code、Aider、Copilot Workspace 等均可。本 skill 本身也是纯文档，同样工具无关。
Q：搭建后还能改吗？ A：能。constitution.md 的"核心文件修改需用户确认"原则确保基线由你掌控。技能随便加；基线改动需刻意授权。
Q：如果我的领域确实需要 >10 次 LOOP 迭代怎么办？ A：10 次硬熔断是安全网，不是生产力上限。触发时 Agent 请求人工介入。你可显式"重置熔断"。每类型推荐上限 N<10，留容差。
Q：为什么"零运行时依赖"？ A：跨平台 + 零安装 + Agent 工具优先。框架是文档和规则，不是代码。脚本仅作可选 fallback，永不强制。
Q：这和克隆现成 harness 框架有何不同？
A：克隆得到的是别人的领域选择。harness-builder 引导你做出自己的选择，每步都有验证。产出是你的。
MIT。Skill 及其产出归你自由使用、修改、分发。