명세 작성 스킬 (Spec Writing Skill)

개요

이 스킬은 사용자의 요구사항을 체계적으로 분석하여 명세서(Specification)와 사용자 스토리(User Story)를 작성합니다. 모든 문서는 양방향 추적성 매트릭스(Bidirectional Traceability Matrix)로 관리됩니다.

실행 조건

다음과 같은 요청 시 이 스킬이 활성화됩니다:

• "명세 작성해줘"
• "요구사항 정리해줘"
• "스펙 문서 만들어줘"
• "사용자 스토리 작성해줘"
• "기능 명세서 작성"

작업 흐름

Phase 1: 요구사항 수집 및 분석

1. 요구사항 확인

   • 사용자로부터 기능 요구사항 수집
   • 불명확한 부분은 질문을 통해 명확화
   • 비기능 요구사항(성능, 보안 등) 파악

2. 요구사항 분류

   • 기능 요구사항 (Functional Requirements)
   • 비기능 요구사항 (Non-Functional Requirements)
   • 제약 조건 (Constraints)

Phase 2: 명세서 작성

파일 위치: docs/specs/SPEC-{번호}-{기능명}.md

명세서 템플릿:

# SPEC-{번호}: {기능명}

## 메타데이터
- **버전**: 1.0.0
- **작성일**: {날짜}
- **상태**: Draft | Review | Approved
- **관련 스토리**: US-{번호}

## 1. 개요
{기능에 대한 간략한 설명}

## 2. 기능 요구사항

### FR-{번호}.1: {요구사항 제목}
- **설명**: {상세 설명}
- **우선순위**: High | Medium | Low
- **수용 기준**: {기준}

## 3. 비기능 요구사항

### NFR-{번호}.1: {요구사항 제목}
- **카테고리**: 성능 | 보안 | 확장성 | 가용성
- **설명**: {상세 설명}
- **측정 기준**: {기준}

## 4. 제약 조건
- {제약 조건 목록}

## 5. 의존성
- {의존하는 다른 명세 또는 시스템}

## 6. 추적성
- **사용자 스토리**: US-{번호}
- **테스트 케이스**: TC-{번호}

Phase 3: 사용자 스토리 작성

파일 위치: docs/user-stories/US-{번호}-{기능명}.md

중요: 사용자 스토리의 "사용자"는 항상 **최종 사용자(End User)**를 의미합니다.

사용자 스토리 템플릿:

# US-{번호}: {스토리 제목}

## 메타데이터
- **Epic**: {에픽명}
- **우선순위**: High | Medium | Low
- **스토리 포인트**: {포인트}
- **관련 명세**: SPEC-{번호}

## 사용자 스토리

**As a** {최종 사용자 역할}
**I want** {원하는 기능/행동}
**So that** {얻고자 하는 가치/이유}

## 인수 조건 (Acceptance Criteria)

### AC-{번호}.1: {조건 제목}
**Given** {사전 조건}
**When** {실행 조건}
**Then** {기대 결과}

### AC-{번호}.2: {조건 제목}
**Given** {사전 조건}
**When** {실행 조건}
**Then** {기대 결과}

## 인수 테스트 (Acceptance Tests)

### AT-{번호}.1: {테스트명}
- **관련 AC**: AC-{번호}.1
- **테스트 유형**: E2E | Integration | API
- **테스트 시나리오**:
  1. {단계 1}
  2. {단계 2}
  3. {단계 3}
- **예상 결과**: {결과}

### AT-{번호}.2: {테스트명}
- **관련 AC**: AC-{번호}.2
- **테스트 유형**: E2E | Integration | API
- **테스트 시나리오**:
  1. {단계 1}
  2. {단계 2}
- **예상 결과**: {결과}

## 기술 노트
- {구현 관련 기술적 고려사항}

## 추적성
- **명세서**: SPEC-{번호}
- **테스트 케이스**: TC-{번호}
- **구현 태스크**: TASK-{번호}

Phase 4: 추적성 매트릭스 업데이트

파일 위치: docs/traceability-matrix.md

모든 명세서와 사용자 스토리 작성 후, 추적성 매트릭스를 업데이트합니다.

## 추적성 매트릭스 항목 추가

| 요구사항 ID | 명세서 ID | 사용자 스토리 ID | 인수 테스트 ID | 테스트 케이스 ID | 구현 상태 |
|------------|----------|-----------------|---------------|-----------------|----------|
| REQ-{번호} | SPEC-{번호} | US-{번호} | AT-{번호}.x | TC-{번호} | 미착수 |

산출물

이 스킬 실행 후 다음 문서들이 생성/업데이트됩니다:

1. docs/specs/SPEC-{번호}-{기능명}.md - 기능 명세서
2. docs/user-stories/US-{번호}-{기능명}.md - 사용자 스토리 (인수 테스트 포함)
3. docs/traceability-matrix.md - 추적성 매트릭스 업데이트

주의사항

1. 사용자 정의: 사용자 스토리에서 "사용자"는 반드시 최종 사용자여야 합니다. 개발자, 시스템 관리자가 아닌 실제 서비스를 이용하는 사람의 관점에서 작성합니다.

2. 인수 테스트 필수: 모든 인수 조건(AC)에는 대응하는 인수 테스트(AT)가 있어야 합니다.

3. 추적성 유지: 모든 문서는 ID를 통해 서로 연결되어야 하며, 추적성 매트릭스에 반영되어야 합니다.

4. 버전 관리: 명세서 수정 시 버전을 업데이트하고 변경 이력을 기록합니다.

다음 단계

명세 작성이 완료되면:

• 신규 프로젝트인 경우: project-bootstrap 스킬로 프로젝트 구조 생성
• 기존 프로젝트인 경우: task-planning 스킬로 작업 계획 수립