spec-score-mcp

Spec Score MCP

在 Claude 根据规范进行开发之前，为你的规范打分。

均衡的规范会产出均衡的代码。不均衡的规范会产出天马行空的虚构内容。

问题

当你的规范在某些维度上写得很详细、在其他维度上却含糊不清时，Claude 不会请求澄清，而是会自行填补空白。结果虽然可以编译，测试也能通过，但却不是你想要的。

这个工具会在你开始开发之前发现这些问题。它会从 4 个维度为你的规范打分，告诉你哪个维度最薄弱，并提供一个具体的改进建议。

4 个维度

维度	回答的问题
完整性	Claude 能否理解要构建的完整范围？
清晰度	这份规范是否只有一种解读方式？
约束	Claude 是否知道哪些内容不应该构建？
具体性	是否包含具体、可测试的细节？

每个维度的得分为 0.0 到 1.0。均衡度得分用于衡量 4 个维度的覆盖是否均衡。

均衡比单项得分更重要。 4 个维度都得 0.50 的规范（均衡度：0.97），产出的效果会好于得分为 0.95 / 0.95 / 0.20 / 0.90 的规范（均衡度：0.58）。为什么？那个薄弱维度——得分为 0.20 的约束——恰恰是 Claude 会自行发挥的地方。你详细描述了要构建什么，却忘了说明哪些内容不在范围内。于是 Claude 不仅构建了你要求的所有内容，还加上了你没要求的功能。

在雷达图上：均匀的菱形胜过尖锐的突起。

评定结果

评定	含义
SHIP IT	规范已就绪——Claude 知道该构建什么，也知道哪些内容不该构建
ALMOST	有一个维度需要稍作修改，然后就可以开始
DRAFT	多个维度需要完善，但结构已经具备
VAGUE	组织良好，但过于抽象，无法据此采取行动
UNBOUNDED	目标明确，但没有边界——Claude 会过度构建
OVER-CONSTRAINED	规则很多，但实际目标不明确
SKETCH	初步起点——大多数维度都需要补充细节

还没达到 SHIP IT？这个工具会告诉你哪个维度最薄弱，以及应该补充什么。修正该维度，重新评分，然后重复这个过程。大多数规范经过 2-3 轮就能达到 SHIP IT。

安装

git clone https://github.com/openpoem/spec-score-mcp.git
cd spec-score-mcp && npm install && npm run build
claude mcp add spec-score -- node $(pwd)/dist/mcp.js

这 3 个工具现在已在每个 Claude Code 会话中可用。

使用方法

斜杠命令

克隆此仓库即可获取内置的斜杠命令：

/project:scan my-feature-spec.md

读取文件并评分，然后生成 my-feature-spec.md.scored.md，其中包含得分、评定、建议和雷达图。

/project:compare blueprint.md implementation.md

为两个文件评分，并生成 compared.scored.md，其中包含并排显示的雷达图。

直接使用工具

这 3 个 MCP 工具可在任何 Claude Code 对话中使用：

工具	功能
spec_score	从 4 个维度为规范评分，并返回均衡度得分和评定结果
spec_visualize	根据得分生成 SVG 雷达图
spec_compare	并排比较两份已评分的规范

向 Claude 提问：“为这份规范评分”、“给我看看雷达图” 或 “比较这两份规范”。

示例：从 UNBOUNDED 到 SHIP IT

这个工具为自己的规范评分——经过 4 轮，每轮都修正最薄弱的维度：

第 1 轮：想法

构建一个规范评分工具

UNBOUNDED  0.12  Tip: What does 'scoring' mean? What axes? What output?

一个维度得分较高（清晰度——目标明确），其他维度的得分都接近零。Claude 会构建……任何东西。Web 应用？命令行工具？VS Code 扩展？完全无从判断。

第 2 轮：补充背景

构建一个 MCP 服务，从 4 个维度为规范评分：完整性、清晰度、 约束、具体性。每个维度的得分为 0.0-1.0。返回均衡度得分和评定结果。

ALMOST  0.67  Tip: What are the verdicts? What does the tool NOT do?

现在 Claude 知道要构建什么了。但约束仍然薄弱——它可能会添加自动修复、CI 集成或数据库。

第 3 轮：添加边界

三个工具：spec_score、spec_visualize、spec_compare。 非目标：不自动修复、不集成 CI、不存储数据。

SHIP IT  0.84  Tip: Add testable criteria — what balance maps to which verdict?

跨过了门槛。Claude 现在知道要构建什么，也知道不该构建什么。具体性仍然是最薄弱的维度。

第 4 轮：添加可测试的细节

平衡度 = 1 - sqrt(variance)/mean。SHIP IT > 0.75，ALMOST > 0.60， 并提供基于模式的判定结果。Node.js、MCP SDK、stdio 传输。

SHIP IT  0.95  Spec is ready for implementation.

四轮迭代：0.12 → 0.67 → 0.84 → 0.95。每轮恰好解决一个问题。

数学原理

1. Claude 为每个维度打分（0.0 - 1.0）
2. 归一化向量：v / ||v||
3. 平衡度：1 - sqrt(variance) / mean
4. 判定结果：平衡度阈值 + 维度模式匹配

评分智能来自 Claude，而不是算法。算法只衡量平衡度。

项目结构

src/
  mcp.ts        # MCP server (3 tools)
  score.ts      # Scoring engine
  visualize.ts  # SVG radar charts
.claude/
  commands/
    scan.md     # /project:scan command
    compare.md  # /project:compare command

---

OpenPoem — spec-score-mcp

MIT 许可证。

© 2026 OpenPoem。[email protected]