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>
195 lines
6.2 KiB
Markdown
195 lines
6.2 KiB
Markdown
# 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. 输出文件清单和下一步建议
|
||
```
|