为代码库组件/概念编写「X…

当需要让未来的 agent 或新贡献者快速理解某个组件、概念或模式如何工作时，为其生成一份引用真实路径的结构化说明文档。

适用场景

解决思路

1. 若命令行提供了 $ARGUMENTS，就把它作为文档主题。
2. 把主题净化为可用作文件名的字符串：去掉路径分隔符、特殊字符和路径穿越模式（如 `../`）。
3. 文档目录固定使用 `.groove/memory/docs/`。
4. 确保文档目录存在，不存在则创建。
5. 动笔前彻底调研代码库（使用 Explore agent），文档必须引用真实文件路径，而不是泛泛的描述。
6. 若范围不明确，向用户提问澄清：受众是新贡献者、未来的 agent，还是两者都要？
7. 在隔离的上下文中撰写文档（使用 general-purpose agent）。
8. 文档写入 Overview 章节：说明该组件/概念是什么、解决什么问题。
9. 文档写入 Key Files 章节：列出最重要的文件，每个文件附一行职责说明。
10. 文档写入 How It Works 章节：用分步方式解释主流程或核心逻辑。
11. 文档写入 Gotchas 章节：记录不明显的约束、边界情况和已知的坑。
12. 完成前逐一校验上述四个必需章节都存在。
13. 每个章节保持简洁——这是参考文档，不是教程。
14. Key Files 中列出的是在代码库里实际找到的路径。
15. How It Works 要追踪一条真实执行路径（例如「用户运行 X → Y 读取配置 → Z 写入文件」）。
16. Gotchas 要挑出读代码看不出来的东西。
17. 不要重复 spec 已经写过的内容——若已存在 spec，改为链接到它。

适用边界 · 注意事项

• 需要的是规范/需求文档（spec）而非「如何工作」的说明文档时。
• 代码库中不存在可调研的实现（纯概念、外部系统或尚未落地的设计）时。
• 范围含糊又无法与用户确认受众和边界时。