English · 한국어 · 中文 · 日本語

forge-harness (FH)

FH 是面向 Claude Code 的元框架（meta-harness）：它帮你搭建框架（harness）和技能——一个项目所需的规则、门禁与记忆——并在发布之前检查它们。

框架（harness） 是你在某个项目里套在 AI agent 外面的那一层，让它不必每次会话都重新听一遍同样的指示： 它遵循的规则、拦住错误改动的检查，以及它学到了什么的记录。元框架则是那个一个项目接一个项目地搭建并验证这些框架的框架。

别再一遍遍向 agent 解释规则——把它们放进项目里。

适合谁，你能得到什么

适合在真实项目里使用 Claude Code（或其他编码 agent），厌倦了重复同样的话、或者发现改动有误时已经太晚的人。你会得到三样东西：

门禁拦的不只是 agent，也包括你自己的错误：2026-08-22 这一天，门禁拦住了FH 的作者七次，其中没有一次是作者自己先发现的（门禁拦截的一天）。

_{录自守卫的一次真实运行（不是示意图；重新生成它的脚本链接在下面）：一个 agent “整理”了技能规格文件（SKILL.md），删掉了其中的 Done When（完成条件）一节。守卫 BLOCK，并点名缺失的那一节；把它放回去就返回 PASS，其余整理照常发布。
重新生成：brew install vhs && vhs docs/demo/gate-block.tape}

快速开始

选一扇门。它们的安装方式不同，得到的东西也不同。

门 ① —— 只要门禁。无需克隆，无需插件，无需 Claude Code 会话。

cd your-repo && npx --package @chrono-meta/fh-gate fh-gate     # 审查当前仓库的 git diff

它通过 git diff 找到你改动的文件，发给审查后端，并输出判定（FH_GATE_VERDICT: PASS | PENDING | BLOCKED | ESCALATE）和退出码。只有审查真的跑过，PASS 才算数：后端始终没有应答、dry run、或者出现未知退出码，都不是 PASS，而 GitHub Actions 步骤默认会因此失败。需要 Node ≥ 16，以及安装并登录好的一个后端 CLI：claude（默认）或 codex（FH_BACKEND=codex）。可用于 CI、pre-commit 钩子，或放在另一个 agent 旁边。也有 GitHub Actions 步骤和 Homebrew tap——见运行门禁。

门 ② —— 在 Claude Code 里使用整套框架。

claude plugin marketplace add https://github.com/chrono-meta/forge-harness.git
claude plugin install -s user fh-meta@forge-harness
git clone https://github.com/chrono-meta/forge-harness.git ~/projects/forge-harness
cd ~/projects/forge-harness && claude          # 然后输入：hi   （或 안녕 · こんにちは · 你好）

1. 在 Claude Code 中打开克隆下来的文件夹（即 cd … && claude 那一行）。

2. 打个招呼。 在全新克隆里，FH 会读取检出内容，发现没有任何会话文件，于是打开一个面向新用户的简短菜单：创建你的第一个项目 · 关联已有项目 · 阅读指南。如果安装向导还没运行，它也会告诉你。

   

3. 在同一次会话里拿到一次收获。 说 “关联一个项目”（FH 会扫描 ../ 下的 git 仓库并创建 tracks/{project}/），然后说 “加速这个项目”（按优先级排序、需批准的计划）或 “运行 /context-doctor”（token 浪费扫描）。完整设置请运行 /install-wizard：每一项都逐个批准，拒绝的也会被记录。

要求。 门 ② 需要 Claude Code CLI（claude --version）。门 ① 需要 Node 和 claude 或 codex CLI，不需要 Claude Code 会话。FH 自己的某个门禁（克隆里的测试套件）另外需要 Python + PyYAML（python3 -m pip install --user pyyaml），缺少时会 fail-closed 拒绝通过。 不确定选哪扇门？ 从 ① 开始：一条命令，不需要全局安装。门 ② 是更大的安装，同时也带有 fh-gate CLI（CHEATSHEET.md）；你在 ① 里学到的东西一点也不会浪费。

