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>
This commit is contained in:
194
skills-req/req-test-gate-plugin/skills/project-bootstrap.md
Normal file
194
skills-req/req-test-gate-plugin/skills/project-bootstrap.md
Normal file
@@ -0,0 +1,194 @@
|
||||
# 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 自动运行 + 受保护分支
|
||||
```
|
||||
|
||||
### 输出格式
|
||||
|
||||
```markdown
|
||||
## 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 项目
|
||||
|
||||
```bash
|
||||
# 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 项目
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 根目录安装 husky，各子项目配置 lint-staged
|
||||
# 参见 templates/pre-commit-config.md — Monorepo 变体
|
||||
```
|
||||
|
||||
### Level 2: 约定与 Ratchet
|
||||
|
||||
**前置**：Level 1 已完成。
|
||||
|
||||
#### Step 1: 创建目录结构
|
||||
|
||||
```bash
|
||||
mkdir -p scripts docs/quality
|
||||
```
|
||||
|
||||
#### Step 2: 创建 GATES.md
|
||||
|
||||
参见 [templates/gates-doc.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](harness-engineering.md) 的「CLAUDE.md 约定文档格式」。
|
||||
|
||||
#### Step 5: 提交
|
||||
|
||||
```bash
|
||||
./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 和受保护分支。
|
||||
|
||||
```yaml
|
||||
# .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. 输出文件清单和下一步建议
|
||||
```
|
||||
Reference in New Issue
Block a user