Update from Sync Service

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*