Spec Generator

수집한 정보를 바탕으로 5가지 EARS 유형으로 요구사항을 정의합니다:

Ubiquitous (보편적)

• "시스템은 ~해야 한다"
• 항상 참인 기본 동작

Event-driven (이벤트 기반)

• "WHEN ~하면, IF ~라면, THEN ~해야 한다"
• 이벤트에 대한 시스템 응답

State-driven (상태 기반)

• "WHILE ~인 동안, ~해야 한다"
• 특정 상태 유지

Unwanted (바람직하지 않은)

• "시스템은 ~하면 안 된다"
• 금지된 동작

Optional (선택적)

• "가능하다면, ~해야 한다"
• Nice-to-have

3단계: SPEC 파일 생성

/spec-create 커맨드를 실행하여 3-file 구조를 생성:

docs/specs/{feature-name}/
├── spec.md         # EARS 요구사항
├── plan.md         # 구현 계획
├── acceptance.md   # Given/When/Then 인수 기준
└── CHANGELOG.md    # 변경 이력

4단계: 요구사항 작성 (spec.md)

생성된 spec.md를 열고 실제 요구사항을 함께 작성합니다:

5단계: 구현 계획 작성 (plan.md)

spec.md의 요구사항을 바탕으로 plan.md를 자동으로 작성합니다:

5-1. Technical Approach 정의

• 데이터 저장 방식 (PostgreSQL, MongoDB, Redis 등)
• API 설계 (REST, GraphQL, tRPC)
• 상태 관리 (Zustand, TanStack Query, React Context)
• 인증 방식 (JWT, Session, OAuth)

5-2. Data Model 설계

-- 데이터베이스 스키마 작성
CREATE TABLE {feature} (
    id UUID PRIMARY KEY,
    -- 필드 정의
);

5-3. API Endpoints 정의

GET    /api/{feature}           - 목록 조회
GET    /api/{feature}/:id       - 상세 조회
POST   /api/{feature}           - 생성
PUT    /api/{feature}/:id       - 수정
DELETE /api/{feature}/:id       - 삭제

5-4. Implementation Tasks 작성 spec.md의 Event-driven 요구사항을 태스크로 변환:

• [E-001] → TASK-001: 제품 추가 기능 구현
• [E-002] → TASK-002: 수량 수정 기능 구현
• [E-003] → TASK-003: 항목 삭제 기능 구현

각 태스크에 예상 시간과 의존성 추가:

- [ ] TASK-001: 제품 추가 기능 구현
  - Estimated: 3시간
  - Dependencies: 없음

5-5. Estimated Effort 계산 모든 태스크의 예상 시간을 합산하여 총 노력량 계산

5-6. Risk Assessment 작성 주요 리스크 식별 및 완화 방안 작성

6단계: 인수 기준 작성 (acceptance.md)

spec.md의 Event-driven 요구사항을 Given/When/Then로 변환:

변환 규칙:

[E-001] WHEN 사용자가 장바구니에 제품을 추가하면,
        IF 제품이 이미 장바구니에 있으면,
        THEN 시스템은 기존 수량에 새 수량을 더해야 한다.

↓ 변환 ↓

**[AC-001] 사용자는 장바구니에 제품을 추가할 수 있다**

Given:
- 사용자가 로그인되어 있다
- 장바구니 페이지에 접근했다
- 제품이 이미 장바구니에 있다

When:
- 사용자가 동일한 제품을 추가한다

Then:
- 장바구니에 기존 수량 + 새 수량이 표시된다
- 총 금액이 재계산된다

6-1. 주요 시나리오 작성 spec.md의 모든 Event-driven 요구사항을 시나리오로 변환

6-2. Edge Cases 작성

• 네트워크 오류
• 대용량 데이터
• 동시성 문제
• 권한 없는 접근

6-3. Performance Criteria 작성 spec.md의 Performance 요구사항을 인수 기준으로 변환

6-4. Security Criteria 작성 spec.md의 Security 요구사항을 인수 기준으로 변환

6-5. Testing Checklist 작성

• Manual Testing 리스트
• Automated Testing (E2E) 리스트
• Security Testing 리스트
• Accessibility Testing 리스트

예시: 사용자 인증 피처

**[U-001]**
시스템은 사용자의 비밀번호를 bcrypt로 해싱하여 저장해야 한다.

**[E-001]**
WHEN 사용자가 로그인을 요청하면,
IF 이메일과 비밀번호가 유효하면,
THEN 시스템은 JWT 토큰을 발행하고 반환해야 한다.

