mcpField
S
spec-miner

spec-miner

github.com/jeffallan开发12.1k4.5k 次安装今天更新
代码仓库

关于 spec-miner

Spec Miner 是一项从现有代码库逆向提取需求的技能。它帮助开发者梳理陌生或缺少文档的系统，通过追踪结构与行为，并以 EARS 格式记录观察结果。

主要功能

  1. 01梳理代码库结构
  2. 02追踪数据流与请求路径
  3. 03用 EARS 格式记录行为
  4. 04区分观察事实与推断
  5. 05标记不确定之处和待确认问题

适用场景

  1. 01为缺少文档的系统编写说明
  2. 02熟悉新的代码库
  3. 03规划现有功能的改进
  4. 04从实现中提取需求

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/jeffallan/claude-skills --skill spec-miner

安装后在 Claude Code 中输入/spec-miner确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
analysis-checklist.md
analysis-process.md
ears-format.md
specification-template.md

详细介绍

规格挖掘器

从现有代码库中提取规格的逆向工程专家。

角色定义

你从两个视角开展工作：架构帽用于分析系统架构和数据流，QA 帽用于分析可观察行为和边缘情况。

何时使用此技能

  • 了解遗留系统或缺少文档的系统
  • 为现有代码创建文档
  • 熟悉新的代码库
  • 规划现有功能的增强
  • 从实现中提取需求

核心工作流

  1. 界定范围 - 确定分析边界（整个系统或特定功能）
  2. 探索 - 使用 Glob、Grep、Read 工具梳理结构
    • 验证检查点： 继续之前，确认已检查足够多的文件。如果关键入口点、配置文件或核心模块仍未读取，请继续探索，然后再编写文档。
  3. 追踪 - 跟踪数据流和请求路径
  4. 记录 - 使用 EARS 格式编写观察到的需求
  5. 标记 - 标出需要澄清的部分
探索模式示例
# Find entry points and public interfaces
Glob('**/*.py', exclude=['**/test*', '**/__pycache__/**'])

# Locate technical debt markers
Grep('TODO|FIXME|HACK|XXX', include='*.py')

# Discover configuration and environment usage
Grep('os\.environ|config\[|settings\.', include='*.py')

# Map API route definitions (Flask/Django/Express examples)
Grep('@app\.route|@router\.|router\.get|router\.post', include='*.py')
EARS 格式速查

EARS（轻松编写需求语法）将观察到的行为组织为：

类型模式示例
通用The <system> shall <action>.API 应返回 JSON 响应。
事件驱动When <trigger>, the <system> shall <action>.当请求缺少身份验证令牌时，系统应返回 HTTP 401。
状态驱动While <state>, the <system> shall <action>.在维护模式下，系统应拒绝所有写入操作。
可选Where <feature> is supported, the <system> shall <action>.启用缓存后，系统应将响应存储 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确保分析全面时

约束

必须执行
  • 所有观察都必须以实际代码证据为依据
  • 广泛使用 Read、Grep、Glob 进行探索
  • 区分观察到的事实与推断
  • 在专门的章节中记录不确定性
  • 为每项观察提供代码位置
禁止事项
  • 不得在缺少代码证据时作出假设
  • 不得跳过安全模式分析
  • 不得忽略错误处理模式
  • 未经过全面探索，不得生成规格

输出模板

将规格保存为：specs/{project_name}_reverse_spec.md

包括：

  1. 技术栈和架构
  2. 模块/目录结构
  3. 观察到的需求（EARS 格式）
  4. 非功能性观察
  5. 推断出的验收标准
  6. 不确定性和问题
  7. 建议

由 @jeffallan 维护，他是 Synergetic Solutions 的首席顾问。

文档

评论

支持 Markdown