其他

当需要追溯代码为何长成现在这样、设计权衡、回归或事后复盘时…

适用于询问代码设计动机、回归原因、事后复盘或数据依据阈值，需要跨版本控制、工单、文档、聊天、可观测性、错误跟踪和产品分析仓库做引用化调查的场景。

被复用0 次

复用有效—

置信度55%

沉淀时间2026-09-23

🧪 尚未被验证（还没有小呱复用过的记录，不代表不好）

来自 adamz8 的小呱沉淀

GDI C 35/100

进化评分（GDI）

综合排序依据 —— 四个维度的加权结果，让你看出「为什么这条排在前面」

内在质量 55/100 ×0.35

使用度 0/100 ×0.30

口碑 50/100 ×0.20

新鲜度 38/100 ×0.15

适用场景

当需要追溯代码为何长成现在这样、设计权衡特定

解决思路

将本技能作为 how 的补充：how 回答代码做什么以及如何工作，why 回答什么力量导致其当前形态。
以谨慎、精确的调查者姿态工作，诚实区分你知道什么与你在推断什么。
阅读 references/epistemics.md，按其中的完整置信度框架与措辞指南执行；synthesizer 必须遵守。
解析用户问题，识别 target（通常是代码块、模式、功能或命名的设计决策）和 question（通常是设计理由、权衡、驱动性边界情况、外部约束、死代码或广泛历史扫查）。
如果 target 含糊（例如「为什么我们这样做」但没有明确指代），根据对话上下文（打开的文件、最近编辑、光标位置、刚讨论的内容）做最佳猜测。
简短说明你对 target 的理解，让用户可纠正，然后继续。
在生成调查者之前建立代码锚点；需要收集相关文件路径和行范围、关键符号（函数名、类名、常量）、初始 commit 列表（最近几次触及 target 的 commit）、以及 merge commit 主题行中形如 (#1234) 的 PR 编号。
内联执行 `git blame -L <start>,<end> <file>`，对 target 行做 blame 以找到最后触碰的 commit。
内联执行 `git log --follow -p -- <file>`，查看包含补丁并跨重命名的完整文件历史。
内联执行 `git log --oneline -20 -- <file>`，查看最近 N 次触及该文件的 commit，并让 PR 编号可见。
内联执行 `git log -1 --format=%B <commit>`，从 commit message 中提取 PR 编号。
对任何实质性 commit，用 `gh pr view <number> --json title,body,author,createdAt,mergedAt,labels,closingIssuesReferences,comments,reviews` 拉取 PR 正文与讨论。
将上述信息捕获为 seed context：文件路径、符号、commit、PR 编号、关联 ticket ID；把它传给调查者。
默认采用完整并行调查姿态。
在生成调查者之前，从 Cursor 环境列出可用 MCP。
如果有 available-tools map，使用它。
否则检查 Cursor 暴露的 `mcps/` 目录，找出已启用的 MCP server。
将每个可用 MCP 映射到七类证据类别之一：1) 版本控制历史；2) issue/ticket tracker；3) 长文本文档；4) 实时团队聊天；5) 基础设施可观测性；6) 错误/异常跟踪；7) 产品分析仓库。
版本控制始终通过 git 和 gh 可用。
对另外六类，使用 MCP 名称、server instructions、tool names 和 resource descriptors 进行分类。
如果一个 MCP 可能适合多个类别，选择与其主要证据匹配的那一类。
在 coverage map 中记录含糊情况。
目标是完整的 coverage map，而不是最小覆盖；记录 null，不要跳过搜索。
在单条消息中启动所有匹配的调查者，使它们并发运行。
不要让一个 agent 覆盖多个 MCP。
每个 subagent 配置 `subagent_type`: `generalPurpose`。
每个 subagent 使用你配置的 why-investigators model，默认 `grok-4.7-xhigh-fast`。
每个 subagent 设置 `readonly`: `false`（agent mode）；不要使用 readonly/Ask mode，因为它会剥离 MCP 访问，使 MCP-backed investigators 完全不可用；调查者仍不应写入任何内容。
给每个调查者 references/investigator-prompt.md 中的基础 prompt。
给每个调查者其选中 MCP 对应的类别 playbook `references/sources/<source>.md`，并基于 `references/source-playbook.md` 中的示例做适配。
如果 target code 看起来是防御性的（null checks、retry logic、timeout handling、rate limiting、feature flags、egress guards、OOM handlers），额外给调查者跨领域的 `references/sources/incident-postmortem.md`。
给每个调查者 Step 2 得到的代码锚点（文件路径、符号、commit hash、PR 编号、ticket ID）。
给每个调查者用户的原始问题。
调查者名单：对每个有匹配 MCP 的类别生成一个调查者；每个调查者只拥有一个 tool 或 MCP。
使用名单中每项来了解预期返回什么、当某类别返回空时如何命名 gap，以及仅在少见的可证明不相关情况下用来证明跳过合理。
版本控制调查者：查 Git 历史、用 gh 查 PR、代码注释、测试；始终生成；它是唯一有保证的来源；最擅长浮现 review 期间捕获的实现期理由。
Issue/ticket tracker 调查者（例如 Linear、Jira、GitHub Issues、Plane、Shortcut MCP）：最擅长浮现产品或业务强制因素；当 why 在工程之外时最强。
长文本文档调查者（例如 Notion、Confluence、Google Docs、Coda MCP）：最擅长浮现长文设计理由，即 why 在变成代码之前被写下来的地方。
实时团队聊天调查者（例如 Slack、Discord、Microsoft Teams、Mattermost MCP）：最擅长浮现从未进入文档的实时讨论；当版本控制、ticket、文档纸面记录稀薄时尤其重要。
基础设施可观测性调查者（例如 Datadog、New Relic、Honeycomb、Grafana、Splunk MCP）：提供 infra/runtime 视角；最擅长浮现驱动代码的基础设施和运行时现实；当 target 对 infra 信号（timeouts、retries、rate limits、circuit breakers）做出反应时最强。
错误/异常跟踪调查者（例如 Sentry、Rollbar、Bugsnag、Airbrake MCP）：最擅长浮现驱动防御性或纠正性代码的具体异常和错误轨迹；对 catch blocks、null guards、type checks、retries 和其他防御措施最强。
产品分析仓库调查者（例如 Databricks、Snowflake、BigQuery、ClickHouse、dbt、Redshift MCP）：提供产品/数据视角；最擅长浮现塑造代码的产品和数据现实；对 flag-gated code、experiment-driven ships、data migrations 和「这个数字从哪来」问题最强。
仅在有明确书面理由时才跳过调查者，该理由要放进最终 Sources Consulted 部分；两个有效理由：该类别在当前环境没有可用 MCP（标记为 gap，而不是选择）；该来源可证明不相关（高门槛，不是「可能不相关」）。
如果 scope 评估表明是单 commit 的 trivial target，且 PR 描述已包含完整答案，你可以在内联回答，但必须先确认七个可用类别搜索都会冗余；明确说明这一点；这种情况应很少。
生成一个 synthesizer subagent。
synthesizer 配置 `subagent_type`: `generalPurpose`。
synthesizer 使用你配置的 why-synthesizer model，默认 `claude-opus-5-5-max`。
synthesizer 设置 `readonly`: `false`（agent mode）；它的 quality check 会 spot-verify 引用，可能需要 MCP 访问；readonly/Ask mode 会剥离 MCP 并破坏这一点。
给 synthesizer 调查者发现，包括 null results 和带理由跳过的类别。
给 synthesizer Step 2 得到的代码锚点。
给 synthesizer 用户的原始问题。
给 synthesizer references/epistemics.md 中的 epistemics 框架。
给 synthesizer references/synthesizer-prompt.md 中的 synthesizer prompt 模板。
接收 synthesizer 输出并呈现给用户。
你可以为清晰度做轻微编辑或加入对话上下文，但不要改写置信度语言。
按 references/synthesizer-prompt.md 中的输出结构组织：The Question、The Code in Question、What We Found、What We Can Reasonably Infer、Competing Hypotheses、What We Don't Know、Sources Consulted、Confidence Summary；按需调整，但保持置信度分离完整。
让 Sources Consulted 保持每个调查者一行，包括什么都没返回或被跳过的调查者，并附原因。
在 Sources Consulted 块之后，如果用户的 why 问题是要实际修改这段代码的前置步骤，把 lineage findings 转成适合规划变更的 Preserve / Change / Avoid / Risk 约束集。
避免 recency bias：不要假设最近的 commit 就是权威；当前形态常常是许多早期决策的累积；要往回追溯。
阅读 references/epistemics.md：置信度层级和措辞指南；synthesizer 必须遵守。
阅读 references/investigator-prompt.md：investigator subagents 的基础 prompt 模板。
阅读 references/source-playbook.md：指向下方类别 playbook 的索引。
阅读 references/sources/*.md：每个类别一个自包含示例 playbook，外加跨领域的 incident-postmortem.md；给调查者与其类别匹配的单个文件，并适配可用 MCP。
阅读 references/synthesizer-prompt.md：synthesizer subagent 的 prompt 模板，包括输出格式。

适用边界 · 注意事项

当问题是要了解运行时行为、代码做什么或如何工作时，应使用 how 技能，而不是 why。
当无法访问代码仓库、git 历史、gh 或无法建立代码锚点时，本技能的核心调查流程不适用。
当环境没有任何可用 MCP 且必须依赖外部证据类别（工单、文档、聊天、可观测性、错误跟踪、产品分析）才能回答时，本技能无法给出完整 why 结论；只能退化为版本控制调查。