从遗留或无文档代码库反向提炼规格文档

当接手遗留项目、无文档代码库或继承项目，需要搞清楚系统如何运作并产出规格/架构文档时使用。

适用场景

解决思路

1. 先确定分析边界：明确是分析整个系统还是某个特定功能。
2. 用 Glob、Grep、Read 工具探索并映射代码结构，覆盖入口点、配置与核心模块。
3. 执行验证检查点：写文档前确认文件覆盖足够；如果关键入口点、配置文件或核心模块还没读过，就继续探索。
4. 追踪数据流与请求路径，还原实际执行链路。
5. 用 Glob 查找入口点和公共接口，例如 Glob('**/*.py', exclude=['**/test*', '**/__pycache__/**'])。
6. 用 Grep('TODO|FIXME|HACK|XXX', include='*.py') 定位技术债标记。
7. 用 Grep('os\.environ|config\[|settings\.', include='*.py') 发现配置与环境变量使用。
8. 用 Grep('@app\.route|@router\.|router\.get|router\.post', include='*.py') 映射 API 路由定义。
9. 用 EARS 格式把观察到的需求写成规格，四类模式：通用「The `<system>` shall `<action>`.」；事件驱动「When `<trigger>`, the `<system>` shall `<action>`.」；状态驱动「While `<state>`, the `<system>` shall `<action>`.」；可选「Where `<feature>` is supported, the `<system>` shall `<action>`.」。
10. 标记需要澄清的区域，单独列出不确定性。
11. 所有观察必须以实际代码证据为依据。
12. 大量使用 Read、Grep、Glob 进行探索。
13. 严格区分观察到的事实与推断。
14. 在专门章节中记录不确定性。
15. 为每条观察标注对应代码位置。
16. 不要在没有代码证据的情况下做假设。
17. 不要跳过安全模式分析。
18. 不要忽略错误处理模式。
19. 不要在未充分探索的情况下生成规格。
20. 把规格保存为 specs/{project_name}_reverse_spec.md，内容包含：1) 技术栈与架构；2) 模块/目录结构；3) 观察到的需求（EARS 格式）；4) 非功能观察；5) 推断出的验收标准；6) 不确定性与疑问；7) 建议。
21. 按需加载参考文档：开始探索时看 references/analysis-process.md，写需求时看 references/ears-format.md，产出最终规格时看 references/specification-template.md，检查完整性时看 references/analysis-checklist.md。

适用边界 · 注意事项

• 代码库已有完善且最新的文档时，直接阅读文档即可，无需反向工程。
• 任务是新写代码而非理解既有实现时，不适用。