Spec Kit - "assess" 익스텐션

#1 개요: "assess"

v0.13.0에서 추가된 Spec Kit의 공식 확장 "assess". "assess"는 어떤 아이디어(feature 후보)를 명세할지 말지를 먼저 판단한다.

"assess"는 코드를 구현하는 기능이 아니지만, 그렇다고 명세 그 자체에 포함되는 단계 또한 아니다. 어떤 기능을 명세하기 전, 그 기능 자체가 명세할 가치가 있는지 심사하는 별도의 과정이다. 공식 문서에서도 assess가 기존의 명세 파이프라인에 포함되지 않는, 독립적인 단계라 설명한다.

 

#2 판올림 및 "assess" 활성화

#2-1 v0.13.0으로 판올림

Spec Kit 자체의 판올림

# in 터미널
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v0.13.0

 

구버전 Spec Kit이 적용된 프로젝트의 판올림

# in 터미널
# 해당 프로젝트의 경로에서
specify init --here

 

#2-2 "assess" 활성화

"assess"는 외부 개발자가 커뮤니티 카탈로그에 올린 확장이 아니다. 공식에서 만든 확장이며, Spec Kit v0.13.0 설치 시 자동으로 포함된다. 하지만 기본적으로 활성화되진 않는다. 이 말은, v0.13.0 버전의 Spec Kit을 사용한다고 한들, "assess"에서 제공하는 명령어를 바로 쓸 수는 없다는 소리다. "assess" 사용을 위해선 터미널에 아래의 명령어를 입력해 주어야 한다.

 

# in 터미널
# Spec Kit v0.13.0 이상이 설치된, 프로젝트 경로에서 입력
specify extension add assess

Spec Kit v0.13.0에 이미 포함된 상태이기에, 위의 명령어가 인터넷으로부터 무언가를 추가 다운로드하는 것은 아니다. 말 그대로 '활성화'다.

 

#3 "assess" 분석에 앞서 알아두기

#3-1 호출 시점

공식 문서가 권장하는 호출 시점은 아이디어가 생긴 뒤, 그 아이디어를 명세(/speckit.specify)하기로 결정하기 전이다. 아래와 같은 질문에 확실히 답하기 어려울 때 사용한다.

• 실제로 해결할 가치가 있는 문제인가?
• 아이디어를 뒷받침하는 근거가 충분한가?
• 아무것도 하지 않는 것보다 만들었을 때의 가치가 큰가? (= 굳이 만들어야 하는가?)
• 감당할 수 있는 비용 안에서 구현할 방법이 있는가?

 

#3-2 "slug"

slug는 평가할 아이디어 하나를 구분하는 짧은 영문 식별자(ID)다. 가령, "다크 모드 기능" 아이디어의 slug는 "dark-mode"로 정할 수 있다.

 

#3-3 '심사'의 3가지 결과

assess는 심사 단계라 했다. 그렇다면 그 심사의 결과는 어떻게 판정되는가?

1. go: 통과. 기존의 명세 파이프라인을 따라가면 된다.
2. needs-clarification: 판단에 필요한 내용이 부족.
3. kill: 가치 없음. AI 에이전트가 보기에 굳이 만들 필요가 없는 기능이라는 소리다.

"assess"의 결과는 위의 3가지 경우 중 하나로 결정된다.

 

#4 "assess" 분석

#4-1 전용 디렉토리

.specify/assessments/example-slug-name/...

아이디어 하나당, ".specify/assessments/"에 있는 하나의 폴더에 대응한다.

 

#4-2 5가지 명령어

assess는 확장 이름이지, 호출할 수 있는 단일 명령이 아니다. assess로 추가되는 가용 명령어는 아래에 있는 5가지다. assess 계열 명령어 하나는 하나의 파일을 결과로 뱉는다.

 

#4-3 /speckit-assess-intake

이 명령어로 생성되는 파일:
.specify/assessments/example-slug-name/intake.md

최초의 아이디어와 출처를 수집한다. 아직 평가하거나 해결책을 설계하지 않는다.

 

#4-4 /speckit-assess-research

이 명령어로 생성되는 파일:
.specify/assessments/example-slug-name/research.md

