SuperAPI AI 工具集

why

编程与开发

查看项目

更新于 10-16 08:19

技能介绍

用途

why 技能用于调查代码背后的动机与意图:为什么它被做成这样?考虑过哪些边界情况?哪些产品、业务或运营约束塑造了设计?哪些替代方案被否决、理由是什么?它是 how 技能的配套:how 回答“这段代码做什么、怎么工作”,why 回答“是什么力量让它变成现在这个形状”。

主要能力

该技能把历史背景分散在七类证据中:源码版本控制历史、工单/问题跟踪、长文档、团队实时聊天、基础设施可观测性、错误/异常跟踪、产品分析数据仓库。仅凭问题本身无法预测哪一类藏有真正答案——提交信息可能为空而设计文档很详细,决定性理由也可能只存在于聊天记录或分析表中。因此该技能会在运行时枚举可用 MCP,把每个 MCP 映射到一个类别,用可用工具并行查询全部七类,再综合发现并显式校准置信度。被搜索类别返回的空结果被视为关于决策如何做出的一等证据,与正面发现一并报告。默认追求覆盖,而非最小化。

使用方式

工作姿态:像侦探一样从零散记录中拼凑历史案件——收集证据、标注每件证据来源、为同一事实考虑替代解释、抵制编造整洁叙事的冲动;记录稀薄时如实说明。具体原则包括:证据先于叙事;精确优于润色,优先使用原文引用与精确出处;考虑未看到的部分;点名空白;有意使用模糊措辞(“似乎”“可能”“表明”);不通过读代码走捷径。

核心认识论:工单会过期,聊天会被删除,提交信息会说谎,人们会在 PR 描述与实现之间改变主意,原作者可能已离职。要无情地诚实区分“已知”与“推断”。原则:引用一切,每条关于意图的主张都应指向具体提交哈希、PR 编号、工单 ID、文档 URL、聊天永久链接或代码注释,无法引用即为推断并须标注;优先用“似乎”而非“因为”;呈现矛盾,两个来源冲突时都展示;承认空白,诚实的“我们查不到原因”比自信的猜测更有价值;多个假设都有效时全部呈现;警惕事后合理化,不要为代码回填意图。

步骤一,理解目标与问题。解析用户所问,目标通常是代码片段、模式、功能或具名设计决策;问题通常是设计理由、权衡/替代方案、防御性推理、外部强制因素、死代码判断或宽泛历史考古。若目标含糊,从对话上下文(当前打开文件、最近编辑、光标位置、刚讨论的内容)做最佳猜测,简要说明解释后继续。

