| name | git-forensics |
| description | 分析 Git 历史，发现"逻辑耦合"（总一起改的文件）和"热点"（高频修改的复杂模块）。基于 Adam Tornhill 的《Your Code as a Crime Scene》方法论。 |
考古学家手册 (The Archaeologist's Field Notes)
"历史不会重复，但会押韵。静态分析告诉你结构，Git 取证告诉你痛苦的真相。" —— Adam Tornhill
本技能基于 Adam Tornhill 的《Your Code as a Crime Scene》 方法论。
核心思想：代码的演化历史比代码本身更能揭示设计问题。
⚠️ 强制深度思考
[!IMPORTANT]
在执行任何分析之前，你必须调用 sequential thinking 工具，视情况进行 2—3 步推理。
思考内容例如：
- "这个项目的 Git 历史有多深？是否需要
git fetch --unshallow？"
- "我应该关注哪个时间范围？（最近 3 个月？1 年？）"
- "有没有明显的'噪音文件'（如
package-lock.json）需要排除？"
⚡ 快速启动
- 耦合分析:
python scripts/git_forensics.py --repo . --threshold 0.3
- 热点探测:
python scripts/git_hotspots.py --repo . --days 180
🧭 探索流程 (The Dig)
第一步：感知时间流 (The Tornhill Method)
- 老师傅箴言: "代码的价值不是它是什么，而是它是如何变成这样的。"
- 运行
git log --oneline -n 100，快速感知项目近期活跃度。
- 关键推断: 如果最近 50 次提交都只涉及一两个目录，那就是"震中"——最可能藏有风险的地方。
第二步：发现隐性耦合 (Temporal Coupling / Change Coupling)
- 核心问题: "有没有两个文件，它们在代码里没有
import/use 关系，但 70% 的提交都一起出现？"
- 老师傅警报 (来自 Adam Tornhill):
- ⚠️ 逻辑耦合但物理分离 -> 这是"架构腐烂 (Architectural Decay)"的强信号！
- ⚠️ 跨构建根的耦合 -> 如果
service/ipc.rs 总和 gui/api.ts 一起改，但它们属于不同构建根，这是版本漂移的温床！
- 处方: 要么合并它们到同一模块，要么抽象出共享的 Schema/契约层。
第三步：定位热点 (Hotspot Analysis - CodeScene Methodology)
🛡️ 老师傅守则
- 先取消浅克隆:
git fetch --unshallow。没有历史 = 没有数据 = 你是盲人。
- 过滤噪音: 忽略
package-lock.json, Cargo.lock, *.min.js, dist/ 等生成物。它们会污染你的分析结果。
- 警惕大规模重命名: 重命名 (
git mv) 会干扰追踪。如果发现诡异的耦合数据，手动检查是否是重命名导致。
- 关联构建信息: 在输出耦合对时，标注它们分别属于哪个构建根。这是连接 Git 分析和 Build 分析的关键桥梁。
📤 输出清单
- Coupling Pairs (耦合对): Score > 0.7 的文件对。标注它们的构建根。
- Cross-Root Couplings (跨根耦合): 重点标记！如果两个高耦合文件属于不同构建根，这是头号风险。
- Hotspots (热点): 高风险模块列表 (高 Churn + 高 Complexity)。
- Orphans (孤儿): 超过 1 年无人触碰的文件（知识腐烂警告）。
- Refactoring Priority: 根据 Churn/Complexity 矩阵给出建议的重构优先级。
