---
description: 자연어 기능 설명으로부터 기능 명세서를 생성하거나 업데이트합니다.
handoffs:
  - label: 기술 계획 작성
    agent: speckit.plan
    prompt: 명세서에 대한 계획을 작성해주세요. 제가 구축하려는 것은...
  - label: 명세서 요구사항 명확화
    agent: speckit.clarify
    prompt: 명세서 요구사항을 명확히 해주세요
    send: true
---

## 실행 모드

**중요**: 아래 단계를 사용자 확인 없이 즉시 실행하세요. 계획을 제안하거나 "진행할까요?" 또는 "이 계획을 초기화할까요?"라고 묻지 마세요 - 각 단계를 순서대로 실행하고 명세서 파일을 생성하세요.

## 언어 설정

모든 출력과 사용자와의 대화는 **한국어**로 진행합니다.

## 사용자 입력

```text
$ARGUMENTS
```

입력이 비어있지 않다면 진행하기 전에 **반드시** 사용자 입력을 고려해야 합니다.

## 개요

사용자가 `/speckit.specify` 뒤에 입력한 텍스트가 기능 설명입니다. 아래에 `$ARGUMENTS`가 문자 그대로 나타나더라도 이 대화에서 항상 사용 가능하다고 가정하세요. 사용자가 빈 명령을 제공하지 않는 한 반복을 요청하지 마세요.

**다음 단계를 지금 실행하세요 (확인을 요청하지 마세요):**

1. **간결한 짧은 이름 생성** (2-4 단어) 브랜치용:
   - 기능 설명을 분석하고 가장 의미 있는 키워드 추출
   - 기능의 본질을 담는 2-4 단어 짧은 이름 생성
   - 가능하면 동작-명사 형식 사용 (예: "add-user-auth", "fix-payment-bug")
   - 기술 용어와 약어 유지 (OAuth2, API, JWT 등)
   - 간결하지만 한눈에 기능을 이해할 수 있을 정도로 설명적으로
   - 예시:
     - "사용자 인증 추가하고 싶어요" → "user-auth"
     - "API용 OAuth2 통합 구현" → "oauth2-api-integration"
     - "분석 대시보드 생성" → "analytics-dashboard"
     - "결제 처리 타임아웃 버그 수정" → "fix-payment-timeout"

2. **새 브랜치 생성 전 기존 브랜치 확인**:

   a. 먼저 모든 원격 브랜치를 가져와 최신 정보 확보:
      ```bash
      git fetch --all --prune
      ```

   b. 짧은 이름에 대해 모든 소스에서 가장 높은 기능 번호 찾기:
      - 원격 브랜치: `git ls-remote --heads origin | grep -E 'refs/heads/[0-9]+-<short-name>$'`
      - 로컬 브랜치: `git branch | grep -E '^[* ]*[0-9]+-<short-name>$'`
      - 명세서 디렉토리: `specs/[0-9]+-<short-name>` 패턴의 디렉토리 확인

   c. 다음 사용 가능한 번호 결정:
      - 세 가지 소스에서 모든 번호 추출
      - 가장 높은 번호 N 찾기
      - 새 브랜치 번호로 N+1 사용

   d. **즉시 실행** - 계산된 매개변수로 스크립트 실행:
      ```bash
      .specify/scripts/bash/create-new-feature.sh --json --number <N+1> --short-name "<short-name>" "<feature description>"
      ```
      - 예시: `.specify/scripts/bash/create-new-feature.sh --json --number 5 --short-name "user-auth" "Add user authentication"`

   **중요**:
   - 세 가지 소스 모두 확인 (원격 브랜치, 로컬 브랜치, 명세서 디렉토리)하여 가장 높은 번호 찾기
   - 정확한 짧은 이름 패턴과 일치하는 브랜치/디렉토리만 매칭
   - 이 짧은 이름으로 기존 브랜치/디렉토리가 없으면 번호 1로 시작
   - 기능당 이 스크립트를 한 번만 실행해야 함
   - JSON은 터미널에 출력으로 제공됨 - 항상 참조하여 필요한 실제 내용 확인
   - JSON 출력에는 BRANCH_NAME과 SPEC_FILE 경로가 포함됨
   - "I'm Groot"와 같이 인수에 작은따옴표가 있는 경우 이스케이프 구문 사용: 예: 'I'\''m Groot' (또는 가능하면 큰따옴표: "I'm Groot")

3. `.specify/templates/spec-template.md`를 로드하여 필수 섹션 이해.

