【免费下载链接】repowiseCodebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.项目地址https://gitcode.com/gh_mirrors/re/repowise点击查看免费下载Repowise 的架构决策Architectural Decisions能力把代码仓库中的为什么沉淀为可检索、可追踪、可审计的决策记录ADR并暴露为 MCP 工具get_why、CLI 命令repowise why与repowise decision让 AI Agent 和人类都能在改动代码前先弄清既有设计意图。本文以 Claude Code 技能文件 architectural-decisions/SKILL.md 为主线完整展开get_why的四种调用模式、决策来源与证据可信度标注机制并结合仓库源码说明底层实现原理读完你可以直接在 Claude Code 会话里用get_why做重构前决策核查用repowise decision管理决策的录入、确认与健康巡检。为什么需要架构决策检索从 WHY 到可验证证据普通的代码检索回答这里是什么架构决策检索回答这里为什么是这样。在 Repowise 索引过的仓库目录中存在.repowise/里每一次架构取舍——选型、重构、模式确立——都能被捕获为一条决策记录并且每条决策的理由都追溯到一段逐字可查的源码片段被打上exact精确/fuzzy模糊/unverified未验证的可信度印章SKILL.md 原文Each rationale traces to a verbatim source span, stamped exact / fuzzy / unverified。这套能力的价值体现在两个典型场景改代码之前在重构、引入新模式、在两个方案之间做选择之前先查这块区域有没有已记录的决策若有先展示给用户因为用户可能并不想推翻一个已经定下的架构选择。问为什么用户直接问为什么 X 是这样实现的Agent 用一句话或一个文件路径即可命中对应决策与佐证。SKILL.md 的触发条件也很明确当遇到为什么代码要以某种方式构建的问题、准备做架构变更、或用户询问某个 Repowise 索引代码库的设计理由时启用同时当提交信息或代码注释中出现WHY:、DECISION:、TRADEOFF:、ADR:这类决策信号时也会自动激活。get_why 的四种模式按传入参数自动分发get_why是 MCP 服务器暴露的决策检索工具根据你传入的参数不同它自动切换到四种模式之一。四种模式都在 tool.py 中完成参数分发。模式一自然语言问题 → 关键词 语义决策搜索get_why(querywhy is auth using JWT?)当query不是路径时进入搜索模式_why_search见 search.py先对全量决策语料做关键词排序_rank_keyword_matches再把同一决策的重复表述折叠_collapse_restatements同时用一次向量嵌入并行拉取语义命中的决策与相关文档_semantic_lanes见 search.py。语义窗口按命名空间切分决策与文档不会互相污染向量库不可用时自动回退到词法索引FTS。模式二文件路径 → 管辖决策 起源故事 对齐度get_why(querysrc/auth/service.py)当query是一个路径时进入路径模式_why_path见 path_mode.py返回三样东西管辖该文件的决策governing decisions只有 scope 能绑定到该文件或所在模块、且状态为accepted的记录才算管辖从未被接受的记录归入candidates相当于评审请求而非规则曾经生效后来被取代/撤回的记录归入retired/history历史而非规则。三者分开呈现避免评审请求被误读为规则见 path_mode.py。起源故事origin story文件的主要作者、总提交数、首末提交、仓库年龄以及关键提交列表——它是证据而不是指令。对齐度alignment score一个覆盖率数值衡量这个文件如今是否仍然遵循它自己的 ADR。对齐度是基于该路径命中的全部记录与全量决策语料计算的而不是基于被截断后的头部见 path_mode.py。值得注意的一个细节路径模式下还会对排在第一位的管辖决策额外做一次 git 询问生成一句still_true这条决策现在是否仍然成立的自然语言判断见_stamp_still_truepath_mode.py因为排第一的决策正是读者会去执行的那条。模式三问题 目标锚定 → 定向增强搜索get_why(querywhy was caching added?, targets[src/auth/cache.py])在搜索模式之上叠加targets参数决策命中会因触及目标文件而获得加权同时为每个目标生成一张目标卡片target_context卡片上区分governing_decisions仅接受过的规则与candidate_decisions未接受的候选当某个目标没有任何已接受决策管辖时卡片会回退到 git 考古证据见_target_cardpath_mode.py。当targets与无query组合时还有一种隐式用法只传targets[src/auth/cache.py]等价于直接询问这些文件本身单目标时直接复用完整的路径模式多目标时逐卡呈现。模式四无参数 → 决策健康仪表盘get_why()不传任何参数时返回决策健康仪表盘_why_health_dashboard见 dashboard.py三类重点一目了然仪表盘区块含义stale_decisions可能已不再适用的过时决策含staleness_score与受影响文件proposed_awaiting_review等待确认的提议决策含来源与置信度ungoverned_hotspots无任何已记录决策管辖的高变更文件热点conflicts/retired_decisions/unscoped_decisions冲突决策、已撤回决策、未限定范围文件的决策实现层面仪表盘调用get_decision_health_summary一次性聚合上述所有通道dashboard.py并在输出前对每个区块做数量上限截断截掉的部分以计数 恢复方式recall的形式保留确保调用方知道还有更多内容。模式零按 ID 或证据引用直接查询get_why还支持id与reference参数传决策 ID 或ev_...证据 ID 直接取回单条记录结构化引用reference里的id与repository会由工具自行补齐调用方无需手工翻译见 tool.py。决策从哪里来五种挖掘来源SKILL.md 明确列出决策的五个来源仓库源码逐一印证ADR 文件扫描仓库根锚定的常规 ADR 目录adr、adrs、docs/adr、docs/adrs、doc/adr等以及松散命名的*adr*.md文件解析 Nygard/MADR 章节标题与 front-matter 状态映射见 adr.py。仓库核心目录中packages/core/src/repowise/core/analysis/decisions/下的adr.py即为此挖掘器。PR 与 squash 提交正文从合并请求正文与压缩提交的详细说明中提取决策描述。内联标记代码里的# WHY:、# DECISION:、# TRADEOFF:、# ADR:注释见 SKILL.md 的 When a file has decision markers 一节。git 考古当某路径不存在任何决策记录时get_why回退到 git 考古_git_archaeology_fallback从文件自身关键提交、交叉引用和实时git log三个层面兜底保证调用永不落空见 path_mode.py。中心度受限的代码注释按中心度边界centrality-bounded限定范围挖掘强标记的 rationale 注释code_rationale通道。搜索模式下当没有任何记录越过相关性阈值时回答同样不会为空先在全仓库挖掘携带问题关键词的强标记 rationale 注释其次是与问题同词的提交历史_question_lanes见 search.py——但明确标注它们是历史而非已陈述的理由。证据可信度与响应结构回答落在哪条答案通道上get_why的响应不是简单把几条记录堆给你它明确回答我的答案建立在什么之上每条决策行都带authority字段accepted表示有人正式确认过签名生效candidate表示至今无人确认只是评审请求。answer_basis字段命名最强的那条答案通道decision决策唯一算裁定的通道、episode事件记录、rationale代码内 rationale 注释、archaeologygit 考古、documentation文档、candidate候选最弱——意味着没有任何记录越过确认门槛。_stamp_answer_basis在所有模式出口统一盖章见 tool.py。证据行自带provenance与evidence_refs相同的 ID 意味着共享同一份证据而非独立的交叉印证——这一点在 tool.py 的工具 docstring 里明确警示防止 Agent 把同一证据出现两次误当两处独立佐证。CLI 与插件入口repowise why / decision / 技能脚本repowise whyget_why 的 CLI 适配器repowise why是对get_why工具的薄封装why_cmd.py# 问一个为什么 repowise why why is auth using JWT? # 查某条路径的管辖决策 起源 对齐度 repowise why src/auth/service.py # 问题锚定目标文件可重复 repowise why why was caching added? --target src/auth/cache.py # 不带参数决策健康仪表盘 repowise whyCLI 投影projection会做三件事默认截断长列表到头部 5 条并保留总数5 of 18 shown保留source/provenance/evidence_refs/restates等证据契约字段并用--full参数放行全部字段含 context、consequences、alternatives、lineage、staleness_score 等默认裁剪掉的细节。git 考古块按file_commits、git_log、cross_references三层分别截断呈现每层同样带总数。repowise decision决策生命周期管理repowise decision是完整的决策命令组decision_cmd.py与get_why形成查询—管理闭环repowise decision add正式录入一条决策。SKILL.md 建议的形式化录入路径即此命令见 SKILL.md 的 Recording new decisions 一节决策录入后处于候选candidate状态需要确认才生效。repowise decision confirm id --scope path确认接受一条候选决策使其成为管辖规则。代理Agent只有在仓库显式允许的情况下才能代为确认且需传--agent slug避免把机器人的接受记录在人的名下见 path_mode.py 的候选提示文案。repowise decision health决策健康巡检与get_why()仪表盘同一套信号。Claude Code 插件与斜杠命令在 Claude Code 插件plugins/claude-code中同一能力还以斜杠命令形式出现/repowise:why——get_why适配器任务中途随时问为什么/repowise:decision—— 决策健康概览repowise decision confirm—— 审查自动提议的决策。此外SKILL.md 本身作为 Claude Code 技能architectural-decisionsuser-invocable: false即由场景自动激活而非用户手动召唤存在技能描述中明确声明激活条件包括决策信号注释与.repowise/索引目录的存在见 SKILL.md。实战建议改代码前的标准核查流程把 SKILL.md 的指引整理成一个可复用的工作流改动前必查调用get_why(querythe specific area youre changing)找出管辖该区域的既有决策。有决策 → 先展示把找到的决策完整呈现给用户再继续用户可能不想推翻既有架构选择。无决策 → 继续但注明可以继续改动但明确标注该区域没有已记录的决策管辖——这一标注本身就有价值它同时意味着该区域是潜在的未管辖热点。会话中产生新决策 → 建议记录当用户在本轮对话中做出了架构取舍主动建议要记录这条决策吗在相关代码里加一条# DECISION:注释或运行repowise decision add正式捕获它。看到决策标记注释 → 取全量上下文若代码中出现# WHY:、# DECISION:、# TRADEOFF:、# ADR:调用get_context(targets[that_file.py])查看带上下文与受影响模块的完整决策记录。局限与边界什么不该信、什么不能做candidate不是规则answer_basis为candidate时意味着没有任何记录越过确认门槛这是最弱的答案通道未接受的候选决策是评审请求不能当作约束来执行。证据 ID 相同 ≠ 独立佐证相同evidence_refs只代表共享同一份证据Agent 不应据此得出两处独立印证的结论。代理确认受限Agent 默认不能代替人确认决策只有仓库显式允许时才可且必须传--agent参数。前置条件本能力面向 Repowise 索引过的仓库存在.repowise/目录且决策/语义检索依赖索引内容与可选的向量存储没有向量库时语义通道自动降级为词法检索能力相应收窄。深入阅读技能定义全文plugins/claude-code/skills/architectural-decisions/SKILL.mdMCP 工具实现与参数分发packages/server/src/repowise/server/mcp_server/tool_why/tool.py搜索 / 路径 / 仪表盘三种模式search.py、path_mode.py、dashboard.pyADR 挖掘与决策生命周期packages/core/src/repowise/core/analysis/decisions/adr.py、decision_cmd.pyCLI 适配器与响应投影why_cmd.pyAPI 客户端决策接口packages/api-client/src/decisions.ts赞分享【免费下载链接】repowiseCodebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.项目地址https://gitcode.com/gh_mirrors/re/repowise点击查看免费下载相关推荐如何用repowise挖掘架构决策get_why带你搞懂代码为什么这么写如何用repowise挖掘架构决策get_why带你搞懂代码为什么这么写 Repowise 是一款代码库智能分析工具它为 AI 和人类同时提供代码健康分、自Lynx Image Service 鸿蒙平台图片加载服务深度解析架构、安装与源码实现Lynx Image Service 鸿蒙平台图片加载服务深度解析架构、安装与源码实现 Lynx Image Service 是 Lynx 框架面向 HarmRepowise Why 深度指南用决策记录、意图溯源与 Git 考古回答代码为什么长这样Repowise Why 深度指南用决策记录、意图溯源与 Git 考古回答代码为什么长这样 repowise why 是 Repowise 代码库情报系统上一篇5步实战从零开始为BambuStudio 3D切片软件贡献代码下一篇Adopt-a-Hydrant性能优化Skylight监控与Rails应用调优技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
