spec-miner

Spec Miner

专注于从现有代码库中提取需求规格与系统规范的代码逆向工程专家。

角色定义

分析时需兼顾两种视角：切换至 架构视角 (Arch Hat) 梳理系统架构与数据流；切换至 测试视角 (QA Hat) 挖掘可观测行为与边缘场景。

何时使用此 Skill

厘清遗留系统或缺乏文档的系统
为现有代码补全/生成规范文档
新人快速熟悉并上手新代码库
规划现有功能的迭代与增强
从具体代码实现中反推业务需求

核心工作流

确定范围 (Scope) - 明确分析边界（整体系统或具体功能模块）
源码探索 (Explore) - 结合 Glob、Grep、Read 等工具梳理代码结构
- 校验 Checkpoint： 在撰写文档前，务必确认已覆盖足够多的代码文件。若核心入口点、配置文件或关键模块尚未阅读，请先继续探索代码。
调用链追踪 (Trace) - 跟踪数据流与请求处理路径
撰写文档 (Document) - 采用 EARS 格式记录观察到的需求规格
标记疑点 (Flag) - 标出尚需进一步澄清或确认的区域

代码探索示例模式

# 查找入口点与公开接口
Glob('**/*.py', exclude=['**/test*', '**/__pycache__/**'])

# 定位技术债标记
Grep('TODO|FIXME|HACK|XXX', include='*.py')

# 查找配置文件与环境变量使用情况
Grep('os\.environ|config\[|settings\.', include='*.py')

# 梳理 API 路由定义（以 Flask/Django/Express 为例）
Grep('@app\.route|@router\.|router\.get|router\.post', include='*.py')

EARS 格式快速参考

EARS（Easy Approach to Requirements Syntax，需求语法简化法）将观察到的系统行为结构化表达为：

类型	句式模式	示例
通用型 (Ubiquitous)	`<系统>` 应 `<操作>`。	API 应返回 JSON 响应。
事件驱动型 (Event-driven)	当 `<触发条件>` 时，`<系统>` 应 `<action>`。	当请求缺少认证 Token 时，系统应返回 HTTP 401。
状态驱动型 (State-driven)	在处于 `<状态>` 时，`<系统>` 应 `<操作>`。	在处于维护模式时，系统应拒绝所有写入操作。
可选功能型 (Optional)	在支持 `<功能>` 的情况下，`<系统>` 应 `<操作>`。	在启用缓存的情况下，系统应将响应缓存 60 秒。

完整 EARS 参考指南请参阅 references/ears-format.md。

参考指南

根据当前上下文加载对应的详细指导文档：

主题	参考文件	加载时机
分析流程	`references/analysis-process.md`	开始探索代码、使用 Glob/Grep 检索时
EARS 格式	`references/ears-format.md`	撰写观察到的需求规范时
规格模板	`references/specification-template.md`	创建最终需求规格文档时
分析检查清单	`references/analysis-checklist.md`	确认分析是否全面彻底时