blueprint-derive-tests

/blueprint:derive-tests

分析 Git 历史，找出缺少对应测试变更的修复和功能提交，然后生成结构化的测试回归计划（TRP）文档，作为按优先级排列的测试待办清单。

使用场景：通过挖掘提交历史中未附带回归测试的 Bug 修复和功能，系统性地弥补测试覆盖率缺口。

何时使用此技能

在以下情况下使用此技能……	在以下情况下使用替代方案……
Bug 修复发布时没有回归测试	需要运行现有测试（/test:run）
想要根据历史记录生成按优先级排列的测试待办清单	为特定功能编写测试（手动 TDD）
为项目引入新成员并评估测试健康状况	检查当前测试覆盖率指标
需要找出哪些修复缺少测试覆盖	从头设计测试策略（/test:architecture）

上下文

• Git 仓库：!git rev-parse --git-dir
• Blueprint 已初始化：!find . -path '*/docs/blueprint/*' -maxdepth 3 -name 'manifest.json' -type f
• 提交总数：!git rev-list --count HEAD
• 测试框架：!find . -maxdepth 3 \( -name 'vitest.config.*' -o -name 'jest.config.*' -o -name 'pytest.ini' -o -name 'pyproject.toml' -o -name 'Cargo.toml' -o -name 'go.mod' \) -type f -print -quit
• 测试文件：!find . -maxdepth 4 -type f \( -name '*.test.*' -o -name '*.spec.*' -o -name 'test_*' -o -name '*_test.*' \) -print
• Conventional Commits 示例：!git log --format="%s" --max-count=10

参数

从 $ARGUMENTS 中解析以下参数：

• --quick：快速扫描（仅检查最近 50 个提交）
• --since DATE：分析指定日期之后的提交（例如，--since 2024-06-01）
• --scope AREA：筛选涉及特定区域/范围的提交（例如，--scope auth）

不带标志时的默认行为：分析最近 200 个提交。

详细模板、严重性矩阵和测试映射规则，请参阅 REFERENCE.md。

执行

执行以下测试回归计划推导工作流：

步骤 1：验证前置条件

检查上述上下文值：

1. 如果 Git 仓库为空 → 错误："This directory is not a git repository. Run from project root."
2. 如果提交总数 = "0" → 错误："Repository has no commit history."
3. 如果 Blueprint 已初始化为空 → 询问用户："Blueprint not initialized. Initialize now (Recommended) or continue without manifest tracking?"
   • 如果选择 "Initialize now" → 使用 Task 工具调用 /blueprint:init，然后继续
   • 如果选择 "Continue without" → 在步骤 7 中跳过清单更新

步骤 2：确定分析范围

从 $ARGUMENTS 中解析 --quick、--since 和 --scope：

1. 如果指定了 --quick → 范围 = 最近 50 个提交
2. 如果指定了 --since DATE → 范围 = 从 DATE 到现在的提交
3. 如果指定了 --scope AREA → 将提交筛选为范围与 AREA 匹配，或涉及 AREA 目录中文件的提交
4. 否则 → 范围 = 最近 200 个提交

保存范围参数，供后续步骤中的 git log 命令使用。

步骤 3：检测测试基础设施

扫描测试框架和约定：

1. 根据上下文识别测试框架（vitest、jest、pytest、cargo test、go test）
2. 检测测试文件命名约定：
   • *.test.ts、*.spec.ts（JS/TS）
   • test_*.py、*_test.py（Python）
   • *_test.rs、tests/ 目录（Rust）
   • *_test.go（Go）
3. 将源代码目录映射到测试目录（例如，src/ → tests/、src/ → src/__tests__/）
4. 记录框架、命名模式和目录映射，供步骤 5 使用

如果未检测到测试框架 → 警告用户，并仅通过文件进行检测。

第 4 步：对提交分类并检测覆盖缺口

运行辅助脚本。它负责确定性核心工作：对 git log 中的 fix:/feat: 提交分类，检测每个提交是否包含内联测试文件变更（git show --name-only），并通过固定矩阵分配严重性（fix: + 无内联测试 → CRITICAL；feat: + 无内联测试 → MEDIUM；任何包含测试的提交 → COVERED）。传入 --limit 可限制扫描范围（默认值为 200；使用 --quick 时传入 --limit 50）：

bash "${CLAUDE_SKILL_DIR}/scripts/blueprint-derive-tests.sh" --home-dir "$HOME" --project-dir "$(pwd)"

