Spec Score MCP

Claudeが仕様書から構築を始める前に、その仕様書をスコアリングします。

バランスの取れた仕様書は、バランスの取れたコードを生み出します。バランスの悪い仕様書は、創作的なフィクションを生み出します。

問題点

仕様書がある軸では詳細なのに、別の軸では曖昧な場合、Claudeは明確化を求めるのではなく、空白を埋めてしまいます。結果としてコンパイルは通り、テストもパスしますが、それは意図したものではありません。

このツールは、構築を始める前にその問題を検知します。仕様書を4つの軸でスコアリングし、最も弱い軸を指摘し、それを修正するための具体的なヒントを提供します。

Related MCP server: MCP Prompt Optimizer

4つの軸

各軸は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」ではありませんか？このツールは、どの軸が最も弱く、何を追加すべきかを教えてくれます。その軸を修正し、再スコアリングし、繰り返してください。ほとんどの仕様書は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

これで、すべてのClaude Codeセッションで3つのツールが利用可能になります。

使用方法

スラッシュコマンド

このリポジトリをクローンして、組み込みのスラッシュコマンドを取得します：

/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の会話でも機能します：

Claudeに「Score this spec（この仕様書をスコアリングして）」、「Show me the radar chart（レーダーチャートを見せて）」、または「Compare these two specs（これら2つの仕様書を比較して）」と尋ねてください。

例：UNBOUNDEDからSHIP ITへ

このツール自身の仕様書をスコアリングした例です。4ラウンドにわたり、それぞれ最も弱い軸を修正しました：

ラウンド1：アイデア

仕様書スコアリングツールを構築する

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

1つの軸（明確性 — 目標は明確）は高いですが、他はほぼゼロです。Claudeは何でも構築してしまうでしょう。Webアプリ？CLI？VS Code拡張機能？知る由もありません。

ラウンド2：コンテキストの追加

4つの軸（完全性、明確性、制約、具体性）で仕様書をスコアリングするMCPサーバーを構築する。各軸は0.0〜1.0。バランススコアと判定を返す。

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

これでClaudeは何を構築すべきかを知りました。しかし、制約はまだ弱いです。自動修正、CI統合、データベースなどを勝手に追加してしまうかもしれません。

ラウンド3：境界の追加

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(分散)/平均。SHIP IT > 0.75, ALMOST > 0.60、およびパターンベースの判定。Node.js, MCP SDK, stdioトランスポート。

SHIP IT  0.95  Spec is ready for implementation.

4ラウンド：0.12 → 0.67 → 0.84 → 0.95。各ラウンドで正確に1つずつ修正しました。

数学的な仕組み

1. Claudeが各軸をスコアリングする (0.0 - 1.0)

2. ベクトルの正規化: v / ||v||

3. バランス: 1 - sqrt(分散) / 平均

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. info@openpoem.org