如何用repowise挖掘架构决策:get_why带你搞懂代码为什么这么写
如何用repowise挖掘架构决策:get_why带你搞懂代码为什么这么写
Repowise 是一款代码库智能分析工具,它为 AI 和人类同时提供代码健康分、自动生成文档、Git 分析与死代码检测能力。其中最有意思的功能之一,是通过 MCP 工具 get_why 挖掘架构决策——把"这段代码为什么这么写"背后的 ADR、提交记录和设计理由,直接问出来。
为什么"为什么"比"是什么"更难答
接手一个老项目时,你很快能知道代码是什么:搜一下就能找到实现。但真正卡住新人的,永远是为什么——
- 为什么认证用 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()(不传参) |
过期决策、冲突项、无决策覆盖的热点文件 |
两个值得注意的细节:
- 答案永不为空。如果某个文件路径下没有任何决策记录,
get_why会自动回退到 Git 考古(提交历史 + 交叉引用),并明确告诉你这是"重建"的而不是"记录"的答案。 - 每条结论都标注可信度。返回结果里的
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 刻意区分三层,这也是理解决策挖掘的关键:
| 层级 | 含义 | 机器能创建? | 有约束力? |
|---|---|---|---|
| Episode | 有据可查的事件(一段对话、一次提交) | ✅ | ❌ |
| Candidate | 从证据推断出的"候选决策" | ✅ | ❌ |
| Decision | 你确认过的约束 | ❌(只有你确认后才算) | ✅ |
只有第三层会进入 AI 的上下文、参与一致性评分。换句话说:机器负责把线索挖出来摆到你面前,拍板权永远在人。确认一条候选决策的命令:
repowise decision candidates # 查看待审核清单
repowise decision confirm <id> --scope packages/core # 确认并指定作用范围
repowise decision health # 过期 / 冲突 / 未治理热点
确认后的决策会导出到版本控制的 .repowise/decisions.yaml,随仓库分发给每位同事。
什么时候该用 get_why?
三个高频场景,都建议在动手之前先问一句:
- 重构之前 🛠️——先看目标文件受哪些决策约束(路径模式自带"一致性评分",告诉你文件是否还在遵守自己的 ADR)。
- 接手陌生代码时 🗺️——路径模式返回的"起源故事"相当于该文件的编年史。
- 让 AI 改架构时 🤖——AI 编码助手会先调用
get_why检查是否会违背既有决策,若发现冲突会先向你提示而不是直接照做。
相关文档路径
想深入了解,可以按图索骥:
- 架构决策层完整说明:docs/layers/DECISIONS.md
get_why的 MCP 工具参考:docs/agent/MCP_TOOLS.md- CLI 命令(
repowise why各模式):plugins/shared/commands/why.md - 决策功能示例走读:examples/decisions/README.md
- 工具实现源码:packages/server/src/repowise/server/mcp_server/tool_why.py
代码会告诉你"是什么",而 get_why 告诉你"为什么"——把团队多年积累的隐性设计知识,变成一次查询就能拿到的显性答案。


