DEVOCEAN

안녕하세요. SK AX 의 송영목 입니다.

SDD(Spec-Driven Development) 를 보면 진실의 원천은 스펙(요구사항) 이 되고 있다고 느낍니다.

앞으로는 스펙 기반으로 작업을 하게 되어 프로젝트 수행 시에 생각하는 구조를 좀 더 바뀌어야 될 것 같습니다.

SDD(Spec-Driven Development) 에서는 "명세가 원본이고, 코드는 표현물이다." 라는 선언합니다.

전통적인 개발에서 명세서는 개발이 시작되면 잊히는 참고 문서에 불과했습니다.

하지만 SDD(Spec-Driven Development)에서 명세(Specification)는 개발 과정 전체를 지배하는 유일한 진실 공급원(Single Source of Truth) 이 됩니다.

이것은 단순히 문서 작업을 늘리는 것이 아니라, 개발의 중심을 '어떻게(how)'에서 '무엇을, 왜(what/why)' 로 옮기는 의도 중심 개발(Intent-Driven Development) 로의 전환을 의미합니다.

명확하게 작성된 명세서는 AI 코딩 에이전트에게 추측이나 환각 현상(hallucination)을 일으킬 틈을 주지 않는 완벽한 '설계도'이자 '가드레일' 역할을 합니다.

또한, 명세서는 한번 만들고 끝나는 박제된 문서가 아니라, 프로젝트의 변화에 따라 함께 진화하는 '살아있는 문서(living document)' 가 됩니다.

기능 수정이 필요할 때 코드를 직접 만지는 대신, 명세서를 업데이트하고 그에 맞춰 코드를 다시 생성함으로써 의도와 구현 사이의 간극이 벌어지는 것을 원천적으로 차단합니다.

스펙 기반 개발(Spec-Driven Development, SDD)의 4단계 프로세스

스펙 기반 개발(Spec-Driven Development, SDD)의 4단계 프로세스는 모호한 자연어 지시를 정밀한 공학적 산출물로 변환하여 AI 코딩의 신뢰성을 높이는 핵심 워크플로입니다.

이 프로세스는 Specify(명세) → Plan(계획) → Tasks(작업) → Implement(구현)의 단계로 구성되며, 각 단계는 이전 단계가 완전히 검증된 후에야 다음으로 넘어가는 '가드레일' 역할을 수행합니다.

1. 명세화 단계 (Specify)

   • 핵심 질문: 무엇을(What), 왜(Why) 만드는가?

   • 주요 활동: 개발자가 높은 수준의 아이디어나 비즈니스 요구사항을 제공하면, AI 에이전트가 이를 구조화된 제품 요구사항 문서(PRD)로 변환합니다.

   • 특징: 이 단계에서는 '어떻게 구현할지'와 같은 기술적 세부 사항(기술 스택, API 구조 등)은 철저히 배제합니다.

   대신 사용자 여정(User Journey), 경험(UX), 성공 지표 및 인수 조건(Acceptance Criteria)을 명확히 정의하는 데 집중합니다.

2. 기술 계획 수립 단계 (Plan)

   • 핵심 질문: 어떻게(How) 구현할 것인가?

   • 주요 활동: 확정된 명세를 바탕으로 구체적인 기술 아키텍처와 구현 정책을 설계합니다.

   • 포함 내용: 사용할 프레임워크와 언어(기술 스택), 데이터 모델 스키마, API 엔드포인트 정의, 보안 및 성능 제약 조건 등을 명시합니다.

   • 원칙 준수: 이 단계에서 수립되는 계획은 프로젝트의 기본 원칙인 '헌법(Constitution)' 파일에 선언된 규칙(예: 테스트 필수, 특정 라이브러리 사용 제한 등)을 반드시 준수해야 합니다.

3. 작업 분해 단계 (Tasks)

   • 주요 활동: 상세 기술 계획을 AI가 실행 가능하고 사람이 검토하기 쉬운 **작은 작업 단위(Chunk)**로 잘게 쪼갭니다.

   • 특징: 각 작업은 독립적으로 구현 및 테스트가 가능해야 합니다.

   예를 들어 단순히 "인증 기능 구축"이라고 정의하는 대신 "이메일 형식 검증 기능이 포함된 사용자 등록 엔드포인트 생성"과 같이 구체적으로 나열합니다.

   이는 AI가 작업의 궤도를 유지하고 스스로 검증할 수 있는 로드맵이 됩니다.

4. 구현 및 검증 단계 (Implement)

   • 주요 활동: 분할된 작업 목록에 따라 AI가 실제로 코드를 생성합니다.

   • 검토 방식: 개발자는 수천 줄의 방대한 코드를 한꺼번에 검토하는 대신, 특정 문제를 해결하기 위해 집중된 변경 사항을 작업 단위별로 리뷰합니다.

   • 인간의 역할: 개발자는 단순히 코드를 복사해 붙여넣는 것이 아니라, AI의 결과물이 명세와 계획에 부합하는지 확인하고 테스트를 실행하는 '조향사(Steerer)' 및 '검증자' 역할을 수행합니다.

   만약 구현 중 오류가 발견되면 코드를 직접 고치기보다 상위의 명세나 계획을 수정하여 일관성을 유지하는 것이 SDD의 원칙입니다.

