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

6.2 KiB

Raw Permalink Blame History

Project Bootstrap — 工程约束基础设施引导

`/harness assess` 检测逻辑

扫描项目结构，自动判断成熟度等级（0-3），列出缺口和建议。

检测项清单（每项附实际执行的命令）

检测项	执行命令	判定	Level
技术栈	`Glob("package.json", "go.mod", "Podfile", "*.csproj")`	存在即识别	基础
Pre-commit hooks	`Glob(".husky/pre-commit")`	文件存在	1
Lint 配置	`Glob(".eslintrc*", ".golangci.yml") + Grep("lint", "Makefile")`	任一存在	1
Formatter	`Glob(".prettierrc*") + Grep("gofmt\\|prettier", ".husky/pre-commit")`	任一存在	1
lint-staged	`Grep("lint-staged", "package.json") + Glob(".lintstagedrc*")`	任一存在	1
约定脚本	`Glob("scripts/check-*.sh")`	至少 1 个	2
基线文件	`Glob("scripts/.*-baseline.json")`	至少 1 个	2
门禁文档	`Glob("docs/quality/GATES.md")`	文件存在	2
CLAUDE.md 质量段落	`Grep("检查命令\\|check-.*\\.sh", "CLAUDE.md")`	有匹配	2
CI workflow	`Grep("check-.\\.sh", ".gitea/workflows/.yml", ".github/workflows/*.yml")`	有匹配	3

等级判定

Level 0: 无上述任何基础设施
Level 1: 有 pre-commit hooks + lint + formatter
Level 2: Level 1 + 有 ratchet/约定脚本 + GATES.md
Level 3: Level 2 + CI 自动运行 + 受保护分支

输出格式

## Harness Assessment: {项目名}

**技术栈**: Go + React (monorepo)
**当前等级**: Level 2

### 已有基础设施
- [x] husky pre-commit hooks
- [x] ESLint + Prettier (frontend)
- [x] gofmt + go vet (backend)
- [x] check-architecture.sh (ratchet, 5 rules)
- [x] check-modal-safety.sh (hard wall)
- [x] GATES.md

### 缺口（升至 Level 3）
- [ ] CI workflow 未调用 check-architecture.sh
- [ ] CI workflow 未调用 check-modal-safety.sh

### 建议
1. 在 .gitea/workflows/quality-gates.yaml 中添加 check-architecture.sh check
2. 在 .gitea/workflows/quality-gates.yaml 中添加 check-modal-safety.sh --ci

`/harness init [level]` 分级实施

Level 1: 基础代码格式化

适用：所有活跃项目。

Node.js 项目

# 1. 安装 husky + lint-staged
npm install -D husky lint-staged
npx husky init

# 2. 配置 lint-staged（package.json）
# 参见 templates/pre-commit-config.md — Node.js 变体

# 3. 配置 pre-commit hook
echo "npx lint-staged" > .husky/pre-commit

Go 项目

# 1. 安装 husky（需要 package.json）
npm init -y
npm install -D husky lint-staged
npx husky init

# 2. 配置 lint-staged（package.json）
# 参见 templates/pre-commit-config.md — Go 变体

# 3. 配置 pre-commit hook
echo "npx lint-staged" > .husky/pre-commit

Monorepo

# 根目录安装 husky，各子项目配置 lint-staged
# 参见 templates/pre-commit-config.md — Monorepo 变体

Level 2: 约定与 Ratchet

前置：Level 1 已完成。

Step 1: 创建目录结构

mkdir -p scripts docs/quality

Step 2: 创建 GATES.md

参见 templates/gates-doc.md，填入项目实际的 lint 工具和 CI 系统。

Step 3: 约束发现（关键步骤）

AI 必须探索项目代码库，按以下清单逐项检查，找出适合建 ratchet 的约束：

检查项	检测方法	发现约束时
分层架构	读 `go.mod` / 目录结构，判断是否有 handler/service/repository 分层	检查跨层 import → ratchet
禁止 import	`grep -r "import" --include="*.go"` 找不应出现的包引用	统计违规数 → ratchet 或 wall
前端 API 调用规范	`grep -r "fetch\|axios" --include="*.tsx"` 看是否有直接调用（应走 service 层）	统计违规数 → ratchet
console.log 残留	`grep -r "console.log" --include=".tsx" --include=".ts"`	统计数量 → ratchet
硬编码配置	`grep -rn "localhost\|127.0.0.1\|:3000\|:8080" --include=".ts" --include=".go"` 排除测试和配置文件	统计数量 → ratchet
TODO/FIXME	`grep -rn "TODO\|FIXME" --include=".go" --include=".ts"`	统计数量 → ratchet（仅追踪，不阻塞）

执行流程：

1. 读取项目目录结构（ls -R 前两层）
2. 识别技术栈和架构风格
3. 按上表逐项 grep 扫描
4. 筛选：违规数 > 0 的项列为候选规则
5. AskUserQuestion：展示候选规则表，让用户勾选要建哪些
6. 对每条选中的规则：
   a. 用 ratchet-script 模板生成 scripts/check-{name}.sh
   b. 运行 baseline 记录初始值
   c. 在 CLAUDE.md 添加约定段落

如果扫描后没有发现任何候选规则（代码量很小或结构简单），Level 2 只创建 GATES.md + CLAUDE.md 质量段落，不创建 ratchet 脚本。后续通过 convention flow（修 bug 时）逐步积累。

Step 4: CLAUDE.md 质量段落

参见 harness-engineering.md 的「CLAUDE.md 约定文档格式」。

Step 5: 提交

./scripts/check-{name}.sh baseline   # 每个新脚本都要 baseline
git add scripts/ docs/quality/ CLAUDE.md
git commit -m "chore: establish harness engineering Level 2"

Level 3: CI 强制

前置：Level 2 已完成 + 项目有 CI 和受保护分支。

# .gitea/workflows/quality-gates.yaml 示例
name: Quality Gates
on:
  pull_request:
    branches: [main, develop]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Architecture Check
        run: ./scripts/check-architecture.sh check
      - name: Convention Checks
        run: |
          for script in scripts/check-*.sh; do
            [ "$script" = "scripts/check-architecture.sh" ] && continue
            bash "$script" --ci
          done

`/harness init` 执行流程

1. 运行 /harness assess 确定当前等级
2. 确定目标等级（用户指定或默认 Level 1）
3. 如果当前等级 ≥ 目标等级，提示"已满足"
4. 按目标等级模板生成文件：
   - Level 1: .husky/ + package.json lint-staged
   - Level 2: scripts/ + docs/quality/ + CLAUDE.md 段落
   - Level 3: CI workflow
5. 运行验证（husky hook 是否生效、脚本是否可执行）
6. 输出文件清单和下一步建议

6.2 KiB Raw Permalink Blame History Unescape Escape