why

原因

通过挖掘仓库已有的记录，还原现有代码背后的推理过程：代码行的历史、提交消息、PR 讨论以及关联的问题。输出应是一段有证据支撑的故事，而不是一堆链接，更不能是猜测。

唯一不可逾越的规则：绝不编造理由。 对未经研究的代码给出听起来合理的解释，比说“记录里没有说明”更糟糕——这会让人形成错误认知。每条关于意图的说法都必须引用来源（注释、提交、PR 或问题），或者明确标注为推断。

挖掘——逐层深入，有了答案就停

只按问题所需的深度进行挖掘。一个 git log -L 就能回答大多数问题；完整挖掘只适用于影响重大的谜团。

第 0 层——代码本身

检查附近的注释、文档字符串或项目文档是否已经给出答案。如果有，引用它并停止——这说明代码库正在发挥应有的作用。

第 1 层——提交历史

查找塑造了相关代码的提交：

git log -L <start>,<end>:<file>          # full evolution of a line range
git log -L :<funcname>:<file>            # or of a function
git blame -w -C -M <file> -L <start>,<end>   # last-touch view, ignoring whitespace/moves

• Blame 显示的是最后一次修改，而不是起源——沿着 git log -L 的输出回溯到引入该决策的提交。
• 跳过表面性提交（格式调整、大规模重命名）；如果仓库中有 .git-blame-ignore-revs，请遵循它（使用 --ignore-revs-file）。
• 如果文件曾被重命名，对该文件运行普通 git log 时加上 --follow。

完整阅读相关提交消息（git show -s <sha>）。一条写得好的消息可能就能让你在此处结束挖掘。

第 2 层——拉取请求

找出合并了每个相关提交的 PR，并阅读其中的讨论：

gh api repos/{owner}/{repo}/commits/<sha>/pulls   # commit → PRs
gh pr view <number> --comments                    # body + discussion

PR 正文会解释意图；评审讨论串通常会记录被否决的具体替代方案及其原因。搜索讨论串中与相关文件和代码行有关的内容。如果远程仓库不在 GitHub 上，或者无法使用 gh，请说明无法访问 PR 层，并继续利用 git 能提供的信息进行挖掘。

第 3 层——问题

从 PR 正文和提交消息（fixes #N、closes #N、工单 ID）中追踪引用，找到最初的问题报告。“实际出了什么问题”就在这里——这往往才是“为什么这里要有这段防御性代码”的真正答案。

第 4 层——相关人员

当记录无以为继时，找出可能知情的人：引入该提交的作者、PR 评审者。检查他们目前是否仍然活跃（使用 git log --author 查看近期活动）。给用户一条措辞精确的问题，让他们去询问——挖掘结果会让问题更具体（“PR #123 添加了重试机制，但 3 次上限是后来加的，且没有解释——这是基于测量结果，还是随意定的？”）。

报告

• 按决策发生的顺序讲述：问题 → 选择 → 被替换或否决的方案 → 此后的演变。每项说法旁边都要标注来源（sha、PR/问题编号）。
• 明确区分记录与推断：“PR 说了 X”与“从差异来看，似乎是 Y——但记录没有说明”。
• 线索中断也是发现，并非失败：准确报告记录在哪一步失去信息（“由 引入，提交消息为‘fix’，没有 PR 讨论”）。

挖掘之后——把答案放在最能长久保留的地方

• 线索中断，但最终还是弄清了原因（通过推理或询问他人）：建议在承载关键逻辑的位置补上一条简洁注释——相关背景已经丢失过一次；加上注释可以避免它再次丢失。只提出建议，不要擅自修改。
• 找到了，但藏得很深（埋在三层深的评审讨论串中）：如果它足够重要，就建议同样把说明提炼为注释。否则，如果用户会运行此套件的会话循环，可以考虑在其档案中留下一行指引（“X 的背景：PR #123”）。对于不使用该循环的用户，完全跳过此项。

防护措施

• 默认只读：唯一的写入是用户接受的晋升提案，这些都是正常的工作成果——绝不要在任何提交到仓库的内容中提及此技能包或个人存储。
• 根据问题调整调查深度：第 1 层已经回答问题时，不要再查四层。
• 绝不要把猜测当作记录来呈现。“我不知道，仓库里也没有说明”是有效且诚实的回答。