blueprint-derive-plans

/blueprint:derive-plans

通过分析 Git 历史记录、代码库结构和现有文档，从已有成熟项目中追溯生成 Blueprint 文档（PRD、ADR、PRP）。

使用场景：将已有成熟项目接入 Blueprint Development 系统，但项目没有 PRD/ADR/PRP 文档，且已有实现历史记录。

何时使用此技能

在以下情况下使用此技能……	在以下情况下使用替代方案……
项目有 Git 历史记录，但没有 PRD/ADR/PRP	从头启动一个没有历史记录的全新项目
将已有成熟项目接入 Blueprint	在用户指导下从头创建新的 PRD
需要从提交历史中提取功能	项目缺少规范的提交记录，且历史不清晰
想要追溯记录架构决策	决策已完整记录

上下文

• Git 仓库：!git rev-parse --git-dir
• Blueprint 已初始化：!find . -path '*/docs/blueprint/*' -maxdepth 3 -name 'manifest.json' -type f
• 提交总数：!git rev-list --count HEAD
• 首次提交：!git log --reverse --format=%ai --max-count=1
• 最新提交：!git log --max-count=1 --format=%ai
• 项目类型：!find . -maxdepth 1 \( -name 'package.json' -o -name 'pyproject.toml' -o -name 'Cargo.toml' -o -name 'go.mod' -o -name 'pom.xml' \) -type f -print -quit
• 文档文件：!find . -maxdepth 2 \( -name "README.md" -o -name "ARCHITECTURE.md" -o -name "DESIGN.md" \)

参数

从 $ARGUMENTS 中解析以下参数：

• --quick：快速扫描（仅检查最近 50 次提交）
• --since DATE：分析指定日期以来的提交（例如，--since 2024-01-01）

不带标志时的默认行为：标准分析（最近 200 次提交，并估算分析范围）。

有关详细模板、清单格式和报告示例，请参阅 REFERENCE.md。

执行

执行以下追溯文档生成工作流：

步骤 1：验证前提条件

检查上方的上下文值：

1. 如果 Git 仓库 = "NO" → 错误："此目录不是 Git 仓库。请从项目根目录运行。"
2. 如果提交总数 = "0" → 错误："仓库没有提交历史记录"
3. 如果 Blueprint 已初始化 = "NO" → 询问用户："Blueprint 尚未初始化。现在初始化（推荐），还是仅进行最小化导入？"
   • 如果选择"现在初始化" → 使用 Task 工具调用 /blueprint:init，然后从步骤 1 继续
   • 如果选择"仅进行最小化导入" → 创建最小目录结构：mkdir -p docs/prds docs/adrs docs/prps

步骤 2：确定分析范围

解析 $ARGUMENTS 中的 --quick 或 --since：

1. 如果存在 --quick 标志 → 范围 = 最近 50 次提交
2. 如果存在 --since DATE → 范围 = 从 DATE 至今的提交
3. 否则 → 向用户提供选项：
   • 快速扫描（最近 50 次提交）
   • 标准分析（最近 200 次提交）
   • 完整历史分析（所有提交）
   • 自定义日期范围

后续所有 Git 分析均使用所选范围。

步骤 3：分析 Git 历史记录质量

针对范围内的提交，计算：

1. 统计提交总数：git log --oneline {scope} | wc -l
2. 统计规范提交数：git log --format="%s" {scope} | grep -cE "^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)\(?.*\)?:" || echo 0
3. 计算百分比并评定质量分数（参见 REFERENCE.md）

报告："Git 历史记录质量：{score}/10（{percentage}% 为规范提交）"

步骤 4：提取功能和架构决策

使用 REFERENCE.md 中的方法：

1. 从规范提交的范围中提取功能边界
2. 识别架构决策（迁移、主要依赖项、破坏性变更）
3. 查找问题引用和待办事项（TODO、跳过的测试）
4. 根据 Git 标签识别发布边界

以结构化格式收集发现，供用户确认。

步骤 5：分析代码库和现有文档

1. 使用 Explore Agent 分析架构：目录结构、组件、框架、模式、入口点、数据层、API 层、测试结构
2. 从清单文件（package.json、pyproject.toml、Cargo.toml、go.mod 等）中提取依赖项
3. 阅读并提取现有文档中的内容：README.md、docs/、ARCHITECTURE.md、DESIGN.md、CONTRIBUTING.md
4. 检测后续工作：代码中的 TODO、未关闭的 GitHub 问题、跳过的测试

步骤 6：向用户确认项目背景

