목차

     

     

    요즘 개발자들 사이에서 화제인 Spec Kit과 스펙 주도 개발(SDD)에 대해 이야기해보려고 합니다.

     

    코드부터? 이제는 스펙부터!

    솔직히 말하면, 우리 대부분은 이렇게 개발하죠

    1. 일단 코드 짜고
    2. 되면 문서 쓰고 (안 쓰는 경우도...)
    3. 나중에 "이게 뭐였더라?" 하면서 코드 뒤적거리기

     

    근데 AI 코딩 도구(Copilot, Claude Code 등)가 나오면서 새로운 문제가 생겼어요. 이 친구들은 패턴 완성은 기가 막히게 잘하는데, 내 마음을 읽지 모태 .... ㅜ

     

    애매한 지시를 주면 그럴듯해 보이지만 완전히 딴판인 코드"를 뚝딱 만들어냅니다.(이자식이?)

     

    이때 ! 스펙 주도 개발(SDD)은 이 문제를 정면돌파합니다:

    코드 먼저 쓰지 말고, 실행 가능한 스펙을 먼저 쓰자!

    Spec Kit의 4단계 프로세스

    Spec Kit은 개발 과정을 명확한 4단계로 나눕니다. 각 단계는 검증을 통과해야만 다음으로 넘어갈 수 있어요.

    1️⃣ Specify – "무엇을, 왜"

      • 사용자 여정과 기대 결과를 글로 명확히 작성
      • 기술 스택은 언급하지 않음 (⭐️)
      • 순수하게 "뭘 만들고 싶은지"만 정리
    기술 스택을 언급하지 않는 이유?
    "무엇을/왜"(사용자 요구사항)와 "어떻게"(기술 구현)를 분리해야 AI가 본질을 놓치지 않고, 나중에 기술이 바뀌어도 스펙을 재사용할 수 있어요.
    단, 레거시 통합이나 컴플라이언스 같은 비즈니스 제약조건은 예외적으로 포함 가능합니다.

    2️⃣ Plan – "어떻게"

    • 이제 기술 스택, 아키텍처, 제약사항 등을 추가
    • AI에게 구체적인 기술 계획서를 만들게 함
    • 회사 표준이나 보안 정책도 여기서 반영

    3️⃣ Tasks – "쪼갠 일감"

    • 테스트 가능한 작은 단위로 작업 분해
    • ❌ "인증 구현" (너무 큼)
    • ✅ "이메일 포맷 검증하는 등록 엔드포인트 작성" (딱 좋음)

    4️⃣ Implement – "코드 작성"

    • 태스크 단위로 코드 작성
    • 작은 PR 단위로 리뷰·검증
    • 우발적 대형 PR을 예방!

     

    실제로 어떻게 쓰나?

    초기 설정 (터미널에서)

    # 새 프로젝트 시작
uvx --from git+https://github.com/github/spec-kit.git specify init 

# 기존 프로젝트에 추가
uvx --from git+https://github.com/github/spec-kit.git specify init --here

    에이전트와 대화 (Copilot Chat, Claude Code 등에서)

    /specify   # 스펙 작성
/plan      # 기술 계획 수립
/tasks     # 태스크 분해

    ⚠️ 주의: 초기화(uvx)는 터미널에서, /specify 같은 명령은 AI 채팅 패널에서 입력합니다!

     

    어디에 쓰면 좋을까?

    1. 그린필드 프로젝트 (0→1)

    처음부터 스펙을 잘 짜두면 AI가 의도대로 뚝딱 만들어줍니다.

    2. 기존 시스템 기능 추가 (N→N+1) ⭐️

    가장 강력한 케이스! 기존 패턴과 제약사항을 플랜에 녹여서, 이상한 덧붙임 코드가 아닌 원래 프로젝트 스타일로 자연스럽게 통합되는 코드를 만들 수 있어요.

    3. 레거시 현대화

    오래된 코드도 스펙으로 비즈니스 규칙을 재정의하고, 새로운 아키텍처로 클린하게 리빌드할 수 있습니다.

     

    팀에서 도입하려면?

    최소 셋업

    • /spec/, /plan/, /tasks/ 폴더를 루트에 생성
    • PR 템플릿에 "연결된 스펙/태스크 ID" 필수 입력
    • CI에서 링크 무결성 검증

    역할 분담

    • 스펙 오너: PM/리드 (변경은 리뷰 필수)
    • 플랜 오너: 아키텍트/리드 (기술 제약 관리)
    • 태스크 오너: 개발 리드 (1~3시간 단위로 쪼개기)

    운영 팁

    • 태스크마다 새 대화 열기 (컨텍스트 오염 방지)
    • 각 태스크 완료 시 테스트/데모로 검증 우선
    • 변경 시 스펙 먼저 업데이트 → 플랜/태스크 재생성

     

    🤷 왜 이게 잘 되는 거지?

    AI 모델은:

    • ✅ 패턴 완성은 천재적
    • ❌ 은유, 암시, 숨은 제약은 약함

    SDD는 명확한 의도 → 구체적 설계 → 검증 가능한 과업으로 구조화된 입력을 제공해서 AI의 추측을 줄이고 품질을 높입니다.

    빠른 시작

    # 1. 프로젝트 초기화
uvx --from git+https://github.com/github/spec-kit.git specify init 

# 2. IDE에서 AI 채팅 열고
/specify   # 무엇/왜
/plan      # 스택/아키텍처
/tasks     # 작은 태스크로 쪼개기

# 3. 태스크별로 소규모 PR 생성·검증

    참고 자료

     

    여러분도 AI와 함께 개발하면서 "왜 내가 원한 게 이게 아닌데..."라고 생각한 적 있으시죠? Spec Kit으로 명확한 스펙을 먼저 잡아두면, AI가 훨씬 정확하게 우리 의도를 이해하고 코드를 만들어줍니다.

    다음 프로젝트에서 한번 시도해보시는 건 어떨까요?  ?

     

    + Recent posts

    티스토리툴바