GitHub Spec Kit의 4단계 워크플로우

이론적인 SDD(Spec-Driven Development)를 실제 프로젝트에서 어떻게 구현할 수 있을까요?

GitHub가 오픈소스로 공개한 Spec Kit은 AI 에이전트와 협업하기 위한 구체적인 4단계 워크플로우를 제공합니다.

이 과정에서 개발자의 역할은 코더가 아닌, AI라는 파일럿을 올바른 방향으로 이끄는 '관제탑' 또는 '조향사' 가 됩니다.

1. /specify (명세화) : 개발자는 '무엇을, 왜 만드는가'에 집중하여 높은 수준의 아이디어를 제시합니다. 기술 스택이나 구현 방식이 아닌, 사용자가 경험할 여정과 핵심 기능에 초점을 맞춥니다. AI는 이 입력을 받아 구조화된 제품 요구사항 명세서(spec.md)를 생성합니다.

2. /plan (계획 수립): 확정된 명세서를 바탕으로 '어떻게 만들 것인가'를 정의합니다. 개발자는 원하는 기술 스택, 아키텍처, 제약 조건 등을 제시하고, AI는 이를 반영하여 상세한 기술 구현 계획서(plan.md)를 만듭니다.

3. /tasks (작업 분해): AI는 수립된 계획을 실행 가능한 최소 단위의 작업들로 분해하여 체크리스트(tasks.md)를 생성합니다. 각 작업은 "이메일 형식 검증 기능이 포함된 회원가입 엔드포인트 생성"처럼 명확하고 독립적으로 테스트할 수 있도록 정의됩니다.

4. /implement (구현): AI 에이전트가 분해된 작업을 순서대로, 또는 병렬로 처리하며 코드를 생성합니다. 개발자는 수천 줄의 코드를 한 번에 검토하는 대신, 각 작업 단위로 생성된 집중된 변경 사항을 검토하고 승인하며 전체 과정을 감독합니다.

   이처럼 SDD는 예측 불가능한 마법을 예측 가능한 공학 의 영역으로 끌어올리는 체계적인 방법론입니다.

SDD vs BDD vs TDD 비교

SDD가 시스템 전체의 '무엇'과 '왜'라는 가장 상위 질문에서 출발한다면, BDD는 사용자의 '행위'에, TDD는 코드 단위의 '정확성'에 집중합니다.

3-File System vs GitHub Spec Kit

프로젝트의 규모, 목적, 개발 인원 구성에 따라 3-File System과 GitHub Spec Kit 중 적합한 방식이 달라집니다.

1. 3-File System이 적합한 경우

   라이언 카슨(Ryan Carson)이 제안한 이 방식은 절차를 최소화하고 속도를 극대화하는 데 초점이 맞춰져 있습니다.

   • 솔로 창업자 및 개인 프로젝트: 엔지니어링 팀 없이 혼자서 빠르게 제품을 만들고 싶을 때 가장 효율적입니다.

   • 속도가 최우선인 초기 프로토타이핑: 복잡한 설계 단계보다 빠르게 동작하는 결과물을 확인해야 하는 경우에 적합합니다.

   • 단순한 서비스 개발: 구조가 복잡하지 않은 간단한 앱이나 웹 서비스를 구축할 때 오버헤드 없이 적용할 수 있습니다.

2. GitHub Spec Kit이 적합한 경우

   GitHub이 공개한 Spec Kit은 공학적 정밀도와 팀 단위의 일관성을 보장하는 데 특화되어 있습니다.

   • 팀 단위 및 복잡한 프로젝트: 여러 이해관계자가 참여하여 인식을 일치시켜야 하거나 요구사항이 복잡한 경우에 필수적입니다.

   • 기존 시스템의 기능 확장 (N-to-N+1): 복잡한 기존 코드베이스에 새 기능을 추가할 때, 기존 시스템과의 상호작용을 명확히 하고 아키텍처 제약을 유지하는 데 매우 강력합니다.

   • 레거시 시스템 현대화: 오래된 시스템을 재구축할 때 기술 부채를 답습하지 않고 핵심 비즈니스 로직만 추출하여 현대적 아키텍처로 재탄생시키고자 할 때 적합합니다.

   • 고품질 및 엔터프라이즈급 소프트웨어: '프로젝트 헌법(Constitution)'을 통해 기술 스택, 테스트 규칙, 보안 가이드라인 등을 강제하여 일관된 품질을 유지해야 하는 경우에 권장됩니다.

3. 비교

아래는 GitHub Spec Kit 으로 로그인 샘플 기능을 만든 과정입니다.

Next.js 프로젝트 생성

npx create-next-app@latest todolist-app --typescript --eslint --tailwind --app --disable-git

Spec Kit 프레임워크 초기화

specify init .

GitHub의 Spec Kit 프레임워크에서 제공하는 초기화 명령어를 실행합니다.

"Spec-Driven Development (SDD)" 방식으로 프로젝트를 시작할 때 사용합니다.

