如何用repowise挖掘架构决策:get_why带你搞懂代码为什么这么写

原创2026-09-22 13:13:331,682 阅读

如何用repowise挖掘架构决策:get_why带你搞懂代码为什么这么写

Repowise 是一款代码库智能分析工具,它为 AI 和人类同时提供代码健康分、自动生成文档、Git 分析与死代码检测能力。其中最有意思的功能之一,是通过 MCP 工具 get_why 挖掘架构决策——把"这段代码为什么这么写"背后的 ADR、提交记录和设计理由,直接问出来。

repowise 架构决策与代码智能看板演示

为什么"为什么"比"是什么"更难答

接手一个老项目时,你很快能知道代码是什么:搜一下就能找到实现。但真正卡住新人的,永远是为什么——

  • 为什么认证用 JWT 而不是 Session?
  • 为什么这个缓存和淘汰路径拆成了两个模块?
  • 这段看起来很怪的写法,是 bug 还是刻意为之?

这些信息散落在 ADR 文档、PR 描述、squash 提交正文,甚至某位同事当年随手写的一行 # WHY: 注释里。get_why 做的,就是把这些"为什么"统一挖掘出来,变成可检索、可追问的结构化答案。

get_why 是什么:一个 MCP 工具,四种问法

get_why 是 Repowise MCP 服务内置的工具之一,专门回答"代码为什么长成这样"。它支持四种查询模式,按你传入的参数自动切换:

模式 怎么传参 返回什么
💬 自然语言提问 get_why(query="为什么认证用 JWT?") 关键词 + 语义匹配的决策记录
📁 文件路径 get_why(query="src/auth/service.py") 该文件受哪些决策约束 + 起源故事 + 一致性评分
🎯 目标锚定搜索 get_why(query="为什么加缓存?", targets=["src/cache"]) 涉及目标文件的决策会被提权
📊 健康看板 get_why()(不传参) 过期决策、冲突项、无决策覆盖的热点文件

两个值得注意的细节:

  1. 答案永不为空。如果某个文件路径下没有任何决策记录,get_why 会自动回退到 Git 考古(提交历史 + 交叉引用),并明确告诉你这是"重建"的而不是"记录"的答案。
  2. 每条结论都标注可信度。返回结果里的 answer_basis 会说明这条答案最依赖哪条证据链;只有 accepted(有人确认过)的决策才算"判决",其余都只是供你权衡的证据。

决策从哪来:五个挖掘源

Repowise 在索引阶段就会从 5 个来源挖掘决策,你不需要额外配置:

  • 📄 ADR 文件——仓库里的架构决策记录文档
  • 🌿 PR 与 squash 提交正文——合并说明里写着的设计理由
  • 🏷️ 内联标记——# WHY:、# DECISION:、# TRADEOFF:、# ADR: 这类注释
  • ⛏️ Git 考古——从提交历史重建"这个文件是怎么演变成今天这样的"
  • 💬 代码注释——受关键度约束的高价值注释

每条理由都会追溯到一段逐字引用的原文,并打上"精确 / 模糊 / 未验证"的标记,所以答案不会凭空捏造。

动手实践:从 init 到第一次提问

整个上手过程只需要两步:

第一步:初始化索引

在你的 git 仓库根目录运行(首次会建立 .repowise/ 索引目录):

repowise init --index-only --yes

决策挖掘作为索引流程的一部分自动执行,无需单独的 LLM 密钥。

第二步:开始提问

CLI 里的 repowise why 命令就是 get_why 的适配器,可以直接在终端提问:

repowise why "为什么认证用 JWT?"        # 自然语言提问
repowise why src/api/auth.py            # 查某个文件受哪些决策约束
repowise why                            # 查看决策健康看板

如果你接入了 Claude Code 或 Codex,它们会通过插件里的 architectural-decisions 技能自动调用 get_why——当你问"这个功能当初为什么这么设计"或准备做架构改动时,AI 会先查决策记录,避免无意中推翻既有设计。

repowise 架构决策图谱页面:以社区聚类展示模块间的依赖关系

三种记录别混淆:机器不能替你"拍板"

Repowise 刻意区分三层,这也是理解决策挖掘的关键:

层级 含义 机器能创建? 有约束力?
Episode 有据可查的事件(一段对话、一次提交) ✅ ❌
Candidate 从证据推断出的"候选决策" ✅ ❌
Decision 你确认过的约束 ❌(只有你确认后才算) ✅

只有第三层会进入 AI 的上下文、参与一致性评分。换句话说:机器负责把线索挖出来摆到你面前,拍板权永远在人。确认一条候选决策的命令:

repowise decision candidates              # 查看待审核清单
repowise decision confirm <id> --scope packages/core   # 确认并指定作用范围
repowise decision health                  # 过期 / 冲突 / 未治理热点

确认后的决策会导出到版本控制的 .repowise/decisions.yaml,随仓库分发给每位同事。

什么时候该用 get_why?

三个高频场景,都建议在动手之前先问一句:

  1. 重构之前 🛠️——先看目标文件受哪些决策约束(路径模式自带"一致性评分",告诉你文件是否还在遵守自己的 ADR)。
  2. 接手陌生代码时 🗺️——路径模式返回的"起源故事"相当于该文件的编年史。
  3. 让 AI 改架构时 🤖——AI 编码助手会先调用 get_why 检查是否会违背既有决策,若发现冲突会先向你提示而不是直接照做。

repowise PR 影响范围分析图:展示改动波及的代码区域

相关文档路径

想深入了解,可以按图索骥:

代码会告诉你"是什么",而 get_why 告诉你"为什么"——把团队多年积累的隐性设计知识,变成一次查询就能拿到的显性答案。

登录后查看全文
repowise