SuperAPI AI 工具集

bonfire-spec

编程与开发

查看项目

更新于 10-16 06:10

技能介绍

用途

bonfire-spec 用于为某个功能或任务(通过 $ARGUMENTS 传入)创建一份完整的实现规格(implementation spec),并写入配置好的规格存放位置。规格需要覆盖:要构建什么以及为什么、带理由的关键决策、具体的实现步骤、边界情况与错误处理、测试方法与范围边界。

主要能力

生成的规格文件必须包含以下四个章节:

  • Overview:该功能做什么以及为什么重要

  • Decisions:关键技术选择及其理由

  • Implementation Steps:有序、可执行的构建步骤

  • Edge Cases:错误处理、边界条件、失败模式

允许添加其他章节,但这四个为必需。质量信号包括:决策引用真实的代码库模式(而非通用建议);实现步骤针对该代码库(文件路径、函数名);边界情况反映研究中发现的真实约束。

使用方式

上下文隔离

研究与撰写在隔离子代理上下文中进行,以保留主上下文用于用户交互。

  • 研究阶段:使用 codebase-explorer 代理,模型 inherit,目的是快速探索而不污染主上下文。
  • 撰写阶段:使用 writer 代理,模型 inherit,目的是在隔离环境中综合,拥有完整的研究与访谈上下文。

通过 Task 工具调用相应代理。这些子代理设置了 user-invocable: false,因此只能通过 Task 访问。

必须进行用户访谈

撰写之前必须访谈用户。研究为问题提供依据;问题能揭示用户不会主动提及的决策。访谈必须覆盖:核心技术决策(模式、方法、权衡)、边界情况与错误处理偏好、测试方法、范围边界(明确排除的内容)。使用 AskUserQuestion。好的问题应由研究支撑、围绕权衡、且针对具体代码库。

文件位置

  • 配置:<git-root>/.bonfire/config.json 中包含 specsLocation
  • 默认:若未配置则为 .bonfire/specs/
  • 命名:<issue-id>-<topic>.md 或 <topic>.md

验证

撰写完成后,验证规格是否包含全部 4 个必需章节。若不完整:警告用户缺少什么;提供选项:继续 / 重试 / 中止。

会话上下文

撰写规格后,在 <git-root>/.bonfire/index.md 的 Current State 下添加对该规格的引用,将规格与创建它的会话关联起来。

完成

验证后,确认规格创建完成并提供选项:继续实现、细化特定章节、留待以后。

指导原则(非规则)

以下模式通常效果良好,但可按需调整:

  • 先研究再访谈——研究发现让问题具体且有价值。
  • 三轮访谈——核心决策 → 边界情况 → 测试与范围。若用户时间紧张可合并。
  • 展示工作过程——告诉用户你在做什么:“Researching...”、“Starting interview...”、“Writing spec...”。
  • 优雅降级——若子代理失败,在主上下文中完成工作。警告用户但不要停止。
  • 大型代码库——探索者可能需要多轮。若发现似乎不完整,可提议继续。
  • 撰写者上下文——调用 writer 代理时,指定文档类型为 “spec”,以便使用正确格式。

反模式

  • 不要问通用问题——“What features do you want?” 浪费访谈机会。
  • 不要跳过访谈——仅研究遗漏用户意图,仅访谈遗漏代码库现实。
  • 不要未经验证就撰写——子代理可能产生不完整输出,务必检查。
  • 不要过度指定实现——步骤应引导而非微观管理,给实现判断留出空间。

适用场景

适用于在 bonfire 工作流中,为某个功能或任务在动手实现前先产出结构化实现规格,尤其适合需要结合代码库现状与用户意图、并希望保持主对话上下文整洁的开发场景。

限制

资料未提供该技能的收费、价格、支持平台或具体效果等信息。