/cc-spec:score — 명세서 "애매함" 점수 매기기

모호성 점수 계산 — 5차원 정량 평가로 스펙 명확성을 측정

/cc-spec:score — 명세서 "애매함" 점수 매기기#

항목	내용
실행 명령	`/cc-spec:score`
분류	스펙 명확화
난이도	●●○ 보통

한마디로#

작성한 명세서(Seed spec)가 얼마나 또렷한지, 아니면 애매한지를 0~1점짜리 점수로 채점해 주는 도구입니다. 글쓰기 선생님이 빨간펜으로 "이 부분 무슨 뜻인지 모르겠어요"라고 짚어주고 종합 점수까지 매겨주는 것과 같아요.

누가·언제 쓰나요#

기획서·요구사항(Seed spec)을 다 쓴 뒤, "이대로 개발에 넘겨도 될 만큼 명확한가?"를 확인하고 싶을 때
누군가 읽고 오해할 만한 애매한 표현이 남아 있는지 점검하고 싶을 때

무엇을 해주나요#

명세서를 5가지 기준으로 살펴본 뒤 종합 애매함 점수와 등급을 알려주고, 그 점수를 명세서 파일 안에도 기록해 줍니다.

5가지 채점 기준
- 단어 정확성 — "빠르게", "적절히", "필요시" 같은 두루뭉술한 말을 쓰지 않았는지
- 지칭 명확성 — "이것", "그것" 같은 말이 무엇을 가리키는지 분명한지
- 완전성 — 모든 기능에 합격 기준이 있고, 예외 상황·오류 상황이 빠지지 않았는지
- 일관성 — 용어가 통일됐는지, 앞뒤 숫자나 우선순위가 서로 어긋나지 않는지
- 테스트 가능성 — 각 요구사항이 합격/불합격을 객관적으로 판정할 수 있는지
결과 등급: CLEAR(통과) / WARNING(조건부) / AMBIGUOUS(미흡) / UNCLEAR(재작성 필요)

어떻게 쓰나요#

/cc-spec:score                      # 가장 최근 Seed 명세서를 채점
/cc-spec:score --file {path}        # 특정 파일을 지정해 채점
/cc-spec:score --verbose            # 기준별 상세 분석까지 함께 보기

그냥 실행하면 가장 최근에 만든 명세서를 자동으로 찾아 채점합니다.
--file로 채점할 파일을 직접 지정할 수 있습니다.
--verbose를 붙이면 5가지 기준별로 어디가 왜 애매한지 자세한 분석까지 보여줍니다.

안에서 무슨 일이 벌어지나요#

파일 불러오기 — 대상 명세서를 읽고 항목별로 나눕니다.
5가지 기준 채점 — 단어 정확성·지칭 명확성·완전성·일관성·테스트 가능성을 각각 0~1점으로 매깁니다.
종합 점수 계산 — 기준마다 정해진 가중치를 곱해 하나의 최종 점수로 합산합니다.
등급 판정 — 점수에 따라 통과/조건부/미흡/재작성 필요 중 하나로 판정합니다.
명세서에 기록 — 계산된 애매함 점수를 명세서 파일 정보란에 다시 적어 둡니다.

⚙️ 상세 옵션·실행 명세 (개발자 / AI 에이전트용)

Usage#

/cc-spec:score                      # Evaluate the latest Seed spec
/cc-spec:score --file {path}        # Evaluate a specific file
/cc-spec:score --verbose            # Include detailed per-dimension analysis

Parameters#

Parameter	Description	Default
`--file`	Target file path	Latest `docs/seed-spec-*.md`
`--verbose`	Detailed analysis output	false

Execution Flow#

1. Load Target File#

Read Seed spec file
Parse each section

2. 5-Dimension Evaluation#

Evaluate each dimension per AMBIGUITY_RUBRIC.md:

2a. Lexical Precision (weight 0.25)

Scan for prohibited words in the spec's own language — English ("fast", "appropriate", "etc.", "if needed" ...) AND Korean ("빠르게", "적절히", "등등", "필요시" ...). Use the locale-tagged table in AMBIGUITY_RUBRIC.md.
Use semantic judgment, not keyword-matching alone — a vague phrase in any language counts even if it is not in the table.
If the spec language is not covered by the table, mark this dimension UNVERIFIED (not 0.0) and fall back to semantic judgment — never score an un-scannable language as "0 prohibited words".
Check whether specific values/criteria have been substituted
Score: 0.0 (0 prohibited words) ~ 1.0 (pervasively ambiguous)

2b. Reference Clarity (weight 0.20)

Scan for pronouns/demonstratives — English ("this", "that", "said") AND Korean ("이것", "그것", "해당", "위의")
Check whether abbreviations are defined
Check for implicit subjects ("is processed" → missing agent)
Score: 0.0 (all references clear) ~ 1.0 (key references unclear)

2c. Completeness (weight 0.20)

Check whether AC (acceptance criteria) exist for all features
Check whether edge cases are identified
Check whether error scenarios are defined
Score: 0.0 (all complete) ~ 1.0 (most missing)

2d. Consistency (weight 0.20)

Check terminology unity
Check for numeric/logical contradictions between sections
Check priority consistency
Score: 0.0 (fully consistent) ~ 1.0 (severe contradictions)

2e. Testability (weight 0.15)

Check whether each requirement has Pass/Fail criteria
Check automation feasibility
Check reproducibility
Score: 0.0 (all testable) ~ 1.0 (most require subjective judgment)

3. Final Score Calculation#

score = (lexical × 0.25) + (reference × 0.20) + (completeness × 0.20)
      + (consistency × 0.20) + (testability × 0.15)

4. Verdict#

Grade	Score	Result
CLEAR	<= 0.2	Pass
WARNING	0.2~0.3	Conditional — Improvement recommendations provided
AMBIGUOUS	0.3~0.5	Fail — Required fix items presented
UNCLEAR	> 0.5	Reject — Rewrite required

5. Seed Spec Update#

Update the ambiguity score in metadata

Output#

Evaluation results printed to console. With --verbose, detailed per-dimension analysis is included. Ambiguity score in Seed spec metadata is updated.

/cc-spec:seed — Create Seed spec
/cc-spec:verify — Verification + lock
/cc-spec:evaluate — 3-stage integrated evaluation

References#

references/AMBIGUITY_RUBRIC.md — Detailed 5-dimension rubric
config/thresholds.yaml — Threshold settings