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

이제 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 대화에서 작동합니다:

Claude에게 "이 명세서 점수 매겨줘", "레이더 차트 보여줘", 또는 *"이 두 명세서를 비교해줘"*라고 요청하세요.

예시: UNBOUNDED에서 SHIP IT으로

이 도구가 자체 명세서를 평가하는 과정입니다. 4라운드에 걸쳐 가장 취약한 축을 수정했습니다:

1라운드: 아이디어

명세서 평가 도구 만들기

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

한 축은 높지만(명확성 — 목표는 명확함), 나머지는 거의 0에 가깝습니다. Claude는... 무엇이든 만들 것입니다. 웹 앱일까요? 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라운드: 경계 추가

세 가지 도구: 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. 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