Files

John Qiu b9c808cce0 feat(req-test-gate): 集成 Harness Engineering 工程约束方法论

将项目级的 Ratchet/约定检测方法论融入 req-test-gate 技能，
通过 /req 流程三个节点自动触发（dev 环境检测、cr 约定建议、test Gate 0B），
无需手动记忆执行。

新增文档：harness-engineering.md、ratchet-pattern.md、convention-flow.md、
project-bootstrap.md 及 4 个模板（ratchet/convention 脚本、GATES.md、pre-commit）。

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-03-26 11:34:42 +10:30

4.9 KiB

Raw Blame History

Harness Engineering — 工程约束方法论

概述

Harness Engineering 是一套建立自动化护栏防止新违规，同时允许渐进式清理遗留问题的工程方法论。

三大支柱：

支柱	核心机制	说明
Ratchet	基线 + 单调递减	遗留违规数只能减不能增，新代码零容忍
约定建立	Bug → 文档 → 自动检测	每个 bug 修复后立即建立约定和检测脚本
门禁层级	Level 1-3 递进	按项目成熟度逐级引入基础设施

子文件索引

文件	内容
ratchet-pattern.md	Ratchet 模式详解：Ratchet vs Hard Wall、基线格式、三命令接口
convention-flow.md	三步约定建立流程：修 bug → 文档化 → 自动化检测
project-bootstrap.md	`/harness assess` 检测逻辑 + `/harness init` 分级实施指南
templates/	脚本模板：ratchet、约定检测、GATES.md、pre-commit 配置

命令集与自动触发

命令	手动触发	自动触发时机
`/harness assess`	用户显式调用	`/req dev` 启动时快速检测（`.husky/` + `scripts/check-*.sh` 都不存在 → 提示 Level 0）
`/harness init [level]`	用户显式调用	不自动触发（创建基础设施需用户确认）
`/harness convention [name]`	用户显式调用	`/req cr` + category=bug 时自动建议（分析根因 → 建议约定 → 用户确认后执行）
`/harness report`	用户显式调用	`/req test` Gate 0B 自动运行所有 `scripts/check-*.sh`

自动触发流程图

/req dev (每次)
  └→ 快速检测: .husky/ 存在? scripts/check-*.sh 存在?
       └→ 都不存在 → 提示「Level 0，建议 /harness init」（不阻塞）
       └→ 有任一 → 静默通过

/req cr (bug 类型需求)
  └→ 五视角扫描
  └→ 运行 scripts/check-*.sh → 写入 CR 报告
  └→ ⭐ 分析 bug 根因 → 可自动检测? → 建议建立约定
       └→ 用户确认 → convention flow（文档化 → 脚本 → CLAUDE.md）

/req test
  └→ Gate 0A: scope 分级
  └→ Gate 0B: 运行所有 scripts/check-*.sh
       └→ 有 FAIL → 阻塞，必须修复
       └→ 全 PASS → 继续 Gate 1-5

手动命令仍然可用。自动触发只是让你"不用记得去跑"。

成熟度分级

Level	基础设施	适用场景
0	无自动化检查	新项目/原型
1	husky + lint-staged + formatter	所有活跃项目
2	+ ratchet 脚本 + GATES.md + CLAUDE.md 质量段落	>10k LOC 或 >1 开发者
3	+ CI workflow + 架构强制 + 约定检测	有 PR 流程和受保护分支的项目

技术栈检测矩阵

技术栈	检测标志	Level 1 工具	Level 2+ 工具
Go	`go.mod`	gofmt + go vet	golangci-lint, architecture ratchet
React/TS	`package.json` + react 依赖	ESLint + Prettier	tsc --noEmit, convention scripts
Vue/TS	`package.json` + vue 依赖	ESLint + Prettier	vite build check
Monorepo	多个 `package.json` / `go.mod`	各子项目独立 lint	统一 CI + 分模块 ratchet

CLAUDE.md 约定文档格式

在项目的 CLAUDE.md 中添加约定时，必须遵循以下标准格式：

### {类别}: {约定名称}

{原因描述 — 为什么需要这条约定}

**规则：{一句话规则描述}**

\`\`\`{语言}
// WRONG — {错误原因}
{错误代码示例}

// CORRECT — {正确做法}
{正确代码示例}
\`\`\`

**检查命令**：`./scripts/check-{name}.sh`（CI 自动运行）

与其他技能的关系

Harness 和 req-test-gate 是互补关系，不要混淆两者的 Gate 编号：

维度	Harness	req-test-gate
作用域	项目级（所有 PR 共享）	需求级（每个需求独立）
触发方式	git commit / PR / `/req test` Gate 0B	`/req test` Gate 1-5
管什么	pre-commit、lint、ratchet 脚本、约定检测	测试执行、质量验证、文档持久化、回归
产出物	`.husky/`、`scripts/check-*.sh`、CLAUDE.md 约定	测试报告、回归用例

⚠️ 注意：项目的 docs/quality/GATES.md 中有自己的 Gate 编号（Gate 0=pre-commit, Gate 1=CI lint, Gate 2=ratchet...），这是项目文档的编号，与 req-test-gate 的 Gate 0-5 是两套独立体系，不要混用。

技能	职责
harness（本文档）	建立和维护项目级护栏（脚本、约定、CLAUDE.md）
req-test-gate	需求级测试门禁（Gate 0-5），其中 Gate 0B 自动调用 harness 建立的脚本
dev-coding	遵守 harness 建立的 CLAUDE.md 约定，编码时不违反 ratchet

4.9 KiB Raw Blame History Unescape Escape