chill/chill_notes

Fork 0

Files

FNS Service bd126edab9 Update from Sync Service

2026-04-24 16:39:12 +08:00

7.9 KiB

Executable File

Raw Blame History

Harness Engineering in AI Coding 研究总结

探索在 AI 编程中的 Harness Engineering，确保 AI 编程可约束、可评估、可追溯

归档：2026-04-24

📊 项目概览

属性	值
仓库	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/ 目录到目标项目

📋 接入新项目步骤

# 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

7.9 KiB Executable File Raw Blame History Unescape Escape