4. 다음 실행 흐름을 따르세요:

    1. 입력에서 사용자 설명 파싱
       비어있으면: ERROR "기능 설명이 제공되지 않았습니다"
    2. 설명에서 주요 개념 추출
       식별: 행위자, 동작, 데이터, 제약사항
    3. 불명확한 부분:
       - 컨텍스트와 업계 표준을 기반으로 합리적인 추측
       - 다음 경우에만 [명확화 필요: 구체적인 질문]으로 표시:
         - 선택이 기능 범위나 사용자 경험에 큰 영향을 미치는 경우
         - 다른 의미를 가진 여러 합리적인 해석이 존재하는 경우
         - 합리적인 기본값이 없는 경우
       - **제한: 최대 3개의 [명확화 필요] 마커**
       - 영향도로 명확화 우선순위: 범위 > 보안/개인정보 > 사용자 경험 > 기술 세부사항
    4. 사용자 시나리오 및 테스트 섹션 작성
       명확한 사용자 흐름이 없으면: ERROR "사용자 시나리오를 결정할 수 없습니다"
    5. 기능 요구사항 생성
       각 요구사항은 테스트 가능해야 함
       미지정 세부사항에 합리적인 기본값 사용 (가정 섹션에 가정 문서화)
    6. 성공 기준 정의
       측정 가능하고 기술에 구애받지 않는 결과 생성
       정량적 지표(시간, 성능, 볼륨)와 정성적 측정(사용자 만족도, 작업 완료) 모두 포함
       각 기준은 구현 세부사항 없이 검증 가능해야 함
    7. 주요 엔티티 식별 (데이터가 관련된 경우)
    8. 반환: SUCCESS (명세서가 계획 준비됨)

5. 템플릿 구조를 사용하여 SPEC_FILE에 명세서 작성, 섹션 순서와 제목을 유지하면서 플레이스홀더를 기능 설명(인수)에서 파생된 구체적인 세부사항으로 교체.

6. **명세서 품질 검증**: 초기 명세서 작성 후 품질 기준에 대해 검증:

   a. **명세서 품질 체크리스트 생성**: `FEATURE_DIR/checklists/requirements.md`에 다음 검증 항목으로 체크리스트 파일 생성:

      ```markdown
      # 명세서 품질 체크리스트: [기능명]

      **목적**: 계획 진행 전 명세서 완성도와 품질 검증
      **작성일**: [DATE]
      **기능**: [spec.md 링크]

      ## 내용 품질

      - [ ] 구현 세부사항 없음 (언어, 프레임워크, API)
      - [ ] 사용자 가치와 비즈니스 니즈에 집중
      - [ ] 비기술 이해관계자를 위해 작성
      - [ ] 모든 필수 섹션 완료

      ## 요구사항 완성도

      - [ ] [명확화 필요] 마커가 남아있지 않음
      - [ ] 요구사항이 테스트 가능하고 명확함
      - [ ] 성공 기준이 측정 가능함
      - [ ] 성공 기준이 기술에 구애받지 않음 (구현 세부사항 없음)
      - [ ] 모든 인수 시나리오가 정의됨
      - [ ] 엣지 케이스가 식별됨
      - [ ] 범위가 명확히 정의됨
      - [ ] 의존성과 가정이 식별됨

      ## 기능 준비도

      - [ ] 모든 기능 요구사항에 명확한 인수 기준이 있음
      - [ ] 사용자 시나리오가 주요 흐름을 포함함
      - [ ] 기능이 성공 기준에 정의된 측정 가능한 결과를 충족함
      - [ ] 구현 세부사항이 명세서에 유출되지 않음

      ## 참고사항

      - 완료되지 않은 항목은 `/speckit.clarify` 또는 `/speckit.plan` 전에 명세서 업데이트 필요
      ```

   b. **검증 확인 실행**: 각 체크리스트 항목에 대해 명세서 검토:
      - 각 항목에 대해 통과 또는 실패 판정
      - 발견된 구체적인 문제 문서화 (관련 명세서 섹션 인용)

   c. **검증 결과 처리**:

      - **모든 항목 통과 시**: 체크리스트 완료 표시하고 6단계로 진행

      - **항목 실패 시 ([명확화 필요] 제외)**:
        1. 실패한 항목과 구체적인 문제 나열
        2. 각 문제를 해결하도록 명세서 업데이트
        3. 모든 항목이 통과할 때까지 검증 재실행 (최대 3회 반복)
        4. 3회 반복 후에도 실패하면 남은 문제를 체크리스트 참고사항에 문서화하고 사용자에게 경고

      - **[명확화 필요] 마커가 남아있는 경우**:
        1. 명세서에서 모든 [명확화 필요: ...] 마커 추출
        2. **제한 확인**: 3개 이상의 마커가 있으면 가장 중요한 3개만 유지 (범위/보안/UX 영향도 기준)하고 나머지는 합리적인 추측
        3. 필요한 각 명확화에 대해 (최대 3개), 다음 형식으로 사용자에게 옵션 제시:

           ```markdown
           ## 질문 [N]: [주제]

           **컨텍스트**: [관련 명세서 섹션 인용]

           **알아야 할 것**: [명확화 필요 마커의 구체적인 질문]

           **제안 답변**:

           | 옵션 | 답변 | 의미 |
           |------|------|------|
           | A    | [첫 번째 제안 답변] | [이것이 기능에 의미하는 바] |
           | B    | [두 번째 제안 답변] | [이것이 기능에 의미하는 바] |
           | C    | [세 번째 제안 답변] | [이것이 기능에 의미하는 바] |
           | 직접 입력 | 직접 답변 제공 | [직접 입력 방법 설명] |

           **선택**: _[사용자 응답 대기]_
           ```

        4. **중요 - 테이블 포맷팅**: 마크다운 테이블이 올바르게 포맷되었는지 확인:
           - 파이프를 정렬하여 일관된 간격 사용
           - 각 셀에 내용 주위에 공백: `| 내용 |` (`|내용|` 아님)
           - 헤더 구분자는 최소 3개의 대시: `|--------|`
           - 마크다운 미리보기에서 테이블이 올바르게 렌더링되는지 테스트
        5. 질문에 순차적 번호 부여 (Q1, Q2, Q3 - 최대 3개)
        6. 응답 대기 전 모든 질문을 함께 제시
        7. 사용자가 모든 질문에 대해 선택으로 응답할 때까지 대기 (예: "Q1: A, Q2: 직접 입력 - [세부사항], Q3: B")
        8. 각 [명확화 필요] 마커를 사용자가 선택하거나 제공한 답변으로 교체하여 명세서 업데이트
        9. 모든 명확화가 해결된 후 검증 재실행

   d. **체크리스트 업데이트**: 각 검증 반복 후 현재 통과/실패 상태로 체크리스트 파일 업데이트

