spec-score-mcp

Spec Score MCP

Claude が実装を始める前に、仕様のスコアを評価します。

バランスの取れた仕様からはバランスの取れたコードが生まれます。バランスの取れていない仕様からは、創作物が生まれます。

問題点

仕様の一部の観点が詳細で、ほかの観点が曖昧な場合、Claude は確認を求めずに空白を埋めます。結果はコンパイルでき、テストにも合格しますが、意図したものとは異なります。

このツールは、実装を始める前にこの問題を検出します。仕様を4つの観点で採点し、最も弱い観点を示して、修正するための具体的なヒントを提示します。

4つの観点

観点	答える質問
completeness	Claude は実装対象の全範囲を理解できますか？
clarity	この仕様の解釈は1通りだけですか？
constraints	Claude は実装してはいけないことを理解していますか？
specificity	具体的でテスト可能な詳細がありますか？

各観点のスコアは0.0から1.0です。バランススコアは、4つの観点がどれだけ均等にカバーされているかを測定します。

個々のスコアよりもバランスが重要です。 4つの観点すべてで0.50の仕様（バランス：0.97）は、0.95／0.95／0.20／0.90の仕様（バランス：0.58）より良い結果を生みます。なぜでしょうか？ 弱い観点であるconstraintsのスコア0.20が、まさにClaudeが独自に補ってしまう部分だからです。実装する内容は詳しく説明していても、対象外の内容を伝え忘れています。そのためClaudeは、依頼されたものに加えて、依頼していない機能まで実装します。

レーダーチャートでは、均等なひし形が鋭く尖った形よりも優れています。

判定

判定	意味
SHIP IT	仕様の準備が整っています。Claude は実装する内容と、実装しない内容を理解しています
ALMOST	始める前に、1つの観点を少し修正する必要があります
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	採点済みの2つの仕様を並べて比較します

Claude に「この仕様を採点して」「レーダーチャートを表示して」「この2つの仕様を比較して」と依頼してください。

例：UNBOUNDEDからSHIP ITへ

このツールが自身の仕様を採点した例です。4回にわたり、毎回最も弱い観点を修正しています。

第1ラウンド：アイデア

仕様を採点するツールを作る

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

1つの観点（clarity、つまり目標の明確さ）だけが高く、それ以外はほぼゼロです。Claude は何でも作れてしまいます。ウェブアプリ？ CLI？ VS Code 拡張機能？ これでは判断できません。

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

completeness、clarity、constraints、specificityの4つの観点で仕様を採点するMCPサーバーを作る。各観点のスコアは0.0～1.0。バランススコアと判定を返す。

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

これでClaudeは実装するものを理解しました。しかしconstraintsはまだ弱く、自動修正、CI統合、データベースなどを追加する可能性があります。

Round 3：境界を追加する

3 つのツール：spec_score、spec_visualize、spec_compare。 対象外：自動修正、CI 統合、ストレージはありません。

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

しきい値を超えました。Claude は、何を構築するかだけでなく、何を構築しないかも把握できるようになりました。具体性は依然として最も弱い軸です。

Round 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 License.

© 2026 OpenPoem. [email protected]