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