# Harness Engineering in AI Coding 研究总结

> 探索在 AI 编程中的 Harness Engineering，确保 AI 编程可约束、可评估、可追溯
>
> 归档：2026-04-24

---

## 📊 项目概览

| 属性 | 值 |
|------|---|
| **仓库** | [2361485765/harness-engineering-in-ai-coding](https://github.com/2361485765/harness-engineering-in-ai-coding) |
| **语言** | Shell |
| **创建时间** | 2026-04-23（极新项目） |
| **License** | MIT |
| **定位** | AI 编程约束框架（Harness Engineering） |

---

## 🎯 核心理念

**Harness Engineering** = 在 AI 编程工具（Claude Code/Cursor/Copilot）之上，构建一套完整的**约束框架**，覆盖软件研发全生命周期。

### 四大目标

| 目标 | 说明 | 手段 |
|------|------|------|
| **可约束** | AI 输出符合团队规范 | Skill 体系 + 上下文注入 |
| **可评估** | 产物质量可度量 | 质量门禁 + 评估机制 |
| **可追溯** | 过程透明可审计 | 记录 + 日志 + Hook |
| **可扩展** | 持续扩展能力边界 | 可插拔 Skill 体系 |

---

## 🏗️ 架构设计

```
需求 → 技术方案 → 编码 → 研发自测 → QA 测试
 ↑        ↑         ↑        ↑         ↑
 └────────┴─────────┴────────┴─────────┘
              Harness（约束·评估·追溯）
                    ↕
            可插拔 Skill 体系
```

### 五大研发阶段

| 阶段 | 目录 | 核心能力 |
|------|------|---------|
| **01 需求引入** | 01-requirements/ | brainstorming + openspec 管理 |
| **02 技术方案** | 02-technical-design/ | harness-init 扫描项目 + 设计生成 |
| **03 编码** | 03-coding/ | 约束感知编码 + 自动 Code Review |
| **04 研发自测** | 04-dev-testing/ | Subagent 并行测试（单元+API） |
| **05 QA 测试** | 05-qa-testing/ | E2E 测试（Playwright） |

### 两个横切关注点

| 关注点 | 目录 | 功能 |
|--------|------|------|
| **任务进度管理** | 06-task-progress/ | 状态模型 + 看板 + 自动更新 |
| **Debug 与纠错** | 07-debug-and-correction/ | 质量门禁 + 失败分析 + 修复流程 |

---

## ⚙️ 核心机制

### 1. Hook 机制（执行保障层）

**核心原则**：确定性规则 → shell 脚本；语义理解 → Skill

| 事件 | 触发时机 | 典型用途 |
|------|----------|----------|
| `PreToolUse` | AI 调用工具**前** | 拦截、校验、注入前置约束 |
| `PostToolUse` | AI 调用工具**后** | 检查输出、触发后续动作 |

#### Hook 全景

| 阶段 | Hook 名称 | 触发 | 目的 |
|------|-----------|------|------|
| 需求 | `requirement-guard` | PreToolUse( Skill=openspec) | 拦截散乱需求，强制完整性 |
| 需求 | `p0-constraint-writer` | PostToolUse(Skill=openspec) | P0 bug 写回代码约束 |
| 编码 | `post-edit-lint` | PostToolUse(Edit) | 修改后自动 lint |
| 编码 | `pre-commit-review` | PreToolUse(git commit) | commit 前自动 review |
| 自测 | `post-implementation-test` | 实现完成后 | 触发 subagent 自测 |
| QA | `post-dev-test-qa` | 自测通过后 | 生成 QA 测试用例 |

#### Hook 返回码约定

| 返回码 | 含义 |
|--------|------|
| `0` | 通过，继续 |
| `非 0` | 拦截，反馈原因 |

---

### 2. Skill 体系（能力扩展层）

| Skill | 用途 |
|-------|------|
| **harness-init** | 初始化项目 Harness 文档结构（扫描代码库 → 生成 CLAUDE.md/ARCHITECTURE.md 等） |
| **design-generator** | 技术方案生成 |
| **progress-tracker** | 任务进度跟踪与看板 |
| **constraint-extractor** | 从 bug 描述提取代码约束 |
| **design-arch-validator** | 设计方案架构校验 |
| **requirement-semantic-check** | 需求语义完整性检查 |

### 3. Agent 体系（执行层）

| Agent | 职责 |
|-------|------|
| **code-reviewer** | 自动化代码审查 |
| **api-tester** | API 集成测试 |
| **qa-tester** | QA 端到端测试 |
| **debug-analyst** | 调试与根因分析 |

---

## 🔧 关键技术实现

### harness-init 工作流

```
1. 检测项目状态（已有文件 vs 新项目）
2. 扫描代码库：
   - 技术栈识别（package.json/go.mod/...）
   - 项目结构（3 层目录）
   - 最近提交（git log -20）
   - 关键代码模式（入口/配置/测试）
3. 创建文档结构（CLAUDE.md / AGENTS.md / ARCHITECTURE.md / docs/）
4. 填充内容（已有项目）或占位符（新项目）
5. 输出完成报告
```

### 生成的文档清单

| 文件 | 内容 |
|------|------|
| `CLAUDE.md` | Claude 专用项目指令 |
| `AGENTS.md` | AI 代理协作指南 |
| `ARCHITECTURE.md` | 系统架构概述 |
| `docs/DESIGN.md` | 设计原则 |
| `docs/SECURITY.md` | 安全规范 |
| `docs/RELIABILITY.md` | 可靠性标准 |
| `docs/QUALITY_SCORE.md` | 质量度量定义 |
| `docs/PLANS.md` | 路线图 |
| `docs/PRODUCT_SENSE.md` | 产品哲学 |

### 代码约束写回流程

```
P0 bug 创建 → constraint-extractor 语义提炼 → 写入 docs/code-constraints.md
  → 追加到 CLAUDE.md 的 "Do Not" 区块 → 后续 AI 编码自动遵守
```

---

## 🆚 与已有框架的对比

| 维度 | Harness Engineering | Superpowers | ClaudeForge |
|------|-------------------|-------------|-------------|
| **定位** | 全流程约束框架 | 开发方法论 | CLAUDE.md 生成 |
| **覆盖范围** | 需求→测试→QA 全链路 | 编码阶段为主 | 文档生成 |
| **Hook 机制** | ✅ Pre/Post 双事件 | ❌ | ❌ |
| **openspec 集成** | ✅ 需求管理核心 | ❌ | ❌ |
| **代码约束写回** | ✅ P0 bug → 自动禁止项 | ❌ | ❌ |
| **多 Agent 并行** | ✅ 测试阶段 | ✅ | ❌ |
| **成熟度** | 新项目（2026-04-23） | 159k ⭐ | 353 ⭐ |
| **语言** | 中文 | 英文 | 英文 |

---

## 💡 独特价值

### 1. 需求管理闭环

```
散乱想法 → requirement-guard 拦截 → AI 反问引导 → 结构化需求
  → openspec 管理（proposal → design → spec → task）
  → P0 bug 自动提炼代码约束 → 写回项目
```

这是**首个**将需求管理与代码约束自动关联的框架。

### 2. 代码约束自动化

```
P0 bug 发现 → 语义提炼"AI 编码禁止项" → 写入约束文档
  → CLAUDE.md "Do Not" 区块 → AI 后续编码自动遵守
  → pre-commit-review 自动检查
```

**Bug → 约束 → 预防**的自动闭环，减少重复错误。

### 3. 中文优先 + 开箱即用

- 全中文文档，降低国内团队学习门槛
- 完整的 Hook 脚本 + Skill + Agent 配置
- 可直接复制 `hooks/` 目录到目标项目

---

## 📋 接入新项目步骤

```bash
# 1. 复制 hooks 目录
cp -r hooks/ /your/project/

# 2. 合并 hook 配置
# 将 .claude/settings.json 中的 hooks 配置合并到目标项目

# 3. 根据技术栈调整 lint 命令
# 编辑 hooks/scripts/post-edit-lint.sh

# 4. 验证脚本可执行
bash hooks/scripts/requirement-guard.sh
```

---

## 🔗 相关资源

| 资源 | 链接 |
|------|------|
| 仓库 | https://github.com/2361485765/harness-engineering-in-ai-coding |
| Superpowers | https://github.com/obra/superpowers |
| openspec | https://github.com/anthropics/openspec |

---

## 📊 评价

### 优点
- ✅ **全流程覆盖**：从需求到 QA，不只是编码辅助
- ✅ **Hook 机制完善**：Pre/Post 双事件 + shell/Skill 分层
- ✅ **代码约束自动关联**：P0 bug → 自动禁止项，减少重复错误
- ✅ **中文友好**：降低国内团队门槛
- ✅ **不重复造轮子**：复用 superpowers、openspec 等成熟工具

### 注意点
- ⚠️ **极新项目**（2026-04-23 创建），0 stars，仍在建设中
- ⚠️ 目前主要面向 Claude Code，其他工具适配待补充
- ⚠️ 文档完成度约 70%，部分章节待填充

### 适用场景
- 团队想系统性引入 AI 编程工具（而非零散使用）
- 需要对 AI 产物建立质量门禁和审计记录
- 希望沉淀 AI 编程最佳实践为工程规范

---

*整理：知识库管理员 | 归档：2026-04-24*