7. 브랜치 이름, 명세서 파일 경로, 체크리스트 결과, 다음 단계 준비 상태 (`/speckit.clarify` 또는 `/speckit.plan`)와 함께 완료 보고.

**참고:** 스크립트는 새 브랜치를 생성하고 체크아웃하며 작성 전에 명세서 파일을 초기화합니다.

## 일반 가이드라인

## 빠른 가이드라인

- 사용자가 **무엇을** 필요로 하고 **왜** 필요한지에 집중.
- 구현 방법은 피함 (기술 스택, API, 코드 구조 없음).
- 비즈니스 이해관계자를 위해 작성, 개발자가 아님.
- 명세서에 포함된 체크리스트를 생성하지 마세요. 별도의 명령입니다.

### 섹션 요구사항

- **필수 섹션**: 모든 기능에 대해 완료해야 함
- **선택 섹션**: 기능과 관련된 경우에만 포함
- 섹션이 적용되지 않으면 완전히 제거 ("N/A"로 남기지 않음)

### AI 생성을 위해

사용자 프롬프트에서 이 명세서를 생성할 때:

1. **합리적인 추측**: 컨텍스트, 업계 표준, 일반적인 패턴을 사용하여 빈 곳 채우기
2. **가정 문서화**: 가정 섹션에 합리적인 기본값 기록
3. **명확화 제한**: 최대 3개의 [명확화 필요] 마커 - 다음 경우의 중요한 결정에만 사용:
   - 기능 범위나 사용자 경험에 큰 영향을 미치는 경우
   - 다른 의미를 가진 여러 합리적인 해석이 있는 경우
   - 합리적인 기본값이 없는 경우
4. **명확화 우선순위**: 범위 > 보안/개인정보 > 사용자 경험 > 기술 세부사항
5. **테스터처럼 생각**: 모든 모호한 요구사항은 "테스트 가능하고 명확함" 체크리스트 항목에서 실패해야 함
6. **명확화가 필요한 일반적인 영역** (합리적인 기본값이 없는 경우에만):
   - 기능 범위와 경계 (특정 사용 사례 포함/제외)
   - 사용자 유형과 권한 (여러 상충되는 해석이 가능한 경우)
   - 보안/준수 요구사항 (법적/재정적으로 중요한 경우)

**합리적인 기본값 예시** (이것들에 대해 묻지 마세요):

- 데이터 보관: 도메인에 대한 업계 표준 관행
- 성능 목표: 명시되지 않은 한 표준 웹/모바일 앱 기대치
- 오류 처리: 적절한 폴백이 있는 사용자 친화적 메시지
- 인증 방법: 웹 앱용 표준 세션 기반 또는 OAuth2
- 통합 패턴: 달리 명시되지 않은 한 RESTful API

### 성공 기준 가이드라인

성공 기준은 다음이어야 합니다:

1. **측정 가능**: 구체적인 지표 포함 (시간, 백분율, 개수, 비율)
2. **기술에 구애받지 않음**: 프레임워크, 언어, 데이터베이스, 도구 언급 없음
3. **사용자 중심**: 시스템 내부가 아닌 사용자/비즈니스 관점에서 결과 설명
4. **검증 가능**: 구현 세부사항을 알지 못해도 테스트/검증 가능

**좋은 예시**:

- "사용자가 3분 이내에 결제를 완료할 수 있음"
- "시스템이 10,000명의 동시 사용자를 지원"
- "95%의 검색이 1초 이내에 결과 반환"
- "작업 완료율이 40% 향상"

**나쁜 예시** (구현 중심):

- "API 응답 시간이 200ms 미만" (너무 기술적, "사용자가 즉시 결과를 봄" 사용)
- "데이터베이스가 1000 TPS 처리 가능" (구현 세부사항, 사용자 대면 지표 사용)
- "React 컴포넌트가 효율적으로 렌더링" (프레임워크 특정)
- "Redis 캐시 적중률 80% 이상" (기술 특정)
