用途
bonfire-document 用于为代码库中的某个主题创建参考文档。它以 $ARGUMENTS 指定主题，产出完整的参考文档，帮助开发者理解代码库中的某个系统、功能或模式。
文档的目标是让不熟悉代码的人能够：
- 理解它做什么以及为什么存在
- 快速找到相关文件
- 在概念层面理解它如何工作
- 规避常见陷阱
主要能力
- 基于代码库研究生成参考文档，而不是通过访谈获取需求，代码是事实来源。
- 强制文档包含四个必需章节：
## Overview：这是什么以及为什么重要## Key Files：重要文件及其作用## How It Works：对流程/行为的概念性解释## Gotchas：边界情况、陷阱、需要注意的事项
- 允许并欢迎附加章节，如 Architecture、Examples、Related Topics。
- 质量信号要求：文件路径准确且存在于代码库中；解释与实际代码行为一致；Gotchas 反映真实问题而非假设性担忧。
使用方式
- 通过 Task 工具调用相应子代理完成工作：
- 研究阶段：使用 codebase-explorer 代理，模型 inherit，目的是快速探索且不污染主上下文。
- 写作阶段：使用 writer 代理，模型 inherit，目的是在隔离环境中利用完整研究上下文进行综合。
- 这两个子代理设置了 user-invocable: false，只能通过 Task 访问。
- 调用 writer 代理时，需将文档类型指定为 "doc"，以便使用正确格式。
- 文档文件位置：配置位于
<git-root>/.bonfire/config.json，其中包含 docsLocation；未配置时默认使用.bonfire/docs/。 - 命名规则：
<topic>.md，采用 kebab-case，例如authentication-flow.md。 - 写入后需要验证文档是否包含全部 4 个必需章节。若不完整，应警告用户缺少什么，并提供选项：继续 / 重试 / 中止。
- 写入后，在
<git-root>/.bonfire/index.md的 Key Resources 下添加对该文档的引用。 - 验证完成后，确认文档创建并提供后续选项：为任意章节补充更多细节、记录相关主题、继续其他工作。
适用场景
- 需要为代码库中的某个系统、功能或模式建立参考文档时。
- 希望新成员或不熟悉代码的人快速定位相关文件并理解概念性工作原理时。
- 需要归纳真实存在的陷阱与边界情况时。
- 适合作为参考文档（how it works），而非使用指南（how to use it）或教程。
限制与注意事项
- 不记录假设：如果在代码中找不到依据，就不要写。
- 不过度抽象：具体的文件路径和函数名比模糊描述更有用。
- 不跳过验证：子代理可能产出不完整结果，必须始终检查。
- 不写教程：这是参考文档（如何工作），不是指南（如何使用）。
- 大代码库：探索器可能需要多轮处理；若发现的结果对该主题似乎不完整，可提议继续。
- 子代理失败时优雅回退：在主上下文中完成工作，警告用户但不要停止。
- 遵循代码：记录代码实际行为，而不是注释声称的内容或主观假设。
- 研究先于写作：让代码库影响文档结构。
- 过程透明：告知用户正在做什么，例如“正在探索代码库……”“正在撰写文档……”。
暂未提供的信息
- 官方文档与定价信息暂未提供。
- 具体的安装命令暂未提供。