解析输出中的 STATUS= 和 ISSUES:。FIX_COMMITS/FEAT_COMMITS 是分类计数；GAPS_CRITICAL/GAPS_MEDIUM/GAPS_TOTAL 是覆盖缺口数量；每个 coverage_gap 问题都包含 SHA=、TYPE=、SEVERITY= 和 SUBJECT=，供 TRP 表格使用。STATUS=ERROR 表示至少存在一个 CRITICAL（未经测试的修复）缺口。

脚本的内联测试检测和基础严重性（CRITICAL/MEDIUM）是确定性基准。若需要更细致的 High/Low 级别、邻近测试提交的严重性下调，或按语言划分的源代码到测试代码映射，请应用 REFERENCE.md 中的修正规则和 REFERENCE.md 中的映射规则。若要按 --since/--scope 筛选，请先使用 REFERENCE.md 中的命令缩小 git 范围，再读取缺口集合。

第 6 步：生成 TRP 文档

TRP 文件位于 docs/trps/ 下的顶层，而不是 docs/blueprint/trps/。这与 derive-* 同级技能的顶层布局一致。切勿将 TRP 文件写入 docs/blueprint/；该路径专用于 blueprint 机制。

1. 创建输出目录：mkdir -p docs/trps
2. 确定 TRP ID：
   • 如果清单存在，读取 id_registry.last_trp 并加 1
   • 否则从 TRP-001 开始
3. 根据范围或日期范围生成 slug（例如，regression-gaps-2024-q3）
4. 使用 REFERENCE.md 中的模板，将 TRP 文档写入 docs/trps/{slug}.md

文档中应包含：

• 包含 id、status: Active、scope、date_range、commits_analyzed 的 YAML frontmatter
• 按严重性统计缺口数量的执行摘要
• 详细缺口表格：提交 SHA、主题、严重性、受影响文件、建议的测试类型
• 建议的测试创建顺序（先处理 Critical，然后是 High 等）
• 每个缺口的建议测试类型（参见 REFERENCE.md）

第 7 步：更新清单

如果已初始化 Blueprint：

1. 将 id_registry.last_trp 更新为新的 TRP 编号
2. 在 id_registry.documents 中注册该文档：

   {
     "TRP-NNN": {
       "path": "docs/trps/{slug}.md",
       "title": "{TRP title}",
       "status": "Active",
       "created": "{date}"
     }
   }
   

3. 更新任务注册表：

   jq --arg now "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
     --arg sha "$(git rev-parse HEAD 2>/dev/null)" \
     --argjson analyzed "{commits_analyzed}" \
     --argjson gaps "{gaps_found}" \
     '.task_registry["derive-tests"].last_completed_at = $now |
      .task_registry["derive-tests"].last_result = "success" |
      .task_registry["derive-tests"].stats.runs_total = ((.task_registry["derive-tests"].stats.runs_total // 0) + 1) |
      .task_registry["derive-tests"].stats.items_processed = $analyzed |
      .task_registry["derive-tests"].stats.items_created = $gaps |
      .task_registry["derive-tests"].context.commits_analyzed_up_to = $sha' \
     docs/blueprint/manifest.json > tmp.json && mv tmp.json docs/blueprint/manifest.json
   

第 8 步：报告结果并建议后续操作

打印摘要：

Test Regression Plan Generated!

**Analysis Summary**
- Commits analyzed: {N} ({date_range})
- Fix commits found: {N}
- Feature commits found: {N}

**Coverage Gaps Found**
- Critical: {N} (fix commits with no tests at all)
- High: {N} (fix commits with stale test files)
- Medium: {N} (feature commits missing tests)
- Low: {N} (feature commits with nearby tests)

**Document**: docs/trps/{slug}.md (TRP-{NNN})

**Top Priority Gaps**
1. {commit subject} — {severity} — {affected file}
2. {commit subject} — {severity} — {affected file}
3. {commit subject} — {severity} — {affected file}

提示用户选择下一步操作：

• “为优先级最高的缺口创建 PRP（推荐）” — 为 Critical/High 缺口生成 PRP 文档
• “查看 TRP 文档” — 打开生成的 TRP，供人工审阅
• “使用不同范围重新运行” — 使用 --since 或 --scope 重新运行
• “暂时完成” — 保存文档并退出

Agentic 优化

场景	命令
仅查看修复提交	git log --format="%H %s" | grep -E "^[a-f0-9]+ fix"
检查提交中是否包含测试	git diff-tree --no-commit-id --name-only -r {SHA} | grep -E "test|spec"
变更的文件	git diff-tree --no-commit-id --name-only -r {SHA}
快速扫描	使用 --quick 扫描最近 50 个提交
范围筛选	使用 --scope auth 将范围限制为特定区域

---

有关详细模板、严重性分类矩阵、测试映射规则和错误处理，请参阅 REFERENCE.md。