# 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 |