Communitygithub.com

명세서 보강기

현재 기능 명세에서 불명확하거나 누락된 부분을 식별하고, 최대 5개의 집중된 질문을 통해 이를 명확히 하여 명세서에 반영합니다.

명세서 보강기란 무엇인가요?

이 스킬은 기능 명세서의 모호함과 불완전성을 체계적으로 분석하고 해결하여, 명세의 품질을 높이고 구현 단계에서의 재작업 위험을 줄여줍니다. 주로 Claude Code, Cursor, Codex와 같은 AI 기반 개발 에이전트에서 사용되며, 사용자가 작업 중인 기능 명세 파일을 분석하여 최대 5개의 핵심 질문을 생성합니다. 각 질문은 다중 선택 또는 5단어 이내의 단답형으로 답변 가능하도록 구성되어 있어, 사용자가 빠르고 명확하게 의사 결정을 내릴 수 있도록 돕습니다. 질문에 대한 답변이 수락되면, 스킬은 해당 내용을 즉시 명세서의 적절한 섹션(예: 기능 요구사항, 데이터 모델, 비기능적 제약 조건 등)에 반영하고, 파일을 저장하여 변경 사항이 손실되지 않도록 합니다. 또한, 선택적으로 `.specify/extensions.yml` 파일에 정의된 확장 훅을 사전에 실행하거나, 요구사항 체크리스트 파일을 업데이트하는 기능을 제공하여, 더욱 정교한 워크플로우를 지원합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/tangjuyo/reels-blocker/tree/HEAD/.claude/skills/speckit-clarify

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

사용자 입력

$ARGUMENTS

진행하기 전에 사용자 입력을 반드시 고려해야 합니다(비어 있지 않은 경우).

사전 실행 검사

확장 훅 확인 (질문 전):

  • 프로젝트 루트에 .specify/extensions.yml 파일이 있는지 확인합니다.
  • 파일이 있으면, hooks.before_clarify 키 아래의 항목을 읽습니다.
  • YAML을 구문 분석할 수 없거나 유효하지 않은 경우, 무시하지 않고 .specify/extensions.yml 파일을 읽을 수 없다는 메시지(파서 오류 포함)와 함께 어떤 훅도 확인되지 않았으며, 여기에 등록된 필수(optional: false) 훅도 확인되지 않았음을 사용자에게 알린 후 정상적으로 계속 진행합니다.
  • enabled가 명시적으로 false인 훅은 필터링합니다. enabled 필드가 없는 훅은 기본적으로 활성화된 것으로 간주합니다.
  • 나머지 각 훅에 대해, 훅 condition 표현식을 해석하거나 평가하려고 시도하지 않습니다:
    • 훅에 condition 필드가 없거나 null/비어 있으면, 훅을 실행 가능한 것으로 간주합니다.
    • 훅에 비어 있지 않은 condition이 정의되어 있으면, 해당 훅을 건너뛰고 조건 평가는 HookExecutor 구현에 맡깁니다.
  • 훅 명령어 이름에서 점(.)을 하이픈(-)으로 바꾸어 명령어 호출을 구성합니다. 예를 들어, speckit.git.commit → /speckit-git-commit과 같습니다.
  • 실행 가능한 각 훅에 대해, optional 플래그에 따라 다음을 출력합니다:
    • 선택적 훅 (optional: true):
      ## 확장 훅
      
      **선택적 사전 훅**: {extension}
      명령어: `/{command}`
      설명: {description}
      
      프롬프트: {prompt}
      실행하려면: `/{command}`
      
    • 필수 훅 (optional: false):
      ## 확장 훅
      
      **자동 사전 훅**: {extension}
      실행 중: `/{command}`
      명령어 실행: {command}
      
      개요로 진행하기 전에 훅 명령어의 결과를 기다리십시오.
      
      위 블록을 출력한 후에는 실제로 훅을 호출하고 계속 진행하기 전에 완료될 때까지 기다려야 합니다. 이 에이전트/세션에서 명령어를 직접 실행하는 것과 동일한 방식으로 실행합니다(호출 방식은 위에 표시된 리터럴 {command} ID와 다를 수 있습니다. 예를 들어, skills-mode 에이전트는 /skill:speckit-... 또는 $speckit-... 형식으로 실행합니다). 블록만 출력하는 것으로는 훅이 실행되지 않습니다.
  • 등록된 훅이 없거나 .specify/extensions.yml 파일이 존재하지 않으면, 조용히 건너뜁니다.