Spec kit 프레임 생성

speckit 필수 프로세스 : 2.1 constitution -> 2.2 specify -> 2.3 plan -> 2.4 tasks -> 2.5 implement

Optional 프로세스 :

/speckit.clarify (요건 명확화, optional) - Ask structured questions to de-risk ambiguous areas before planning (run before /speckit.plan if used)

/speckit.analyze (optional) - Cross-artifact consistency & alignment report (after /speckit.tasks, before /speckit.implement)

/speckit.checklist (optional) - Generate quality checklists to validate requirements completeness, clarity, and consistency (after /speckit.plan)

copilot-instructions.md 생성

copilot-instructions.md를 한국어로 변환

copilot-instructions.md를 한국어로 작성해 줘

한국어 코드 작성 지침

• AI 응답 메시지: 한국어 사용(설명/요약/진행 보고/결과 보고/산출물 등)

• 커밋 메시지: type(scope): 한국어 설명 (예: feat(task): 할일 추가 기능 구현)

• 주석: 한국어로 작성

• 코드 식별자: 영어 사용 (변수/함수/컴포넌트명)

  
  

• constitution

  /speckit.constitution

  코드 품질, 테스트 표준, 사용자 경험 일관성 및 성능 요구사항에 중점을 둔 원칙을 수립하십시오.

  이러한 원칙이 기술적 결정과 구현 선택을 어떻게 안내해야 하는지에 대한 거버넌스를 포함하십시오.

생성된 constitution.md

2. specify (요구사항)

   /speckit.specify

3. 개요 (Overview)

   학습자가 Next.js 16의 Server Actions와 Cookie를 활용한 인증 흐름을 가장 쉽고 명확하게 이해할 수 있도록 최소한의 기능만 구현합니다. 별도의 데이터베이스 연결 없이 하드코딩된 사용자 정보를 사용하여 인증의 핵심 로직에 집중합니다.

4. 사용자 시나리오 (User Scenarios)

   로그인 시도: 사용자는 정해진 아이디(admin)와 비밀번호(1234)를 입력합니다.

   인증 성공: 정보가 일치하면 '로그인 성공' 메시지와 함께 메인 화면으로 이동합니다.

   인증 실패: 정보가 틀리면 화면에 "아이디 또는 비밀번호가 틀렸습니다"라는 경고를 띄웁니다.

   로그아웃: 버튼을 누르면 브라우저의 인증 쿠키를 삭제하고 로그인 페이지로 돌아갑니다.

5. 핵심 요구사항 (Requirements)

   단순함: 복잡한 외부 DB나 인증 라이브러리(Next-Auth 등) 없이 표준 API만 사용합니다.

   보안: 로그인이 완료되면 httpOnly 쿠키를 생성하여 클라이언트 자바스크립트에서 접근하지 못하게 합니다.

   UI/UX: Tailwind CSS 4를 사용하여 한눈에 들어오는 단순한 중앙 정렬 카드 레이아웃을 제공합니다.

   기술 스택: Next.js 16 App Router와 React 19의 최신 폼 처리 방식을 학습합니다.

6. 기술적 상세 (Technical Details)

   컴포넌트 구조:

   login-form.tsx: useActionState 훅을 사용하여 서버 액션의 결과(에러 등)를 처리하는 클라이언트 컴포넌트입니다.

   auth-actions.ts: 사용자의 입력을 검증하고 쿠키를 설정하는 서버 로직 파일입니다.

   인증 방식:

   아이디/비밀번호가 일치하면 session이라는 이름의 쿠키를 생성합니다.

   경로 보호: middleware.ts에서 쿠키 유무를 확인해 로그인이 안 된 사용자를 로그인 페이지로 튕겨냅니다.

7. 테스트 계획 (Testing Plan)

   단위 테스트 (Vitest): 아이디와 비밀번호가 비어있을 때 에러를 반환하는 유효성 검사 로직을 테스트합니다.

   E2E 테스트 (Playwright): admin / 1234 입력 후 메인 페이지 URL로 이동하는지 확인합니다.

copilot-instruction.md 를 참조하여 한국어로 만들어 주세요.

생성된 spec.md 파일

3. clarify (Optional)

   
   

4. plan (기술 스펙 정보 포함)

   /speckit.plan

   • 계정 정보: 별도 DB 없이 admin / 1234로 고정하여 로직의 흐름에 집중

   • 언어: 모든 주석과 설명은 한국어로 작성

   • 스타일:

   Tailwind CSS를 사용하여 코드를 최소화

   https://v0.app/?utm_source=tailwindcss 참고

생성된 plan.md 파일

5. tasks

   /speckit.tasks

tasks.md 파일 생성

tasks.md 파일 내에 수행할 tasks 들이 정의됨.

6. analyze (Optional)

   /speckit.analyze

   
   

7. implement

   /speckit.implement

   
   

Task 성공 시, [x] 체크 표시

Task 요약 내용

Test Coverage 확인

로그인 화면 테스트

참조

https://code.visualstudio.com/docs/copilot/customization/overview

https://github.com/github/awesome-copilot/tree/main

https://github.com/github/spec-kit