252 lines
7.9 KiB
Markdown
Executable File
252 lines
7.9 KiB
Markdown
Executable File
# 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* |