SuperAPI AI 工具集

explore

编程与开发

查看项目

更新于 10-16 16:34

技能介绍

用途

Explore 是一个后端开发技能,用于在改动遗留代码或多服务代码库之前,先理解代码。它的核心原则是:在编写任何实现代码之前,先产出一份基于代码库、以证据为基础的探索报告,报告中的每一项断言都必须由具体的 文件路径:行号 引用支撑。该技能适用于启动任何非平凡的后端任务,包括功能请求、Bug 报告、重构范围界定以及跨服务影响问题;仅在拼写修正、纯配置变更或零行为歧义的一行编辑时才跳过。

核心铁律

  • 探索报告交付并获批前,不得修改代码。
  • 没有解释探索步骤和推理路径,不得给出最终结论。
  • 报告本身就是交付物,实现是后续单独步骤,且需要双方约定的范围。

主要能力

技能将该任务拆分为五个阶段:

  • 阶段 0:分类请求。判断是 Bug 还是功能(重构算作功能)。
  • 阶段 1:定位(两条轨道通用)。按最省力顺序搜索:领域术语、现有端点/控制器、服务层方法、数据访问与数据库列名、配置与功能开关。记录每个相关的 文件路径:行号。
  • 阶段 1.5:领域与数据库(数据库优先)。先以 schema 为基准开展调查,产出涉及的表、列、关系、领域含义与基数/数据量。可优先使用只读的 MCP 工具或仓库本地只读 helper,否则回退到迁移文件、JPA @Entity/MyBatis mapper、DDL 转储、schema 文档等静态来源。查询安全规则:仅限只读(SELECT/SHOW/DESCRIBE/EXPLAIN),仅限非生产环境,必须加 LIMIT,不得把 PII/真实用户数据写入报告。
  • 阶段 2A:Bug 轨道——根因。采用反向追踪纪律,从症状追踪到最初的触发点,而不是在症状处打补丁。产出:逐字症状、复现步骤、调用链(每个环节带 文件:行号)、一句话根因陈述、被考虑并否决的替代假设、以及源头修复规则。
  • 阶段 2B:功能轨道——模式与匹配。在起草计划前回答五个问题:归属位置、适用的现有模式、可复用的内容、接口/契约、影响半径。
  • 阶段 3:影响与风险。列出将被触及文件的调用方与依赖方、共享状态、跨服务影响、需要修改或新增的测试,以及回滚方案。
  • 阶段 4:报告。按固定模板产出报告,包含执行摘要和面向 AI 优化的正文,并持久化到磁盘。

使用方式

报告保存位置:

  • 若范围为单一微服务/模块,使用该服务目录作为 artifact root;若跨多个服务或明确为仓库级,则使用仓库根目录。
  • 目录布局:<artifact-root>/.backend/<YYYYMM>/<slug>/(按月分桶)。
  • 文件为该目录下的 explore.md,完整路径如 <artifact-root>/.backend/<YYYYMM>/<slug>/explore.md。
  • <YYYYMM> 为探索的六位年月;<slug> 为 kebab-case、不超过 50 字符、由请求推导。
  • 若该目录已存在 explore.md,不得覆盖,改为生成 explore-v2.md、explore-v3.md 等。
  • 该目录是本工单的持久工作区,也会存放其他技能产生的兄弟产物,尤其是 /work 写入的 work.md 和 /verify 写入的 verify.md;本技能不创建 work.md 或 verify.md。

报告输出结构(严格):

  • §1 执行摘要——散文式、面向非开发者
  • §2 元信息——kind/slug/yyyymm/scope/one-liner
  • §3 证据——文件:行号 · 说明
  • §4 领域与数据——表、列(含类型/NN/PK/FK/IX)、关系、基数、来源标签
  • §5A 根因(Bug)或 §5B 模式与匹配(功能)
  • §6 复用清单
  • §7 拟议改动
  • §8 影响半径
  • §9 测试计划
  • §10 开放问题——[BLOCK] [INFO] [GAP]
  • §11 回滚
  • §12 探索步骤与推理
  • §13 复现头(3 行,用于后续会话重载上下文)

从 §2 起禁止使用散文;每项事实均引用 文件:行号。

适用场景

  • 代码库包含多个服务/模块(多微服务、monorepo)
  • 你从未接触过受影响区域
  • 用户提到「遗留」或询问如何避免破坏
  • 快速修复看似诱人但影响半径不明确
  • 功能请求、Bug 报告、重构范围界定、跨服务影响问题

限制与约束

  • 范围为只读;允许的输出仅为 .backend/<YYYYMM>/<slug>/explore*.md,禁止改动源码/测试/配置文件。
  • 只有在独立探索能减少工作量或不确定性、且委托可用并获授权时,才使用有边界的只读子代理;否则直接调查。
  • 禁止在 explore.md 获批前编辑代码;禁止要求子代理编辑文件、回滚改动或实现代码;禁止在没有搜索步骤和推理的情况下返回结论;禁止在未限定任务、未提供可用工具和授权的情况下进行委托。
  • 引用纪律:每个关于代码库的事实断言均标注 路径:行号;范围可用 文件:行号-行号;展示代码最多 3 行;引用若为近似(搜索过但未打开文件)标记 ~。
  • 若结论需要计划外证据或运行时证明,应停下询问,不得把探索变成 /work 或 /verify。

其他

本技能所在目录包含若干支持文件:database-first.md(阶段 1.5 schema/数据核实流程)、reuse-checklist.md(阶段 2B 复用纪律清单)、report-template.md(阶段 4 输出格式与符号图例)。管线中的兄弟技能包括 work(消费 explore.md 并实现计划)与 verify(消费 explore.md + work.md)。完成探索后,应总结结果并链接报告,不要在聊天中重复其完整内容;交付到此为止,仅在用户授权后才继续进入实现。