SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场why

why

编程与开发

查看项目

更新于 10-15 16:28

技能介绍

用途

why 用于调查代码背后的动机与意图。它回答的是“什么力量塑造了代码现在的形态”，而不是“代码做了什么、如何工作”——后者由配套的 how 技能负责。典型问题包括：设计理由、权衡取舍、驱动性的边界情况、外部约束、死代码，或大范围的历史梳理。

主要能力

  • 建立代码锚点：收集文件路径与行范围、关键符号（函数、类、常量）、最近触及目标的提交、合并提交中的 PR 编号（主题行形如 (#1234)）、以及关联的工单 ID。
  • 发现可用 MCP：通过系统提示顶部的工具列表（每个 MCP 以 mcp__<server>__<name> 前缀出现）、插件/项目中的 .mcp.json，或运行 claude mcp list 来列出可用 MCP。
  • 按证据类别映射 MCP：源代码控制历史、工单/问题追踪、长文档、实时团队聊天、基础设施可观测性、错误/异常追踪、产品分析仓库。源代码控制始终通过 git 和 gh 可用。
  • 并行派出调查员：每个有匹配 MCP 的类别派出一名调查员，在单条消息中并发运行，每人只负责一个工具或 MCP。
  • 综合结论：由一名综合者汇总调查发现（包括空结果和跳过项），输出区分置信度的报告。

使用方式

  1. 理解目标与问题：目标通常是代码块、模式、功能或具名设计决策；问题通常是设计理由、权衡、驱动性边界情况、外部约束、死代码或历史梳理。若目标含糊，从对话上下文（打开的文件、最近编辑、光标位置、刚讨论的内容）做最佳猜测，简要说明解释后继续。
  2. 建立代码锚点：运行 git blame -L <start>,<end> <file> 获取最后触及的提交，git log --follow -p -- <file> 获取含重命名的完整历史与补丁，git log --oneline -20 -- <file> 获取带 PR 编号的近期提交，git log -1 --format=%B <commit> 提取 PR 编号。随后用 gh pr view <number> --json title,body,author,createdAt,mergedAt,labels,closingIssuesReferences,comments,reviews 拉取 PR 正文与讨论。该锚点会传给每位调查员和综合者。
  3. 并行调查：默认进行完整的并行调查，目标是完整的覆盖图而非最小覆盖。记录空结果，不要跳过搜索。
  4. 综合：综合者获得调查发现（含空结果与带理由的跳过项）、代码锚点、用户原始问题、references/epistemics.md 中的置信度框架，以及 references/synthesizer-prompt.md 中的提示模板。
  5. 呈现：将综合者输出呈现给用户，可轻度编辑以提升清晰度或补充对话上下文，但不得改写置信度措辞。

调查员名册（按证据类别）

  • 源代码控制（git 历史、gh 查 PR、代码注释、测试）：始终派出，唯一有保证的来源。最擅长捕获评审时记录的实现期理由。
  • 工单/问题追踪（如 Linear、Jira、GitHub Issues、Plane、Shortcut MCP）：最擅长产品/业务驱动力，当“为什么”来自工程之外时最强。
  • 长文档（如 Notion、Confluence、Google Docs、Coda MCP）：最擅长在变成代码之前写下的长篇设计理由。
  • 实时团队聊天（如 Slack、Discord、Microsoft Teams、Mattermost MCP）：最擅长从未进入文档的实时讨论，当源代码控制、工单和文档线索稀薄时尤为重要。
  • 基础设施可观测性（如 Datadog、New Relic、Honeycomb、Grafana、Splunk MCP）：最擅长驱动代码的基础设施与运行时现实，当目标响应基础设施信号（超时、重试、限流、熔断）时最强。
  • 错误/异常追踪（如 Sentry、Rollbar、Bugsnag、Airbrake MCP）：最擅长驱动防御性或纠正性代码的具体异常与错误轨迹，对 catch 块、空值保护、类型检查、重试等防御最强。
  • 产品分析仓库（如 Databricks、Snowflake、BigQuery、ClickHouse、dbt、Redshift MCP）：最擅长塑造代码的产品与数据现实，对开关门控代码、实验驱动发布、数据迁移和“这个数字从哪来”的问题最强。

何时跳过调查员

仅在最终“Sources Consulted”中给出明确书面理由时才跳过。两个有效理由：该类别在此环境中没有可用 MCP（标记为缺口而非选择）；来源可证明无关而非“可能无关”（门槛很高）。若范围评估表明是单提交的琐碎目标且 PR 描述已含完整答案，可在确认全部七个可用类别搜索都冗余后内联回答，并明确说明，这种情况应很少见。

输出格式

结构来自 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 每位调查员一行，包括返回空结果或被跳过的，并附理由。若用户的 why 问题是修改此代码的前置，则在 Sources Consulted 之后将沿革发现转换为 Preserve / Change / Avoid / Risk 约束集，用于规划变更。

模型与推理强度

角色默认值来自 plugins/pstack/models.json。why investigators 与 why synthesizer 默认均为 opus。pstack-models.md 覆盖表中匹配的角色行会在运行时覆盖。覆盖表中的角色值可在模型名后命名推理强度，如 opus @xhigh。Claude Code 上的级别：low、medium、high、xhigh、max，具体适用取决于模型。不带 @ 的值取覆盖表的默认强度行、某级别或 session；覆盖表无该行时为 session。读取模型前先剥离后缀：inherit-parent 或 auto 在任何级别都省略模型，模型名则作为 model 传入。在 Claude Code 上，级别会从原本使用的 subagent_type 选择 effort agent：pstack:poteto-agent 变为 subagent_type: "pstack:poteto-agent-<level>"；general-purpose 或无 subagent_type 变为 subagent_type: "pstack:effort-<level>"。effort agent 只设置强度，传入的模型仍决定模型。在 Codex 上，将级别作为 spawn_agent 的 reasoning_effort 传入并保留常规指令。

操作姿态与常见失败模式

以谨慎、精确的调查员姿态操作，诚实区分已知与推断，综合者必须遵循 references/epistemics.md 中的置信度框架与措辞指南。需避免的常见失败模式：近因偏差——假设最近的提交最具权威性，而当前形态往往是许多更早决策的累积，应向前追溯。

平台说明

在 Codex 上，遵循本技能前先阅读平台映射（含其逐技能说明）。在 GitHub Copilot 上同样如此。每次 spawn 均为 general-purpose 且 readonly: false（agent 模式），不要使用 readonly/Ask 模式，因为它会剥离 MCP 访问，从而禁用基于 MCP 的调查员和综合者的引用抽查。调查员仍不应写入任何内容。