只装插件（不克隆）也能用，但不完整：你会得到技能和 agent，得不到 CLAUDE.md 的治理规则或 tracks/ 记忆。第一次使用的韩文逐步指引：docs/USER_GUIDE.md。

一张图看懂它如何运作

这是设计上的流程。哪些步骤由代码强制、哪些由被告知要遵守的 AI 规则承担，见下方“能做与不能做”表和 docs/map/FH_MAP.md。

flowchart TD
    A["你说出想要什么<br/>（日常语言）"] --> B["FH 读取意图"] --> C["把它锻造成两种形态之一"]
    C --> R1["AI 遵循的规则<br/>（CLAUDE.md、技能）"]
    C --> R2["不需要 AI 的代码<br/>（钩子、门禁、脚本）"]
    R1 --> S1
    R2 --> S1
    subgraph G["对框架的每一次改动都要经过"]
        direction TB
        S1["1. 设计之前，先写下“什么算成功 / 它绝不做什么”"] --> S2["2. 从几个相互独立的角度去试<br/>（另一个模型家族、另一个仓库的视角）"] --> S3["3. 一直攻击，直到剩下的是站得住的——然后再发布"]
    end

如果图没有显示：你说出想要什么 → FH 读取意图 → 锻造成 AI 遵循的规则或不需要 AI 的代码 →（每一次改动）1. 先写下成败定义和绝不做的事 → 2. 从几个独立的角度去试 → 3. 一直攻击到站得住，然后再发布。

• 不可逆的步骤（发布 · 删除 · 重写历史）会停下来问人
• 检查没能测量的东西，报告为“未测量”——绝不报告成 0
• 每次会话学到的东西写进 tracks/ → 下一次会话从那里开始

枢纽（本仓库）保存共享的 knowledge/ 和每个项目各自的 tracks/；你关联的每个项目都指回它。完整地图，每个节点都是真实路径：docs/map/FH_MAP.md（交互版：chrono-meta.github.io/forge-harness）。

三个信念

1. 质量是杠杆，速度是结果。 工作假设：经过一次冷眼审视的工作，之后需要的返工更少。本页没有对它做基准测试。
2. 作者是最差的审查者。 和 AI 一起做完之后，你就成了它的辩护人，所以真正算数的检查，是由从未见过你的推理过程的审查者做的——docs/WHY.md。
3. 在不可逆的边界上放机器；判断保持开放。 在无法撤销的地方拦住，并承认你没有测量的东西——docs/ETHOS.md。

能做与不能做

证据，以及它薄弱的地方

• 一份真实的第三方 diff（2026-05-31）。 对 OpenCode 中 AI 所写的 permission/arity.ts（163 行，CI 全绿）运行 fh-gate：判定 BLOCKED，依据是 CI 漏掉的两个 A 级发现。
• 埋洞测试，模型固定（2026-07-14）。 另外两个模型写下的八个 fail-open 漏洞。普通审查 5/8（其中 2 个找错了 bug）· + FH 的 degrade-direction 视角 6/8 · + 第二个模型家族 8/8，误报 0。单次抽样，样本很小。 要点是两次单模型运行漏掉了同样的两个漏洞。方法见 ship_readiness_gate.md；更多运行见 docs/OUTPUT_EVIDENCE.md。
• 成熟度是评级，不是宣称。 下面列出的五重身份在 ship_readiness_gate.md 中带有注明日期的等级；依赖其中任何一个之前，先读它的等级。
• 本页的数字（46 个技能 · 14 个 agent）是 plugins/（fh-meta、fh-commons、fh-qp、fh-preprep）下的技能文件夹和 agent 文件，统计于 2026-10-10。用语手册：CHEATSHEET.md §12。

用起来之后会遇到的词

开始时用不到这些。它们说明 FH 是怎么搭起来的，当问候或某个门禁用到其中一个时再来查。这里的定义只有一句话；正典是 fh_three_layer_canon.md。

其他术语：GLOSSARY.md。

接下来读什么

这份文档是写给人看的。 如果它对你有用，点个 star 能帮助更多人找到它。