blueprint-derive-rules

/blueprint:derive-rules

从 Git 提交历史中提取项目决策，并将其编写为 Claude 规则。发生冲突时，较新的提交会覆盖较旧的决策。

使用场景：从 Git 历史中推导隐式项目模式，建立一致的 AI 辅助开发指南。

用法：/blueprint:derive-rules [--since DATE] [--scope SCOPE]

何时使用此技能

在以下情况下使用此技能……	在以下情况下使用替代方案……
想从 Git 历史中提取隐式决策	根据需求创建规则（请改用 PRD）
项目有大量提交历史	新项目，历史记录较少
建立项目编码标准	快速手动创建规则

上下文

• Git 仓库：!git rev-parse --git-dir
• Blueprint 已初始化：!find . -path '*/docs/blueprint/*' -maxdepth 3 -name 'manifest.json' -type f
• 提交总数：!git rev-list --count HEAD
• Conventional Commits 占比：!git log --format="%s"
• 默认位置的现有规则：!find . -path '*/.claude/rules/*' -maxdepth 3 -name "*.md" -type f
• Blueprint 子目录中的现有规则：!find . -path '*/.claude/rules/blueprint/*' -maxdepth 4 -name "*.md" -type f

参数

解析 $ARGUMENTS：

• --since DATE：分析指定日期之后的提交（例如，--since 2024-01-01）
• --scope SCOPE：聚焦于特定领域（例如，--scope api、--scope testing）

执行

执行完整的 Git 到规则推导工作流：

步骤 0：确定输出路径

从 docs/blueprint/manifest.json 中读取 structure.generated_rules_path（默认值为 .claude/rules/）：

RULES_DIR=$(jq -r '.structure.generated_rules_path // ".claude/rules/"' docs/blueprint/manifest.json)
mkdir -p "$RULES_DIR"

后续所有读取、写入和冲突检查都使用 $RULES_DIR。此技能有意忽略父级 .claude/rules/ 中手写的文件（问题 #1043）。

步骤 1：验证前提条件

1. 如果不是 Git 仓库 → 错误：“此目录不是 Git 仓库”
2. 如果 Blueprint 尚未初始化 → 建议先运行 /blueprint:init
3. 如果提交较少（< 20）→ 警告：“提交历史有限；推导出的规则可能不完整”

步骤 2：分析 Git 历史质量

1. 计算范围内的提交总数
2. 计算 Conventional Commits 占比
3. 报告质量：占比越高，从中提取的规则可信度越高
4. 解析 --since 和 --scope 标记以确定分析范围

步骤 3：提取包含决策的提交

使用并行 Agent 高效分析 Git 历史（参见 REFERENCE.md）：

• Agent 1：分析 refactor: 提交中的代码风格模式
• Agent 2：分析 fix: 提交中的重复问题类型
• Agent 3：分析 feat!: 和 BREAKING CHANGE: 提交中的架构决策
• Agent 4：分析 chore: 和 build: 提交中的工具决策

按领域（代码风格、测试、API 设计等）、时间顺序（最新优先）和频率（最常见者优先）整合发现。

步骤 4：解决冲突

当多个提交涉及同一主题时：

1. 使用模式匹配检测冲突：git log --format="%H|%ai|%s" | grep "{topic}"
2. 应用解决策略：
   • 较新者覆盖较旧者：以最新决策为准
   • 频率较高者优先：如果 5 个提交支持 X，而 1 个提交支持 Y，则以 X 为准
   • 破坏性变更优先：feat!: 优先于常规提交
3. 将被覆盖的决策标记为“已取代”，并引用较新的决策
4. 通过 AskUserQuestion 向用户确认重要决策

步骤 5：在 $RULES_DIR 中生成规则

对于每项决策，使用 REFERENCE.md 中的模板生成规则文件。将每个文件写入 $RULES_DIR/<filename>.md（配置的 structure.generated_rules_path）：

1. 提取源提交、日期和类型

2. 确定置信度级别（根据提交频率和清晰度分为高／中／低）

3. 生成可执行的规则说明

