From bd126edab9502ebc6d363c11d229b23d20be9bf2 Mon Sep 17 00:00:00 2001 From: FNS Service Date: Fri, 24 Apr 2026 16:39:12 +0800 Subject: [PATCH] Update from Sync Service --- AI工程/HarnessEngineering研究总结.md | 252 +++++++++++++++++++++++++++ 1 file changed, 252 insertions(+) create mode 100755 AI工程/HarnessEngineering研究总结.md diff --git a/AI工程/HarnessEngineering研究总结.md b/AI工程/HarnessEngineering研究总结.md new file mode 100755 index 0000000..3513930 --- /dev/null +++ b/AI工程/HarnessEngineering研究总结.md @@ -0,0 +1,252 @@ +# 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* \ No newline at end of file