명세 작성 스킬

개요

이 스킬은 사용자의 요구사항을 체계적으로 분석하여 명세서와 사용자 스토리 문서를 작성합니다. 모든 산출물은 양방향 추적성 매트릭스로 관리됩니다.

산출물

이 스킬은 다음 문서들을 생성합니다:

문서	경로	설명
명세서	docs/specs/SPEC-{번호}-{기능명}.md	기능 요구사항 상세
사용자 스토리	docs/user-stories/US-{번호}-{기능명}.md	최종 사용자 관점의 스토리
추적성 매트릭스	docs/traceability-matrix.md	양방향 추적성 관리

실행 절차

1단계: 요구사항 수집 및 분석

사용자로부터 요구사항을 수집합니다:

• 구현하려는 기능의 목적
• 예상 사용자와 사용 시나리오
• 기술적 제약사항
• 우선순위

2단계: 명세서 작성

다음 형식으로 명세서를 작성합니다:

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

## 메타데이터
- **작성일**: YYYY-MM-DD
- **버전**: 1.0
- **상태**: 초안 | 검토중 | 승인됨
- **관련 사용자 스토리**: US-{번호}

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

## 기능 요구사항

### FR-{번호}.1: {세부 요구사항 제목}
- **설명**: {상세 설명}
- **우선순위**: 필수 | 권장 | 선택
- **추적 ID**: SPEC-{번호}-FR-1

### FR-{번호}.2: {세부 요구사항 제목}
...

## 비기능 요구사항

### NFR-{번호}.1: {비기능 요구사항}
- **카테고리**: 성능 | 보안 | 확장성 | 유지보수성
- **설명**: {상세 설명}
- **측정 기준**: {정량적 기준}

## 제약사항
- {기술적/비즈니스 제약사항}

## 용어 정의
| 용어 | 정의 |
|------|------|
| {용어} | {정의} |

3단계: 사용자 스토리 작성

중요: 사용자 스토리의 "사용자"는 항상 최종 사용자입니다.

다음 형식으로 사용자 스토리를 작성합니다:

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

## 메타데이터
- **작성일**: YYYY-MM-DD
- **관련 명세**: SPEC-{번호}
- **우선순위**: 높음 | 중간 | 낮음
- **스토리 포인트**: {예상 복잡도}

## 사용자 스토리

**사용자로서**, {최종 사용자의 역할}
**나는**, {달성하고자 하는 것}을 원한다
**그래서**, {얻고자 하는 가치/이유}

## 인수 조건 (Acceptance Criteria)

### AC-{번호}.1: {인수 조건 제목}
- **Given** (전제조건): {초기 상태/조건}
- **When** (행동): {사용자가 수행하는 행동}
- **Then** (결과): {예상되는 결과}
- **추적 ID**: US-{번호}-AC-1

### AC-{번호}.2: {인수 조건 제목}
...

## 인수 테스트

### AT-{번호}.1: {테스트 제목}
- **관련 인수 조건**: AC-{번호}.1
- **테스트 시나리오**:
  1. {단계 1}
  2. {단계 2}
  3. {단계 3}
- **예상 결과**: {검증할 결과}
- **추적 ID**: US-{번호}-AT-1

### AT-{번호}.2: {테스트 제목}
...

## 화면/인터페이스 스케치 (선택사항)
{필요시 ASCII 다이어그램 또는 설명}

## 의존성
- {다른 스토리나 기술적 의존성}

## 참고사항
- {추가 정보}

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

docs/traceability-matrix.md 파일을 생성하거나 업데이트합니다:

# 양방향 추적성 매트릭스

## 개요
이 문서는 요구사항부터 구현까지의 양방향 추적성을 관리합니다.

## 순방향 추적 (요구사항 → 구현)

| 명세 ID | 사용자 스토리 | 인수 조건 | 인수 테스트 | 구현 상태 |
|---------|--------------|-----------|-------------|-----------|
| SPEC-{번호} | US-{번호} | AC-{번호}.1, AC-{번호}.2 | AT-{번호}.1, AT-{번호}.2 | 대기중 |

## 역방향 추적 (구현 → 요구사항)

| 코드/테스트 파일 | 추적 ID | 관련 인수 테스트 | 관련 명세 |
|-----------------|---------|-----------------|-----------|
| (구현 후 업데이트) | | | |

## 추적 ID 규칙

- 명세: `SPEC-{번호}`
- 기능 요구사항: `SPEC-{번호}-FR-{순번}`
- 사용자 스토리: `US-{번호}`
- 인수 조건: `US-{번호}-AC-{순번}`
- 인수 테스트: `US-{번호}-AT-{순번}`
- 코드 어노테이션: `@trace US-{번호}-AT-{순번}`

코드 어노테이션 규칙

역방향 추적을 위해 코드와 테스트에 다음 어노테이션을 사용합니다:

// @trace US-001-AT-1
// @spec SPEC-001-FR-1
function featureImplementation() {
  // 구현 코드
}

# @trace US-001-AT-1
# @spec SPEC-001-FR-1
def feature_implementation():
    # 구현 코드
    pass

다음 단계

명세 작성이 완료되면:

• 신규 프로젝트: project-bootstrap 스킬을 사용하여 프로젝트 구조와 CI 파이프라인을 생성합니다.
• 기존 프로젝트: task-planning 스킬을 사용하여 작업 계획을 수립합니다.

품질 체크리스트

명세 작성 완료 전 확인사항:

• 모든 요구사항에 고유 ID가 부여되었는가?
• 사용자 스토리의 사용자가 최종 사용자인가?
• 각 인수 조건에 Given-When-Then 형식이 적용되었는가?
• 인수 테스트가 검증 가능한 형태로 작성되었는가?
• 추적성 매트릭스가 업데이트되었는가?