4. 加入提交差异中的代码示例

5. 引用任何已被取代的早期决策

6. 必须：除非规则确实适用于所有情况，否则必须通过 paths: frontmatter 为每条生成的规则限定范围。 没有 paths: 的规则会在每个会话中加载，并污染无关工作的上下文。根据源信号选择 paths:：

   信号	来源	paths: 值
   规则正文通过“从 <path> 提取的模式”引用特定文件	步骤 3／4 冲突解决	对该文件所在目录使用 Glob：<dir>/**/*.<ext>
   规则源自 chore(deps)／build: 提交	工具决策 Agent	锁文件和清单：package.json、pyproject.toml、Cargo.toml、go.mod、*.lock、biome.json 等
   规则涉及某种语言（refactor: + 仅包含 JS 的代码块）	代码风格 Agent	语言 Glob：**/*.{js,jsx,ts,tsx}、**/*.py、**/*.rs
   规则涉及测试	测试策略 Agent	**/*.{test,spec}.*、tests/**/*、test/**/*
   规则涉及 API 端点	API 设计 Agent	src/{api,routes}/**/*、**/*controller*、**/*handler*
   规则涉及文档	文档 Agent	docs/**、**/*.md
   规则重述了全局项目上下文（已在 CLAUDE.md 中）	任意	不要生成——这是 CLAUDE.md 的职责；中止生成该规则
   规则确实适用于每个文件（例如通用的错误处理理念、安全意识）	少见	有意省略 paths:，并在规则正文中注明“全局规则”

   默认限定范围。自动推导的起点：提取规则正文中每个代码块引用的文件扩展名／目录根路径，并将其写入 paths:。写入前，请验证生成的 Glob 集确实能匹配工作树中的文件——如果匹配列表为空，说明推断的范围有误；请重新推导。

按类别生成单独的规则文件（规范文件名和默认 paths: 见 REFERENCE.md）：

• code-style.md、testing-standards.md、api-conventions.md、error-handling.md、dependencies.md、security-practices.md

步骤 6：处理与现有规则的冲突

仅检查 $RULES_DIR 下的现有规则是否存在冲突（绝不检查上级 .claude/rules/，其中可能包含与 blueprint 无关的手写内容）：

1. 如果发现冲突 → 询问用户：以 Git 派生规则覆盖现有规则，还是保留现有规则？
2. 应用用户的选择：更新、合并或分别保留
3. 在规则文件中记录冲突解决情况

步骤 7：更新任务注册表

更新 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 processed "${COMMITS_ANALYZED:-0}" \
  --argjson created "${RULES_DERIVED:-0}" \
  '.task_registry["derive-rules"].last_completed_at = $now |
   .task_registry["derive-rules"].last_result = "success" |
   .task_registry["derive-rules"].context.commits_analyzed_up_to = $sha |
   .task_registry["derive-rules"].stats.runs_total = ((.task_registry["derive-rules"].stats.runs_total // 0) + 1) |
   .task_registry["derive-rules"].stats.items_processed = $processed |
   .task_registry["derive-rules"].stats.items_created = $created' \
  docs/blueprint/manifest.json > tmp.json && mv tmp.json docs/blueprint/manifest.json

步骤 8：更新清单并报告

1. 使用派生规则的元数据更新 docs/blueprint/manifest.json：时间戳、已分析的提交、生成的规则、源提交
2. 生成完成报告，显示：
   • 已分析的提交（数量和日期范围）
   • Conventional Commits 的占比
   • 按类别生成的规则
   • 每条规则的置信度评分
   • 已解决的任何冲突
3. 提示用户选择下一步：审查规则、执行派生的开发工作流，或结束

Agent 式优化

上下文	命令
检查 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 -c "^(feat|fix|refactor)" || echo 0
提取决策类提交	git log --format="%H|%s|%b" | grep -E "(always|never|must|prefer)"
快速推导	对多领域分析使用并行 Agent（Explore）

---

有关 git 分析模式、规则模板、冲突解决和详细流程，请参阅 REFERENCE.md。