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

3.0 KiB

Raw Permalink Blame History

Ratchet Pattern — 渐进式违规清理

Ratchet vs Hard Wall

策略	适用场景	基线值	CI 行为
Ratchet	有遗留违规（>0）	当前违规数	新值 > 基线 → FAIL
Hard Wall	必须为零	固定 = 0	值 ≠ 0 → FAIL

选择依据：

遗留违规 = 0 → Hard Wall（绝对禁止）
遗留违规 > 0 → Ratchet（允许存在但不能增加）

基线文件格式

基线以 JSON 格式存储，提交到 git：

{
  "rule_name_1": 108,
  "rule_name_2": 7,
  "rule_name_3": 0
}

位置约定：scripts/.{检测名}-baseline.json（如 scripts/.architecture-baseline.json）

三命令接口

每个 ratchet 脚本必须实现三个子命令：

命令	用途	CI 使用
`check`	比较当前值与基线，增加则失败	PR 门禁
`baseline`	记录当前值为新基线	修复违规后手动执行
`report`	打印当前值 vs 基线的对比表	人工审查

./scripts/check-{name}.sh check      # CI: fail if violations increased
./scripts/check-{name}.sh baseline   # After fix: record new lower baseline
./scripts/check-{name}.sh report     # Human: see current vs baseline

何时降低基线

1. 修复一个或多个违规
2. 运行 check → PASS（因为当前值 ≤ 旧基线）
3. 运行 baseline → 记录更低的基线
4. git commit 新的基线文件
5. 后续 PR 使用更低的基线

关键：修复后一定要 baseline + commit，否则下次有人新增违规会被允许（因为基线还是旧的高值）。

多规则 Ratchet

一个脚本可以管理多条规则，每条规则有独立的基线值和类型（ratchet/wall）。

# rules 数组定义规则名
rules=("handlers_import_database" "routes_import_database" "models_import_upper")
# types 数组定义策略
types=("ratchet" "ratchet" "wall")

# 循环检查每条规则
for i in "${!rules[@]}"; do
  rule="${rules[$i]}"
  type="${types[$i]}"
  # ...
done

参考实现

new-ai-proj 项目的架构 ratchet：

脚本：scripts/check-architecture.sh
基线：scripts/.architecture-baseline.json
规则文档：docs/architecture/LAYER_RULES.md
门禁文档：docs/quality/GATES.md

五条规则：

规则	类型	含义
`handlers_import_database`	ratchet	Handler 不应直接访问数据库层
`routes_import_database`	ratchet	路由不应直接访问数据库层
`routes_import_services`	ratchet	路由应通过 handler 委托
`models_import_upper`	hard wall	模型层禁止反向依赖
`services_import_handlers`	hard wall	服务层禁止反向依赖

设计 Ratchet 规则的原则

可计数 — 规则违规必须能通过 grep/AST 精确计数
无歧义 — 一个文件/行要么违规要么不违规，不能有灰色地带
可修复 — 开发者必须知道怎么把违规改正确
有文档 — 每条规则配 LAYER_RULES.md 或 CLAUDE.md 中的正反示例

3.0 KiB Raw Permalink Blame History Unescape Escape