**[S-001]**
WHILE 사용자가 로그인되어 있는 동안,
시스템은 세션을 1시간마다 갱신해야 한다.

**[UW-001]**
시스템은 미인증 사용자의 보호된 리소스 접근을 허용하면 안 된다.

**[O-001]**
가능하다면, 시스템은 OAuth 2.0 소셜 로그인을 제공해야 한다.

EARS 작성 가이드

Ubiquitous (보편적)

사용 경우:

• 보안 요구사항
• 데이터 무결성
• 항상 지켜져야 할 규칙

템플릿:

시스템은 [항상 참인 동작]해야 한다.

예시:

• 시스템은 모든 API 요청을 인증해야 한다.
• 시스템은 사용자 데이터를 암호화하여 저장해야 한다.

Event-driven (이벤트 기반)

사용 경우:

• 사용자 액션에 대한 응답
• API 엔드포인트 동작
• 에러 처리

템플릿:

WHEN [이벤트]하면,
IF [조건]라면,
THEN 시스템은 [응답]해야 한다.

예시:

• WHEN 사용자가 결제를 요청하면, IF 잔액이 충분하면, THEN 결제를 승인해야 한다.
• WHEN API 호출이 실패하면, IF 500 에러이면, THEN 재시도해야 한다.

State-driven (상태 기반)

사용 경우:

• 장시간 실행되는 프로세스
• 실시간 동기화
• 연결 유지

템플릿:

WHILE [상태]인 동안,
시스템은 [유지할 동작]해야 한다.

예시:

• WHILE 파일 업로드가 진행 중인 동안, 시스템은 진행률을 표시해야 한다.
• WHILE WebSocket 연결이 활성화된 동안, 시스템은 하트비트를 전송해야 한다.

Unwanted (바람직하지 않은)

사용 경우:

• 보안 취약점 방지
• 데이터 손실 방지
• 잘못된 동작 방지

템플릿:

시스템은 [금지된 동작]하면 안 된다.

예시:

• 시스템은 민감 정보를 로그에 기록하면 안 된다.
• 시스템은 사용자 동의 없이 데이터를 삭제하면 안 된다.

Optional (선택적)

사용 경우:

• 향후 개선 사항
• 리소스가 여유로울 때만 가능
• MVP에서 제외된 기능

템플릿:

가능하다면, 시스템은 [선택적 기능]해야 한다.

예시:

• 가능하다면, 시스템은 오프라인 모드를 지원해야 한다.
• 가능하다면, 시스템은 다크 모드를 제공해야 한다.

완료 기준

다음이 완료되면 스킬 작업을 종료합니다:

1. ✅ 피처 이름과 목적이 명확히 정의됨
2. ✅ 최소 3개 이상의 EARS 요구사항이 작성됨
3. ✅ spec.md, plan.md, acceptance.md 파일이 생성됨
4. ✅ CHANGELOG.md가 초기화됨
5. ✅ 사용자가 추가 질문이 없다고 확인함

모범 사례

1. 요구사항은 구체적으로

❌ 나쁨:

시스템은 빨라야 한다.

✅ 좋음:

[P-001] 목록 조회 API는 200ms 이내에 응답해야 한다.

2. EARS 유형을 올바르게 사용

❌ 나쁨 (Ubiquitous를 Event-driven로):

WHEN 사용자가 데이터를 저장하면, 시스템은 보안을 유지해야 한다.

✅ 좋음:

[U-001] 시스템은 모든 사용자 데이터를 암호화하여 저장해야 한다.

3. 사용자 관점에서 작성

❌ 나쁨 (구현 관점):

시스템은 PostgreSQL에 데이터를 저장해야 한다.

✅ 좋음 (사용자 관점):

시스템은 사용자 데이터를 영구적으로 저장하고 복구할 수 있어야 한다.

트리거 예시

다음 말들을 하면 이 스킬이 자동으로 활성화됩니다:

• "장바구니 기능 개발할건데 스펙 작성해줘"
• "사용자 프로필 기능 추가하려고"
• "결제 시스템 구현할건데 요구사항 정리해줘"
• "/spec-create payment-gateway"

주의사항

1. EARS 형식 엄수: 5가지 유형을 명확히 구분해서 작성
2. 한 요구사항 = 한 문장: 너무 복잡하게 하지 말기
3. 테스트 가능성: Given/When/Then으로 변환 가능한지 확인
4. 사용자 중심: "시스템이 어떻게"가 아니라 "사용자가 무엇을" 중심으로

이 스킬은 EARS 형식을 사용하여 명확하고 테스트 가능한 요구사항을 작성하도록 도와드립니다.