--- name: why description: "用于‘X 为什么这样工作’、‘为什么选 Y’、设计理由、回归、事后分析或有数据依据的阈值。发现可用 MCP,并行查询各证据类别(源码历史、工单、长文档、即时聊天、基础设施观测、错误追踪、产品分析仓库),再给出带引用的决策与权衡解释。运行行为用 how。" disable-model-invocation: true --- # 为什么如此 在 Claude Code 中,每个会话在遵循此技能前,先阅读一次 [Claude Code 适配器](../../docs/harness/claude-code.md)。它将 pstack 技能中的 Cursor 名称映射到 Claude Code。 调查代码背后的动机和意图。配套 `how` 技能回答代码做什么、如何运作;`why` 回答哪些力量导致这种形态。 下方每次派生都指出 `pstack-models.mdc` 中的角色行和默认值。把 `model` 设为该行值;规则或行缺失时使用默认值。值为 `auto` 或 `inherit-parent` 时不设置 `model`。若 Task 拒绝标识,用默认值并说明;若默认也被拒绝,用错误消息中同系列最接近的有效标识。按 **poteto-mode** 技能“子智能体”一节,为任务选择每位子智能体的推理级别与快速或标准速度。 每次派生使用 `generalPurpose` 和 `readonly: false`(智能体模式)。**不要使用 readonly/Ask 模式。** 它会移除 MCP,禁用依赖 MCP 的调查和综合者的引用抽查。调查者仍不得写入任何内容。 ## 工作姿态 作为**认真、谨慎、精确的调查者**工作。诚实区分知道与推断。阅读 `references/epistemics.md` 获取完整置信框架与措辞指南。综合者必须遵循它。 ## 第 1 步:理解目标与问题 **目标**通常是一块代码、一种模式、一个功能或一项有名称的设计决策。**问题**通常是设计理由、权衡、触发设计的边界情况、外部约束、死代码或广泛历史调查。 目标模糊时,例如“为什么这样做”没有明确指代,依据对话背景作最佳判断,包括打开的文件、近期修改、光标位置、刚才讨论内容。简要说明理解,让用户可以纠正,然后继续。 ## 第 2 步:建立代码锚点 派调查者前,直接建立种子背景:文件路径与行范围、关键符号(函数、类、常量)、最近触及目标的若干提交、合并提交中的 PR 号(主题行中的 `(#1234)`),以及关联工单 ID。运行 `git blame -L , ` 查看最近触及提交,`git log --follow -p -- ` 查看跨重命名的完整补丁历史,`git log --oneline -20 -- ` 查看带 PR 号的近期提交,`git log -1 --format=%B ` 提取 PR 号。随后拉取每个实质提交的 PR 正文与讨论:`gh pr view --json title,body,author,createdAt,mergedAt,labels,closingIssuesReferences,comments,reviews`。将该锚点交给每位调查者和综合者。 ## 第 3 步:派出并行调查者 **默认进行完整并行调查。** 目标是完整覆盖图,不是最小覆盖。记录空结果,不跳过搜索。 ### 发现能力 派生前,列出 Cursor 环境中的可用 MCP。有可用工具映射就使用;否则检查 Cursor 暴露的已启用 MCP 服务器 `mcps/` 目录。 把每个可用 MCP 映射到一种证据类别: 1. 源码控制历史 2. 问题或工单跟踪器 3. 长文档 4. 团队即时聊天 5. 基础设施可观测性 6. 错误或异常追踪 7. 产品分析数据仓库 源码历史始终可经 git 和 `gh` 获取。其余六种按 MCP 名称、服务器说明、工具名和资源描述分类。MCP 可匹配多类时,选其主要证据所属类。在覆盖图记录有歧义的情况。 对每个具有匹配 MCP 的类别派一位调查者,在同一消息中启动以便并发,各自只负责一个工具或 MCP。不要让一个智能体覆盖多个 MCP。`model` 使用 `why investigators` 行,默认 `grok-4.7-xhigh-fast`。 每位调查者的提示是填好的 `references/investigator-prompt.md`,再附: - 所选 MCP 的类别手册 `references/sources/.md`,按 `references/source-playbook.md` 示例适配。 - **目标代码看起来具有防御性**时附 `references/sources/incident-postmortem.md`,包括空值检查、重试逻辑、超时处理、限流、功能开关、出口防护、OOM 处理。 - 代码锚点和用户原始问题。 ### 调查者名单:每个可用证据类别一位 下方每类都有独特优势,“最擅长”之后指出其能揭示的“为什么”。用它预判结果、在类别返回空时命名缺口,并且仅在少见的可证明无关情形下解释跳过。 1. **源码控制**(git 历史、用 `gh` 获取 PR、代码注释、测试)。始终派出,唯一保证存在的来源。最擅长*审查期间记录的实现时理由*。 2. **问题或工单跟踪器**(例如 Linear、Jira、GitHub Issues、Plane、Shortcut MCP)。最擅长*迫使变化的产品或商业因素*,理由来自工程之外时最强。 3. **长文档**(例如 Notion、Confluence、Google Docs、Coda MCP)。最擅长*在变成代码前写下的长篇设计理由*。 4. **团队即时聊天**(例如 Slack、Discord、Microsoft Teams、Mattermost MCP)。最擅长*从未进入文档的实时讨论*。源码、工单和文档轨迹稀薄时尤其重要。 5. **基础设施可观测性**(例如 Datadog、New Relic、Honeycomb、Grafana、Splunk MCP)。最擅长*促成代码的基础设施和运行时现实*。目标响应基础设施信号,如超时、重试、限流、熔断时最强。 6. **错误或异常追踪**(例如 Sentry、Rollbar、Bugsnag、Airbrake MCP)。最擅长*促成防御或修正代码的具体异常和错误轨迹*。适用于 catch 块、空值防护、类型检查、重试及其他防御。 7. **产品分析数据仓库**(例如 Databricks、Snowflake、BigQuery、ClickHouse、dbt、Redshift MCP)。最擅长*塑造代码的产品和数据现实*。适用于开关控制代码、实验驱动交付、数据迁移、“这个数字从哪里来”。 ### 何时跳过调查者 只有提供**明确书面理由**,并写进最终“查阅来源”时才可跳过。两种有效理由: - **环境中没有对应类别的 MCP。** 标为缺口,不是选择:“跳过团队即时聊天。没有可用匹配 MCP,因此无法搜索对话记录。” - **来源可以证明无关**,而非“可能无关”。门槛很高:“跳过错误或异常追踪。目标是构建时脚本,没有运行时代码路径。” 若范围判断认为目标只是一个提交的琐碎改动,且 PR 描述已经完整回答,只有在确认七个可用类别的搜索全部冗余后,才可直接回答,并明确说明。应当少见。 ## 第 4 步:综合 派一位综合者。`model` 使用 `why synthesizer` 行,默认 `claude-opus-5-5-xhigh`。给予: 1. 调查发现,包括空结果与有理由跳过的类别。 2. 代码锚点。 3. 用户原始问题。 4. `references/epistemics.md` 中的置信框架。 5. `references/synthesizer-prompt.md` 中的综合提示模板。 ## 第 5 步:展示 向用户展示综合者输出。可为清晰度轻微编辑或补充对话背景,但**不要改写置信措辞**。 ## 输出格式 结构遵循 `references/synthesizer-prompt.md`:问题、相关代码、发现的事实、可以合理推断的内容、竞争性假设、未知项、查阅来源、置信总结。按需要适配,但保持置信分离;“查阅来源”按调查者一行,包含返回空和跳过的调查者及原因。 “查阅来源”之后,如果用户问“为什么”是为了随后修改代码,把历史发现转成规划约束集:保留 / 改变 / 避免 / 风险。 ## 应避免的常见失败 - **近因偏差。** 假定最近提交最权威。当前形态通常积累了许多更早决策,应向前追溯。