通过 AskUserQuestion 询问需要澄清的问题。完整的问题模板 （问题陈述、目标用户、项目阶段、利益相关者规模）请参阅 REFERENCE.md。

1. 项目目的（如果 README 中不明确）：提供推断出的描述供用户确认，或请用户提供描述
2. 目标用户：开发者、最终用户或两者兼有——这会影响 PRD 的表述方式
3. 项目阶段：MVP / 积极开发 / 维护 / 计划重大变更——决定对功能与稳定性的侧重
4. 利益相关者：规模（个人 / 小团队 / 大型组织 / OSS 社区）→ 决定 PRD 利益相关者矩阵的详细程度（参见 REFERENCE.md）
5. 功能确认：展示从 git 中提取的 {N} 项功能，以供审查和确定优先级
6. 架构决策依据：针对每项已识别的决策，询问其主要驱动因素
7. 生成确认：展示以下摘要，并询问是否准备好生成

在确认步骤中，展示：

• Git 历史质量：{score}/10
• 已识别的功能：{N}
• 架构决策：{N}
• 后续工作项：{N}
• 拟生成的文档：PRD（含利益相关者矩阵）、{N} 份 ADR、{N} 份 PRP

步骤 7：生成文档

创建目录结构：mkdir -p docs/prds docs/adrs docs/prps

对于每种文档类型，使用 REFERENCE.md 中的模板和模式：

1. 生成 PRD，保存为 docs/prds/project-overview.md

   • 使用 REFERENCE.md 中的章节和结构
   • 包含提取出的功能及其优先级和来源
   • 为各章节标注置信度评分

2. 生成 ADR，保存为 docs/adrs/{NNNN}-{title}.md（每项决策一份）

   • 使用 REFERENCE.md 中的 ADR 模板
   • 包含 git 证据（提交 SHA、日期、变更文件）
   • 标注置信度评分
   • 冲突与取代关系检查：写完 ADR 后，运行 /blueprint:adr-relationships，以检测同一领域中的冲突，并运行 /blueprint:adr-validate，以确保取代关系的一致性是双向的。 不要在此处重新实现冲突评分——这些技能负责处理该任务。

3. 创建 ADR 索引，保存为 docs/adrs/README.md

   • 用表格列出所有 ADR 及其状态和日期
   • 链接到 MADR 模板，供创建新 ADR 时使用

4. 生成 PRP，保存为 docs/prps/{feature}.md（每项后续工作各一份）

   • 使用 REFERENCE.md 中的 PRP 模板
   • 包含来源引用和置信度评分
   • 根据代码库模式提出实现建议

步骤 8：更新清单并报告结果

1. 使用导入元数据更新 docs/blueprint/manifest.json：时间戳、分析的提交、置信度评分、生成的产物

步骤 8.5：为生成的文档提供 GitHub 问题选项（可选）

通过 AskUserQuestion 提示用户，询问是否要为生成的 PRD（以及可选的每份 PRP）创建跟踪用的 GitHub 问题。提示模板和 gh issue create 命令请参阅 REFERENCE.md。用户同意后：

1. 创建问题，标题为 [{PRD-NNN}] {Project Name}。
2. 将问题编号添加到文档的 github-issues frontmatter。
3. 在清单 id_registry 中记录该问题（documents[ID].github_issues 和 github_issues 映射）。

若未配置 gh 远程仓库或用户拒绝，则直接跳过，不作提示。

步骤 9：更新任务注册表

更新 docs/blueprint/manifest.json 中的任务注册表条目：

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

2. 创建摘要报告，显示：

   • 已分析的提交及日期范围
   • Git 质量评分
   • 生成的文档（PRD、ADR 数量、PRP 数量）
   • 需要审核的部分（置信度 < 7）
   • 建议的后续步骤

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

   • 审核并完善文档
   • 根据 PRD 生成项目规则
   • 生成工作流命令
   • 退出（文档已保存）

Agentic 优化

上下文	命令
检查 git 状态	git rev-parse --git-dir 2>/dev/null && echo "YES" || echo "NO"
统计提交数	git rev-list --count HEAD 2>/dev/null || echo "0"
统计 Conventional Commits 数量	git log --format="%s" | grep -cE "^(feat|fix|docs)" || echo 0
提取作用域	git log --format="%s" | grep -oE '\([^)]+\)' | sort | uniq -c
快速分析	使用 --quick 标志，仅分析最近 50 条提交

---

有关详细模板、git 分析模式、文档生成示例和错误处理指南，请参阅 REFERENCE.md。