MoAI-ADK 实现了 挽具工程 (Harness Engineering) 范式。开发者不再直接编写代码，而是设计一个让 AI 智能体能够产出最优代码的环境（挽具）。

“Human steers, agents execute.” — 工程师的角色从编写代码转向设计挽具：SPEC、质量门禁、反馈循环。

传统的氛围编程 (Vibe Coding) 让 AI 自由生成代码，然后人工审查结果。挽具工程恰恰相反 — 用规格 (SPEC)、自动验证、持续反馈循环引导 AI 智能体，产出质量稳定一致的代码。

那么挽具究竟是什么？它是围绕基础模型、编排其执行的整个系统 — 决定模型如何思考与规划、如何调用工具、如何感知和管理上下文、产物存放在哪里、结果如何评估的那一层。MoAI-ADK 正是架在 Claude Code 之上的这套挽具。

挽具工程是 v3.0 三大核心交汇的地方。

其中第二个核心是关键创新。AI 递归式自我改进 (RSI) 的现实短期路径不是直接修改模型权重，而是改进围绕模型的挽具。MoAI-ADK 走的正是这条路 — 递归改进的不是模型，而是挽具（技能·智能体指令）。

graph TD
    subgraph Harness["挽具工程"]
        direction TB
        SF["Scaffolding First
生成空文件桩"] --> FC["Failing Checklist
注册验收标准任务"]
        FC --> SV["Self-Verify Loop
代码→测试→修复→通过"]
        SV --> GC["Garbage Collection
清除死代码"]
        GC --> CM["Context Map
维护架构文档"]
        CM --> SP["Session Persistence
跨会话进度追踪"]
        SP --> LA["Language-Agnostic
16 种语言自动检测"]
        LA --> SF
    end

    style Harness fill:#f0f7ff,stroke:#1565C0

每个组件都映射到 MoAI 的特定命令：

/moai run 启动后，智能体在编写代码之前先创建所需的文件结构：

src/
├── auth/
│   ├── handler.go      ← 空桩
│   ├── handler_test.go  ← 空测试
│   ├── service.go       ← 空桩
│   └── service_test.go  ← 空测试
└── middleware/
    └── jwt.go           ← 空桩

这种方式防止智能体无序地创建文件，保持项目结构一致。

SPEC 的验收标准会自动注册到任务列表中：

- [ ] JWT 令牌生成端点
- [ ] 令牌校验中间件
- [ ] 刷新令牌逻辑
- [ ] 过期令牌处理
- [ ] 85%+ 测试覆盖率

每一项在实现并通过测试后被勾选。所有条目全部勾选，工作才算完成。

智能体自主执行的核心循环：

graph TD
    A["编写代码"] --> B["运行测试"]
    B --> C{"通过？"}
    C -->|"失败"| D["分析错误"]
    D --> A
    C -->|"通过"| E["下一项"]

该循环在 /moai loop 中最多重复 100 次，并包含收敛检测（同一错误重复出现时切换替代策略）。如果想直接声明完成条件，可使用 goal 引擎（/moai goal "<条件>"）— 会话会自主工作，直到条件满足或达到轮次上限。

/moai codemaps 生成的架构文档为智能体提供代码库的整体结构。借助它，智能体可以：

• 选择不与现有代码冲突的实现方式
• 遵循恰当的模式与规范
• 理解依赖关系并把握影响范围

即使 Claude Code 会话中断，progress.md 也会记录已完成的步骤：

## Progress
- [x] Phase 1: 分析完成
- [x] Phase 2: 处理器实现
- [ ] Phase 3: 编写测试 ← 从这里恢复
- [ ] Phase 4: 重构

用 /moai run --resume SPEC-XXX 即可从中断点自动恢复。

挽具不是固定不变的环境。循环转得越多，观察积累越多，挽具依据这些观察进行学习，自行改进指令。

运行循环 → 积累观察 → 学习模式 → 演化指令（批准门禁）

自动演化绝不会在没有人类监督的封闭循环中运转。评估者与权限控制被放在演化循环的外部：

• 5 层安全流水线 — 通过快照与回滚（moai harness rollback）可随时恢复
• 用户批准门禁 — Tier-4 自动更新必须经过用户批准
• Constitution 系统 — 不变规则 (FROZEN) 被排除在演化对象之外（参见 Constitution 系统）

moai harness status      # 查看学习状态（观察数、模式、提案）
moai harness apply       # 应用提案（需通过用户批准门禁）
moai harness rollback    # 回退上一次应用
moai harness disable     # 停用学习

修改指令本身也是一次实验。编辑规则、智能体、钩子等挽具组件时，适用决策可观测性：每次编辑都记录一条可证伪的预测（哪一类失败将不再复发），并且在采纳前必须通过双重检查——held-in（该编辑确实捕获了引发它的失败）与 held-out（现有防护与测试仍然通过）。被否决的编辑也会留档，避免重复同一次失败的尝试。

当你亲自创建自定义技能或智能体时，需要了解 moai update 会覆盖 (overwrite) 哪些资产、保留 (preserve) 哪些资产。MoAI-ADK 将命名空间明确划分为 “通用分发 (template-managed)” 与 “用户创建 (user-owned)”。

moai-* 前缀技能与 moai-harness-* 是 MoAI-ADK 包提供的通用资产。它们分发到所有用户项目，执行 moai update 时会被最新 template 覆盖。因此直接修改这些资产，改动会在下次更新时丢失。

hns-* 前缀技能（Harness v4 Builder 生成的正式命名空间）与 .claude/agents/harness/ 目录归用户项目所有。上一代前缀 harness-* / my-harness-* 也同样被识别。moai update 绝不删除或修改它们，更新前先备份并原样保留。

要让自己创建的领域特化技能或智能体在 moai update 后依然存活，务必使用 hns-* 前缀（智能体放在 .claude/agents/harness/）。若以 moai-* 或 moai-harness-* 前缀创建，会被视为 template-managed，在下次更新时被覆盖。通过 /moai harness "自然语言请求" 创建挽具时，Builder 会自动分配符合此规则的名称。

• 基于 SPEC 的开发 — 编写作为挽具输入的 SPEC 文档
• TRUST 5 质量 — 挽具所验证的 5 项质量标准
• Constitution 系统 — 管控挽具演化的不变规则