개요

목표: 활성 기능 명세서의 모호함이나 누락된 결정 지점을 감지하고 줄여 명확하게 한 내용을 명세 파일에 직접 기록합니다.

참고: 이 명확화 워크플로우는 /speckit-plan을 호출하기 전에 실행(및 완료)되어야 합니다. 사용자가 명확화를 생략하겠다고 명시적으로 밝히는 경우(예: 탐색적 스파이크), 진행할 수 있지만 다운스트림 재작업 위험이 증가한다고 경고해야 합니다.

실행 단계:

  1. 저장소 루트에서 .specify/scripts/bash/check-prerequisites.sh --json --paths-only를 한 번 실행합니다(결합된 --json --paths-only 모드 / -Json -PathsOnly). 최소 JSON 페이로드 필드를 구문 분석합니다:

    • FEATURE_DIR
    • FEATURE_SPEC
    • (선택적으로 향후 연결된 흐름을 위해 IMPL_PLAN, TASKS를 캡처합니다.)
    • JSON 구문 분석에 실패하면 중단하고 사용자에게 /speckit-specify를 다시 실행하거나 기능 브랜치 환경을 확인하도록 안내합니다.
    • "I'm Groot"와 같은 인수에 작은따옴표가 포함된 경우, 이스케이프 구문을 사용합니다(예: 'I'''m Groot' 또는 가능하면 큰따옴표 사용: "I'm Groot").
  2. 존재하는 경우: 프로젝트 원칙 및 거버넌스 제약 조건을 위해 .specify/memory/constitution.md를 로드합니다.

  3. 현재 명세 파일을 로드합니다. 다음 분류 체계를 사용하여 구조화된 모호성 및 범위 검사를 수행합니다. 각 범주에 대해 상태를 표시합니다: 명확 / 부분적 / 누락. 우선 순위 지정에 사용되는 내부 범위 맵을 생성합니다(질문이 없을 경우 원시 맵을 출력하지 않음).

    기능 범위 및 동작:

    • 핵심 사용자 목표 및 성공 기준
    • 명시적인 범위 외 선언
    • 사용자 역할 / 페르소나 차별화

    도메인 및 데이터 모델:

    • 엔티티, 속성, 관계
    • ID 및 고유성 규칙
    • 수명 주기/상태 전환
    • 데이터 볼륨/규모 가정

    상호 작용 및 UX 흐름:

    • 중요한 사용자 여정/시퀀스
    • 오류/빈/로딩 상태
    • 접근성 또는 현지화 참고 사항

    비기능적 품질 속성:

    • 성능(지연 시간, 처리량 목표)
    • 확장성(수평/수직, 제한)
    • 신뢰성 및 가용성(가동 시간, 복구 기대치)
    • 관찰 가능성(로깅, 메트릭, 추적 신호)
    • 보안 및 개인 정보 보호(인증/권한 부여, 데이터 보호, 위협 가정)
    • 규정 준수/규제 제약 조건(해당하는 경우)

    통합 및 외부 종속성:

    • 외부 서비스/API 및 실패 모드
    • 데이터 가져오기/내보내기 형식
    • 프로토콜/버전 관리 가정

    에지 케이스 및 오류 처리:

    • 부정적 시나리오
    • 속도 제한/스로틀링
    • 충돌 해결(예: 동시 편집)

    제약 조건 및 트레이드오프:

    • 기술적 제약 조건(언어, 스토리지, 호스팅)
    • 명시적인 트레이드오프 또는 거부된 대안

    용어 및 일관성:

    • 표준 용어집 용어
    • 피해야 할 동의어/더 이상 사용되지 않는 용어

    완료 신호:

    • 승인 기준 테스트 가능성
    • 측정 가능한 완료 정의 스타일 지표

    기타 / 자리 표시자:

    • TODO 마커 / 해결되지 않은 결정
    • 정량화가 부족한 모호한 형용사("강력한", "직관적인")

    상태가 부분적 또는 누락인 각 범주에 대해 후보 질문 기회를 추가합니다. 단, 다음의 경우는 제외합니다:

    • 명확화가 구현 또는 검증 전략에 실질적으로 영향을 미치지 않는 경우
    • 해당 항목이 구체적으로 구현 방법, 기술 스택 비교 또는 작업 분류에 관한 경우(내부적으로 기록)
  4. 후보 명확화 질문의 우선 순위 대기열을 (내부적으로) 생성합니다(최대 5개). 한 번에 모두 출력하지 않습니다. 다음 제약 조건을 적용합니다:

    • 전체 세션 동안 총 5개의 질문으로 제한합니다.
    • 각 질문은 다음 중 하나로 답변할 수 있어야 합니다:
      • 짧은 다중 선택(2~5개의 상호 배타적인 옵션), 또는
      • 한 단어/짧은 구문 답변(명시적으로 제한: "5단어 이내로 답변").
    • 아키텍처, 데이터 모델링, 작업 분류, 테스트 설계, UX 동작, 운영 준비 상태 또는 규정 준수 검증에 실질적인 영향을 미치는 질문만 포함합니다.
    • 범주 범위 균형을 유지합니다: 먼저 가장 영향력이 큰 해결되지 않은 범주를 다루려고 시도합니다. 보안 태세와 같은 단일 고영향 영역이 해결되지 않은 상태에서 낮은 영향의 질문 두 개를 묻는 것을 피합니다.
    • 이미 답변된 질문, 사소한 스타일 선호도, 또는 계획 수준의 실행 세부 사항(정확성을 차단하지 않는 한)은 제외합니다.
    • 다운스트림 재작업 위험을 줄이거나 잘못 정렬된 승인 테스트를 방지하는 명확화를 선호합니다.
    • 5개 이상의 범주가 해결되지 않은 상태로 남아 있으면, (영향 * 불확실성) 휴리스틱에 따라 상위 5개를 선택합니다.
  5. 순차적 질문 루프(대화형):

    • 한 번에 정확히 하나의 질문을 제시합니다.

    • 질문 작성 품질(모든 질문, MC 또는 단답형에 적용):

      • **질문:**으로 시작하고 ?로 끝나는 완전한 의문문을 사용합니다. ? 앞의 질문 텍스트는 그 자체로 의미가 있어야 합니다.
      • 절대 주제 레이블, 섹션 제목 또는 요구 사항 ID를 질문 자체로 사용하지 마십시오. 예를 들어, 수락 장치/런타임 매트릭스 (FR-023)은(는) 유효하지 않습니다. 레이블일 뿐 질문이 아닙니다.
      • ? 뒤에는 선택적 괄호로 묶인 요구 사항/질문 ID만 허용됩니다. 정확한 형식: **질문:** <의문문>? 또는 **질문:** <의문문>? (FR-023). ID를 ? 앞에 절대 배치하지 말고, ID를 (단독으로 또는 주제 레이블과 함께) 전체 프롬프트로 사용하지 마십시오.
      • 질문 줄 바로 다음에, 추천/옵션 앞에 하나의 평이한 언어로 된 "중요한 이유" 문장(수락 또는 출시에 대한 이해 관계)을 추가합니다.
      • 일상적인 표현을 사용합니다. 전문 용어는 같은 문장에서 정의된 경우에만 도입합니다. 자체 점검: Spec Kit을 모르는 독자가 질문 줄만으로 답변할 수 있어야 합니다. 간결해도 괜찮습니다. 암호 같은 레이블은 안 됩니다.
    • 객관식 질문의 경우:

      • 모든 옵션을 분석하고 다음을 기반으로 가장 적합한 옵션을 결정합니다:
        • 프로젝트 유형에 대한 모범 사례
        • 유사한 구현에서의 일반적인 패턴
        • 위험 감소(보안, 성능, 유지 보수성)
        • 명세에 표시된 명시적인 프로젝트 목표 또는 제약 조건과의 정렬
      • 추천 옵션을 맨 위에 눈에 띄게 명확한 근거와 함께 제시합니다(이것이 최선의 선택인 이유를 설명하는 1-2 문장).
      • 형식: **추천:** 옵션 [X] - <근거>
      • 그런 다음 모든 옵션을 Markdown 테이블로 렌더링합니다:
      옵션설명
      A<옵션 A 설명>
      B<옵션 B 설명>
      C<옵션 C 설명> (필요에 따라 최대 5개까지 D/E 추가)
      단답다른 짧은 답변 제공(<=5단어) (자유 형식 대안이 적절한 경우에만 포함)
      • 테이블 뒤에 다음을 추가합니다: 옵션 문자(예: "A")로 답변하거나, "yes" 또는 "recommended"라고 말하여 추천을 수락하거나, 자신의 짧은 답변을 제공할 수 있습니다.
    • 단답형 스타일(의미 있는 개별 옵션이 없는 경우):

      • 모범 사례와 컨텍스트를 기반으로 제안된 답변을 제공합니다.
      • 형식: **제안:** <제안된 답변> - <간단한 근거>
      • 그런 다음 다음을 출력합니다: 형식: 짧은 답변 (<=5단어). "yes" 또는 "suggested"라고 말하여 제안을 수락하거나, 자신의 답변을 제공할 수 있습니다.
    • 사용자가 답변한 후:

      • 사용자가 "yes", "recommended" 또는 "suggested"라고 답변하면, 이전에 명시한 추천/제안을 답변으로 사용합니다.
      • 그렇지 않으면, 답변이 하나의 옵션에 매핑되거나 5단어 이하 제약 조건에 맞는지 확인합니다.
      • 모호한 경우, 빠른 명확화를 요청합니다(카운트는 동일한 질문에 속함; 진행하지 않음).
      • 만족스러우면, 작업 메모리에 기록하고(아직 디스크에 쓰지 않음) 다음 대기 질문으로 이동합니다.
    • 다음과 같은 경우 추가 질문을 중단합니다:

      • 모든 중요한 모호함이 조기에 해결된 경우(나머지 대기 항목이 불필요해짐), 또는
      • 사용자가 완료 신호를 보낸 경우("done", "good", "no more"), 또는
      • 5개의 질문을 한 경우.
    • 향후 대기 중인 질문을 미리 절대 공개하지 않습니다.

    • 시작 시 유효한 질문이 없으면, 즉시 중요한 모호함이 없다고 보고합니다.

  6. 각 수락된 답변 후 통합(증분 업데이트 방식):

    • 명세의 메모리 내 표현(처음에 한 번 로드됨)과 원시 파일 내용을 유지합니다.
    • 이 세션에서 첫 번째 통합된 답변의 경우:
      • ## 명확화 섹션이 있는지 확인합니다(없는 경우 명세 템플릿당 가장 높은 수준의 컨텍스트/개요 섹션 바로 뒤에 생성).
      • 그 아래에 오늘 날짜의 ### 세션 YYYY-MM-DD 하위 제목을 생성합니다(없는 경우).
    • 수락 직후에 글머리 기호 줄을 추가합니다: - Q: <질문> → A: <최종 답변>.
    • 그런 다음 즉시 가장 적절한 섹션에 명확화를 적용합니다:
      • 기능적 모호함 → 기능 요구 사항의 글머리 기호를 업데이트하거나 추가합니다.
      • 사용자 상호 작용/행위자 구분 → 사용자 스토리 또는 행위자 하위 섹션(있는 경우)을 명확화된 역할, 제약 조건 또는 시나리오로 업데이트합니다.
      • 데이터 형태/엔티티 → 데이터 모델 업데이트(필드, 유형, 관계 추가)하고 순서를 유지합니다. 추가된 제약 조건을 간결하게 기록합니다.
      • 비기능적 제약 조건 → 성공 기준 > 측정 가능한 결과에서 측정 가능한 기준을 추가/수정합니다(모호한 형용사를 메트릭 또는 명시적 목표로 변환).
      • 에지 케이스/부정적 흐름 → 에지 케이스 / 오류 처리 아래에 새 글머리 기호를 추가합니다(또는 템플릿이 이에 대한 자리 표시자를 제공하는 경우 해당 하위 섹션을 생성).
      • 용어 충돌 → 명세 전반에 걸쳐 용어를 정규화합니다. 필요한 경우에만 (이전에는 "X"라고 함)을 추가하여 원본을 유지합니다.
    • 명확화가 이전의 모호한 진술을 무효화하는 경우, 중복하지 말고 해당 진술을 대체합니다. 구식의 모순된 텍스트를 남기지 않습니다.
    • 각 통합 후에 명세 파일을 저장하여 컨텍스트 손실 위험을 최소화합니다(원자적 덮어쓰기).
    • 서식을 유지합니다. 관련 없는 섹션의 순서를 변경하지 말고, 제목 계층을 그대로 유지합니다.
    • 삽입된 각 명확화를 최소한으로 유지하고 테스트 가능하게 만듭니다(서사적 표류 방지).
  7. 검증(각 쓰기 후 및 최종 패스 후 수행):

    • 명확화 세션에는 수락된 답변당 정확히 하나의 글머리 기호가 포함됩니다(중복 없음).
    • 총 질문(수락된) 수 ≤ 5.
    • 업데이트된 섹션에는 새 답변이 해결해야 하는 남아있는 모호한 자리 표시자가 없어야 합니다.
    • 모순된 이전 진술이 남아 있지 않아야 합니다(이제 유효하지 않은 대안 선택이 제거되었는지 스캔).
    • Markdown 구조가 유효해야 합니다. 허용되는 새 제목만: ## 명확화, ### 세션 YYYY-MM-DD.
    • 용어 일관성: 업데이트된 모든 섹션에서 동일한 표준 용어를 사용해야 합니다.
  8. 업데이트된 명세를 FEATURE_SPEC에 다시 씁니다.

  9. 명세 품질 체크리스트 재검증(존재하는 경우):

    • FEATURE_DIR/checklists/requirements.md 파일이 있는지 확인합니다.
    • 파일이 없으면, 이 단계를 조용히 건너뜁니다.
    • 파일이 있는 경우:
      1. 체크리스트 파일을 읽습니다.
      2. GitHub 작업 목록 체크박스 줄을 모두 식별합니다 — 코드 펜스 외부에서 - [ ], - [x] 또는 - [X]와 일치하는 줄(대소문자 구분 안 함, 중첩 항목의 경우 선행 공백 허용). 다른 모든 내용(제목, 메모, 체크박스가 아닌 글머리 기호, 메타데이터)은 무시합니다.
      3. 각 체크박스 줄에 대해 현재 마커 상태(선택됨 또는 선택 안 됨)와 항목 텍스트를 이전 스냅샷 목록에 기록합니다.
      4. 업데이트된 명세(7단계에서 방금 저장된 버전)에 대해 각 체크박스 항목을 재평가합니다.
      5. 선택/선택 해제 상태가 실제로 변경되는 경우에만 각 체크박스 항목을 업데이트합니다:
        • 항목이 이제 통과하고 이전에 선택되지 않은 경우: [ ]를 [x]로 변경합니다.
        • 항목이 이제 실패하고 이전에 선택된 경우: [x]/[X]를 [ ]로 변경합니다.
        • 상태가 변경되지 않은 경우: 변경하지 않고 그대로 둡니다.
      6. 상태가 변경된 각 체크박스 항목에 대해 설명하는 요약 메시지를 출력합니다:
        • 새로 선택됨: - [x] ~task 텍스트~ (업데이트된 명세에 따라 해결됨)
        • 새로 선택 해제됨: - [ ] ~task 텍스트~ (업데이트된 명세에 따라 더 이상 충족되지 않음)
      7. 두 경우 모두 변경된 체크박스 줄로 인해 뒤따르는 중첩 체크박스의 계층 구조가 변경될 수 있습니다. 계층 구조가 깨지지 않도록 수동으로 수정하지 말고, 대신 방금 저장한 명세 파일에 대한 각 후속 호출이 자체적인 읽기-재평가-쓰기 주기를 수행한다는 점에 의존하십시오. 원래 체크박스 줄만 업데이트하고, 체크박스 외부의 모든 내용(제목, 메모, 표, 코드 펜스)은 그대로 둡니다.
      8. 업데이트된 체크리스트를 FEATURE_DIR/checklists/requirements.md에 다시 씁니다.
      9. 최종 업데이트된 체크리스트를 사용자에게 표시하지 마십시오. 대신 체크리스트 재검증이 완료되었으며 위에서 언급된 변경 사항(있는 경우)이 적용되었다는 상태를 요약합니다.
  10. 최종적으로, ## 명확화 섹션의 현재 세션(세션 YYYY-MM-DD) 아래에 걸린 질문이 하나도 없는지 확인합니다. 세션이 동기화되었음을 나타냅니다.

  11. 아래 요약 출력 후 종료합니다:

    ---
    - **질문한 질문 수**: {number}
    - **다룬 범주**: {comma-separated list}
    - **다음 단계**: 기능 명세가 명확합니다. `/speckit-plan`을 실행하여 구현 계획을 생성하십시오.
    

Individual skills in this repo

This repo contains 9 individual skills — each has its own dedicated page.

관련 스킬