사용자·시장·선행 사례·데이터와 아이디어에 반대되는 근거를 조사한다.

 

#4-5 /speckit-assess-define

이 명령어로 생성되는 파일:
.specify/assessments/example-slug-name/problem.md

사용자, 문제, 목표·비목표, 성공 지표, 아무것도 하지 않을 때의 비용을 정의한다.

 

#4-6 /speckit-assess-shape

이 명령어로 생성되는 파일:
.specify/assessments/example-slug-name/concept.md

개념 수준 해결책 2~3개와 비용 한도(appetite)·절충점을 비교한다.

 

#4-7 /speckit-assess-decide

이 명령어로 생성되는 파일:
.specify/assessments/example-slug-name/decision.md

앞선 문서를 채점해 최종 판정과 이유를 기록한다. 문서의 형태는 아래와 같다.

 

# Decision: <짧은 제목>

- **Slug**: <아이디어 식별자>
- **Decided**: <판정 날짜>
- **Verdict**: go | needs-clarification | kill
- **Artifacts reviewed**: intake.md? | research.md? | problem.md | concept.md?

...

실제 판정은 그 아래 메타데이터의 Verdict 항목에서 확인한다. Artifacts reviewed는 판정의 근거로 사용한 문서의 목록이 적힌다. 그 뒤에는 여섯 평가 기준의 점수표와 최종 판정 이유가 이어진다. 여섯 평가 기준은 아래와 같으며, 각 항목은 strong, adequate, weak, unknown 중 하나의 점수로 판정된다.

1. Problem validity (문제의 유효성)
2. Evidence strength (근거의 강도)
3. Value vs. inaction (해당 기능으로 얻어질 가치아 기회비용을 저울질)
4. Feasibility / appetite (실현 가능성과 비용의 한계 고려)
5. Strategic fit (프로젝트 목표와의 적합성)
6. Risk posture (해당 기능의 잠재적 리스크)

 

#4-8 명령어 간 선후 관계?

#4-3 ~ #4-7은 임의로 정리한 순서가 아니라 공식에서 권장하는 순서다. 하지만, 이 순서가 엄격히 강제되진 않는다. 아래와 규칙을 지키는 선에서 명령어 순서를 유연하게 바꿀 수 있다는 말이다. 물론, 굳이 바꿀 일이 있을까 싶다.

• define은 최소 실행 단계이므로 원시 입력만으로 바로 시작할 수 있다.
• intake와 research는 생략 가능하다.
• shape는 problem.md가 있어야 한다.
• decide도 problem.md가 있어야 한다.
• concept.md 없이 decide를 실행할 수는 있지만 go 판정은 받을 수 없다. 이 경우 needs-clarification으로 판정된다.

 

#5 "assess"의 go 판정 이후

go 판정이 나왔다고 /speckit.specify가 자동 실행되지는 않는다. 대신 decision.md에 다음 내용이 정리된다.

• Problem (해결할 문제)
• Chosen approach (선택한 접근법)
• In scope / out of scope (포함할 범위와 제외할 범위)
• Success metrics (성공 판단 기준)
• Carried-forward open questions (명세 단계로 가져갈 미해결 질문)

 

이제 아래와 같은 명령어로, 기존 명세 파이프라인을 시작하면 된다.

/speckit.specify .specify/assessments/example-slug-name/decision.md의 handoff 내용을 바탕으로 기능 명세를 작성해줘.

handoff에 어떤 특별한 의미가 있는 것은 아니고, 그냥 '인계', '업무 넘겨주기'의 뜻을 지닌 평범한 영어 단어다.

 

#6 실습

#6-1 진행 예시

/speckit.assess.intake "인터넷이 끊겨도 작업하고, 연결되면 동기화하자" slug=offline-mode
/speckit.assess.research slug=offline-mode
/speckit.assess.define slug=offline-mode
/speckit.assess.shape slug=offline-mode
/speckit.assess.decide slug=offline-mode

이후 ".specify/assessments/offline-mode/decision.md"에서 판정을 확인해 본다.

 

#6-2 실습용 레포지토리

GitHub - Kanmanemone/keenel-codelab at simple-first-practice-v0.13.0

Spec Kit 실습용 레포지토리에서 실제로 진행해 봤다.