用途
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 工作流中,为某个功能或任务在动手实现前先产出结构化实现规格,尤其适合需要结合代码库现状与用户意图、并希望保持主对话上下文整洁的开发场景。
限制
资料未提供该技能的收费、价格、支持平台或具体效果等信息。