Understanding: IEEE/ISO 표준 기반 요구사항 품질 분석 도구

섹션별 상세

Understanding은 인간이나 LLM의 주관적인 리뷰 대신 IEEE 830 및 ISO 29148 표준에 기반한 결정론적 분석을 수행한다. 동일한 입력에 대해 항상 동일한 결과를 출력하므로 엔지니어링 도구 체인에 적합하며, API 키나 클라우드 연결 없이 로컬 환경에서 약 500ms 내외의 빠른 속도로 작동한다.

bash

uv tool install git+https://github.com/Testimonial/understanding.git \
  --with "spacy>=3.0.0" \
  --with "graphviz>=0.20.0"

# Download spaCy language model
uv pip install --python ~/.local/share/uv/tools/understanding/bin/python \
  en-core-web-sm@https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl

uv를 사용하여 Understanding 도구와 필수 의존성인 spaCy 모델을 설치하는 방법

요구사항 품질을 평가하기 위해 6개 카테고리에서 총 31가지 지표를 사용한다. 구조(원자성, 수동태 비율), 테스트 가능성(제약 조건 밀도), 가독성(Flesch Reading Ease), 인지 부하(문장 길이, 조건문 부하), 시맨틱(행위자 및 결과 존재 여부), 행동 지표(시나리오 분해) 등을 가중치에 따라 종합하여 점수화한다.

bash

# Scan a spec (NLP + entity extraction enabled by default)
understanding spec.md

# Enforce quality gates (exit code 1 on failure)
understanding spec.md --validate

# JSON for CI/CD
understanding spec.md --json --validate

CLI를 통한 요구사항 스캔 및 CI/CD 연동을 위한 품질 게이트 검증 실행

python

from understanding import analyze_with_enhanced_metrics

result = analyze_with_enhanced_metrics(text)
metrics = result["enhanced_metrics"]
overall = metrics["overall_weighted_average"]
categories = metrics["category_averages"]

print(f"Overall: {overall:.2%}")
print(f"Structure: {categories['structure']:.2%}")
print(f"Testability: {categories['testability']:.2%}")

Python API를 사용하여 요구사항의 카테고리별 품질 점수를 추출하는 예시

Understanding CLI 도구의 실행 데모 GIF — Screenshot터미널에서 요구사항 파일을 스캔했을 때 출력되는 31가지 지표의 점수와 품질 게이트 통과 여부, 그리고 엔티티 분석 결과를 시각적으로 보여준다. 색상 코드를 통해 위험 요소를 직관적으로 파악할 수 있음을 확인시켜 준다.

실험적 기능인 에너지 지표(Energy Metrics)는 로컬에서 실행되는 SmolLM2-135M 모델을 사용하여 토큰 단위의 퍼플렉서티를 분석한다. 모델이 예측하기 어려운 단어나 문구는 모호성 핫스팟으로 간주되어 사용자에게 시각적으로 표시되며, 이를 통해 잠재적인 요구사항 결함을 사전에 탐지할 수 있다.

python

from understanding import analyze_energy
# Requires: pip install understanding[energy]

result = analyze_energy("The system must validate user email format before saving.")
print(f"Composite: {result.composite_score:.2%}")
for token, energy in result.hotspot_tokens:
    print(f"  {token}: {energy:.2f}")

로컬 LLM을 활용하여 문장 내 모호성(에너지)을 토큰 단위로 분석하는 API 사용법

CLI 도구로서의 기능뿐만 아니라 Spec Kit 확장 기능을 통해 AI 에이전트와 통합된다. AI가 생성한 요구사항을 즉시 검증하거나 CI/CD 환경에서 설정된 임계값(예: ISO 29148 기준 0.70 이상)을 충족하지 못할 경우 빌드를 실패시키는 품질 게이트 역할을 수행한다.

용어 해설

ISO 29148 표준(ISO 29148): — 소프트웨어 및 시스템 공학에서 요구사항 명세의 프로세스와 품질 기준을 정의하는 국제 표준이다. 요구사항의 원자성, 완전성, 일관성 등을 평가하는 지표의 근거가 된다.
퍼플렉서티(Perplexity): — 언어 모델이 특정 텍스트를 얼마나 잘 예측하는지 나타내는 척도이다. 요구사항 분석에서는 특정 단어나 문장의 모호성이 높을 때 퍼플렉서티가 상승하는 특성을 이용해 결함을 탐지한다.
결정론적 분석(Deterministic Analysis): — 동일한 입력에 대해 항상 동일한 결과를 출력하는 분석 방식이다. 확률적인 LLM 기반 리뷰와 달리 규칙 기반 알고리즘과 수식을 사용하여 분석의 재현성을 보장한다.
인지 부하(Cognitive Load): — 사람의 작업 기억이 정보를 처리할 때 가해지는 부담의 양이다. 문장의 길이, 음절 복잡도, 조건문 중첩 등을 통해 독자가 요구사항을 이해하는 데 드는 노력을 수치화한다.

기술

Python
spaCy
SmolLM2
Transformers
Graphviz
uv

활용 사례

CI/CD 요구사항 품질 게이트
AI 에이전트 생성 스펙 자동 검증
오프라인 요구사항 모호성 분석

언급된 리소스

GitHubUnderstanding GitHub Repository

GitHubSpec Kit