步骤二,建立代码锚点。在派出调查者前,先锚定具体代码:相关文件路径与行范围、关键符号(函数名、类名、常量)、初始提交列表(最近触及目标的若干提交)、从合并提交中提取的 PR 编号(常见模式:主题行中的 (#1234))。可用命令包括:git blame -L <start>,<end> <file>;git log --follow -p -- <file>;git log --oneline -20 -- <file>;git log -1 --format=%B <commit>;以及通过 gh pr view <number> --json title,body,author,createdAt,mergedAt,labels,closingIssuesReferences,comments,reviews 拉取 PR 正文与讨论。把这些作为种子上下文传给调查者。

步骤三,并行派出调查者(默认姿态)。默认进行完整并行调查。先列出 Cursor 环境中可用的 MCP,把每个映射到七类之一;源码版本控制历史始终可通过 git 和 gh 获得。目标是完整的覆盖图而非最小覆盖。在单条消息中同时启动所有匹配的调查者,使其并发运行;每个调查者只负责一个工具或 MCP。子代理配置:subagent_type 为 generalPurpose,model 为 composer-2.5-fast,readonly 为 false(agent 模式),不要用 readonly/Ask 模式,因为它会剥离 MCP 访问。每个调查者获得:references/investigator-prompt.md 的基础提示、所选 MCP 对应的 references/sources/<source>.md 类别手册、若目标代码看起来具防御性(空值检查、重试逻辑、超时处理、限流、功能开关、出口防护、OOM 处理)则加上 references/sources/incident-postmortem.md 横切手册、步骤二的代码锚点、用户原始问题。

调查者名单(每个可用证据类别一个):源码版本控制调查者(git 历史、gh 拉取 PR、代码注释、测试;始终派出,唯一保证可用的来源;最擅长呈现实现期理由,如 PR 描述中的问题、评审线程中的替代方案辩论、内联注释中的非显然约束、测试名中的动机边界情况、提交信息中关联的工单或事故)。工单/问题跟踪调查者(如 Linear、Jira、GitHub Issues、Plane、Shortcut MCP;最擅长呈现产品/业务强制因素,如客户请求、合规截止日期、父级倡议框架、工单级范围变更、动机分类标签)。长文档调查者(如 Notion、Confluence、Google Docs、Coda MCP;PRD、规格、RFC、设计文档、ADR、事后复盘、团队页面、会议记录;最擅长呈现长文设计理由,如问题陈述、明确的“考虑过的替代方案”与“被否决的方法”、设定优先级的战略文档、最终决策的 ADR、与代码直接相关的事后行动项)。实时团队聊天调查者(如 Slack、Discord、Microsoft Teams、Mattermost MCP;按功能名与符号搜索、PR URL 提及、事故频道、发布日前后作者活动;最擅长呈现从未进入文档的实时讨论,如事故中的紧急决策、PR 作者与评审者之间的问答、随意的“我们因为 Y 决定 X”线程、不值得写 PRD 的小改动理由)。基础设施可观测性调查者(如 Datadog、New Relic、Honeycomb、Grafana、Splunk MCP;指标、监控、仪表盘、日志、APM 追踪、正式事故;最擅长呈现驱动代码的基础设施与运行时现实,如与代码常量匹配的监控阈值、PR 合并前窗口的指标尖峰、作为事后行动项创建的仪表盘、引用目标的事故时间线)。错误/异常跟踪调查者(如 Sentry、Rollbar、Bugsnag、Airbrake MCP;问题、事件、堆栈跟踪、发布;最擅长呈现驱动防御性或纠正性代码的具体异常与错误轨迹,如穿过目标函数的堆栈跟踪、首次/末次出现窗口夹住 PR 发布日的问题、显示错误在特定版本停止的发布关联)。产品分析数据仓库调查者(如 Databricks、Snowflake、BigQuery、ClickHouse、dbt、Redshift MCP;产品分析事件、实验与功能开关曝光表、使用与计费事件、查询历史、仓库遥测;最擅长呈现塑造代码的产品与数据现实,如功能使用轨迹、与发布决策相关的实验/开关曝光数据、揭示阈值常量来源的发布前分布、迁移/回填的数据管道规模证据)。

何时跳过调查者:只有两种有效理由,且须在最终“已查阅来源”部分写明明确理由。一是该类别在此环境无可用 MCP,标记为空白而非选择;二是来源可证明无关,而非“可能无关”,这是很高的门槛。例如“错误/异常跟踪跳过:目标是构建期脚本,无运行时代码路径”可以,而“大概不在错误跟踪里,它是功能不是错误”不够。若范围评估表明是单提交的琐碎目标且 PR 描述已含完整答案,只有在确认全部七类可用搜索都冗余后才可内联回答,且必须在输出中明确说明;这种情况应很少见。

步骤四,综合。派出一个综合者子代理:subagent_type 为 generalPurpose,model 为 claude-opus-4-7-thinking-xhigh,readonly 为 false(agent 模式),因为其质量检查包括抽查引用,可能需要 MCP 访问。

默认输出:只返回结果、阻碍和必要证据。省略前言、过程叙述、重复上下文、置信度分数和后续提议。除非所需产物或模式需要更多,否则最多五条要点。

适用场景

适用于回答“为什么 X 是这样工作的”“为什么我们选了 Y”、设计理由、回归、事后复盘或数据支撑的阈值等问题。

限制

历史证据分散且可能缺失:工单会过期、聊天会被删除、提交信息可能不准确、原作者可能已离职。该技能不通过阅读代码推断意图,证据不足时明确记录空白而非猜测。其效果取决于环境中可用的 MCP 覆盖情况;缺失类别只能作为空白报告。