John Qiu
b9c808cce0
将项目级的 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>
114 lines
4.9 KiB
Markdown
114 lines
4.9 KiB
Markdown
# Harness Engineering — 工程约束方法论
|
||
|
||
## 概述
|
||
|
||
Harness Engineering 是一套**建立自动化护栏防止新违规，同时允许渐进式清理遗留问题**的工程方法论。
|
||
|
||
**三大支柱**：
|
||
|
||
| 支柱 | 核心机制 | 说明 |
|
||
|------|---------|------|
|
||
| **Ratchet** | 基线 + 单调递减 | 遗留违规数只能减不能增，新代码零容忍 |
|
||
| **约定建立** | Bug → 文档 → 自动检测 | 每个 bug 修复后立即建立约定和检测脚本 |
|
||
| **门禁层级** | Level 1-3 递进 | 按项目成熟度逐级引入基础设施 |
|
||
|
||
## 子文件索引
|
||
|
||
| 文件 | 内容 |
|
||
|------|------|
|
||
| [ratchet-pattern.md](ratchet-pattern.md) | Ratchet 模式详解：Ratchet vs Hard Wall、基线格式、三命令接口 |
|
||
| [convention-flow.md](convention-flow.md) | 三步约定建立流程：修 bug → 文档化 → 自动化检测 |
|
||
| [project-bootstrap.md](project-bootstrap.md) | `/harness assess` 检测逻辑 + `/harness init` 分级实施指南 |
|
||
| [templates/](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 中添加约定时，必须遵循以下标准格式：
|
||
|
||
```markdown
|
||
### {类别}: {约定名称}
|
||
|
||
{原因描述 — 为什么需要这条约定}
|
||
|
||
**规则：{一句话规则描述}**
|
||
|
||
\`\`\`{语言}
|
||
// 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 |
|