AgentSkillsCN

spec-driven-development

为功能实现撰写技术规格与实施方案文档，助力以规格驱动的开发流程。

SKILL.md
--- frontmatter
name: spec-driven-development
description: 기능 구현을 위한 테크스펙과 구현 계획 문서를 작성합니다. 스펙 주도 개발 워크플로우를 지원합니다.

스펙 주도 개발 (Spec Driven Development)

개요

이 skill은 기능 구현 전에 테크스펙과 구현 계획 문서를 체계적으로 작성하도록 도와줍니다.

핵심 원칙: 테크스펙이 가장 중요하다

"코드는 테크스펙의 구현일 뿐이다. 테크스펙 없이 코드를 작성하지 마라."

왜 테크스펙이 중요한가?

  1. •명확한 방향 설정: 구현 전에 무엇을, 왜, 어떻게 만들지 명확히 정의
  2. •설계 오류 조기 발견: 코드 작성 전에 설계 문제를 발견하고 수정
  3. •커뮤니케이션 도구: 팀원, 미래의 자신과의 명확한 의사소통
  4. •의사결정 기록: 기술적 결정의 이유와 트레이드오프 문서화
  5. •구현 품질 향상: 충분한 사전 검토로 더 나은 코드 품질 확보

테크스펙 작성 원칙

  • •최대한 자세하게: 모호함 없이 구체적으로 작성
  • •모든 엣지 케이스 고려: 예외 상황과 경계 조건 명시
  • •코드 수준의 상세함: 주요 타입, 함수 시그니처, 데이터 구조 포함
  • •Why를 명확히: 단순히 What이 아닌, 왜 그렇게 결정했는지 기록
  • •검증 가능한 요구사항: 테스트로 검증할 수 있는 형태로 작성

테크스펙 완성 기준

테크스펙은 다음 질문에 모두 답할 수 있어야 완성된 것이다:

  • • 이 기능이 해결하는 문제가 명확한가?
  • • 모든 기능적/비기능적 요구사항이 정의되었는가?
  • • 도메인 모델과 타입이 구체적으로 설계되었는가?
  • • API 인터페이스가 명확하게 정의되었는가?
  • • 데이터 모델과 스키마가 설계되었는가?
  • • 기술 선택의 이유가 문서화되었는가?
  • • 위험 요소와 완화 방안이 식별되었는가?
  • • 테스트 전략이 수립되었는가?

워크플로우

  1. •테크스펙 작성 (가장 중요): 기능의 요구사항, 설계, 기술적 결정사항을 최대한 자세하게 문서화
  2. •구현 계획 작성: 테크스펙 기반으로 단계별 구현 계획과 체크리스트 생성

파일 구조

code
docs/spec/
├── 001-기능명/
│   ├── TECH-SPEC.md           # 테크스펙
│   └── PLAN.md                # 구현 계획
├── 002-기능명/
│   ├── TECH-SPEC.md
│   └── PLAN.md
└── ...

사용법

1. 새 기능 테크스펙 작성

사용자가 기능에 대해 설명하면:

  1. •docs/spec/ 디렉토리에서 기존 폴더 번호 확인
  2. •다음 번호로 docs/spec/NNN-기능명/ 디렉토리 생성
  3. •TECH-SPEC.template.md 템플릿을 기반으로 TECH-SPEC.md 작성

2. 구현 계획 작성

테크스펙이 완성되면:

  1. •사용자에게 PLAN 문서 작성 여부 확인 (필수)
    • •"테크스펙 작성이 완료되었습니다. 구현 계획(PLAN) 문서를 작성할까요?"
    • •사용자가 명시적으로 허락할 때까지 PLAN 작성을 진행하지 않음
  2. •사용자 승인 후, 동일 디렉토리에 PLAN.md 파일 생성
  3. •PLAN.template.md 템플릿을 기반으로 문서 작성
  4. •각 단계별 체크리스트 포함

템플릿 파일

진행 방법

테크스펙 작성 시

  1. •사용자로부터 기능 요구사항 청취
  2. •docs/spec/ 디렉토리의 기존 파일 확인하여 다음 번호 결정
  3. •테크스펙 템플릿을 기반으로 문서 작성
  4. •사용자와 함께 요구사항 및 설계 검토

구현 계획 작성 시

중요: 테크스펙 완성 후 반드시 사용자에게 PLAN 작성 허락을 받아야 합니다. 사용자가 명시적으로 승인하기 전까지 PLAN 문서 작성을 시작하지 마세요.

  1. •테크스펙 완성 후 사용자에게 PLAN 작성 여부 질문
  2. •사용자 승인 후에만 해당 테크스펙 문서 읽기
  3. •테크스펙 기반으로 구현 단계 도출
  4. •각 단계별 체크리스트 작성
  5. •의존성 및 선행 조건 명시

구현 진행 시

  1. •구현 계획 문서의 체크리스트 확인
  2. •각 작업 완료 시 체크 표시 (- [x])
  3. •단계 완료 시 상태 테이블 업데이트
  4. •예상치 못한 변경사항은 계획 문서에 반영

디렉토리 번호 규칙

bash
# 기존 디렉토리 확인
ls -d docs/spec/[0-9]*/ 2>/dev/null | sort -r | head -1

# 다음 번호 결정
# 기존 디렉토리가 없으면: 001
# 기존 최신이 005면: 006

디렉토리명 규칙

  • •번호: 3자리 (001, 002, ...)
  • •기능명: 영문 소문자 + 하이픈 (kebab-case)
  • •예시:
    • •docs/spec/001-user-authentication/TECH-SPEC.md
    • •docs/spec/001-user-authentication/PLAN.md
    • •docs/spec/002-order-execution/TECH-SPEC.md
    • •docs/spec/002-order-execution/PLAN.md

주의사항

  1. •테크스펙 먼저: 구현 계획은 반드시 테크스펙 완성 후 작성
  2. •사용자 승인 필수: PLAN 문서는 사용자가 명시적으로 허락할 때만 작성 (자동으로 진행하지 않음)
  3. •점진적 상세화: 처음부터 완벽할 필요 없음, 점진적으로 보완
  4. •변경 추적: 중요한 변경사항은 문서에 기록
  5. •체크리스트 활용: 구현 진행 상황을 체크리스트로 추적
  6. •프로젝트 원칙 준수: CLAUDE.md의 함수형 DDD 원칙 따르기