SuperAPI AI 工具集

specs-explore

编程与开发

查看项目

更新于 10-15 15:28

技能介绍

用途

specs-explore 是 specs.explore 命令的阶段执行器技能,用于在真正提交代码改动之前先对代码库进行探查。它的目标是在决定怎么做之前,先调查代码库、思考问题、比较不同方案,并返回一份结构化的分析结果。

主要能力

  • 解析用户想要探索的内容:判断这是新功能、缺陷修复还是重构,以及涉及哪个领域。
  • 调查代码库:阅读入口点和关键文件,通过 Grep 搜索相关功能,用 Glob 检查已有测试,查找已在使用的模式,并识别依赖与耦合,从而理解当前架构与模式、会被影响的文件和模块、与需求相关的现有行为,以及潜在的约束或风险。
  • 分析方案:如果存在多种实现方式,会按方案、优点、缺点、复杂度(低/中/高)进行对比。
  • 产出分析结果:默认以内联方式返回结构化分析;仅当提供 --spec 参数时,才写入 exploration.md 文件。

使用方式

技能由编排器调用,接收以下输入:一个待探索的主题或功能,--spec 路径(可选),--lang 框架(可选)。

执行步骤包括:

  1. 理解请求:解析用户想探索的内容,判断类型与所属领域。
  2. 调查代码库:读取相关代码,理解架构、受影响文件、相关现有行为,以及约束或风险。
  3. 分析方案:对多种做法进行对比。
  4. 持久化产物(仅在提供 --spec 时):写入 {spec}/exploration.md,内容结构包含 Exploration 标题、Current State、Affected Areas、Approaches(每个方案含简介、Pros、Cons、Effort)、Recommendation、Risks 以及 Ready for Proposal(Yes/No 及用户应了解的事项)。
  5. 返回结果:内联返回同样的结构化分析,并附状态报告,包含 status(done、blocked 或 partial)、executive_summary(一句话描述探索了什么及关键建议)、artifact(提供 --spec 时为 {spec}/exploration.md,否则为 none)、next_recommended(提供 spec 时为 specs.brainstorm,独立使用时为 none)、risks(发现的风险或 None)。

适用场景

  • 在决定实现某个新功能、修复缺陷或重构之前,需要先理解代码库现状。
  • 需要在多个实现方案之间进行比较和取舍。
  • 需要为后续 spec 流程(如 specs.brainstorm)准备一份探索记录。

限制

  • 唯一允许创建的文件是 spec 文件夹内的 exploration.md,且仅在提供 --spec 时创建。
  • 不得修改任何已有代码或文件。
  • 必须阅读真实代码,不得对代码库进行猜测。
  • 分析须保持简洁,是摘要而非长篇论述。
  • 如果找不到足够信息,需明确说明。
  • 如果请求过于模糊,需要请求澄清。
  • 关于定价、平台支持等信息暂未提供。