iOS Development • January 15, 2026

스펙 주도 개발 알아보기

#SDD#specdrivendevelopment#github#spek-kit#사양주도개발#스펙주도개발

https://github.com/github/spec-kit 리포지토리 분석 먼저.

이 프로젝트는 "코딩 전에 사양(Spec)부터 제대로 만들자"는 철학을 바탕으로, AI와 함께 체계적으로 소프트웨어를 개발할 수 있도록 돕는 툴킷입니다.

1. README 요약 (주요 내용)

핵심 개념: Spec-Driven Development (사양 주도 개발)

  • 기존에는 사양서가 코딩을 위한 임시 보조 수단이었다면, 이 방식에서는 사양서가 실행 가능한(executable) 중심축이 됩니다.

  • "어떻게(How)" 만들지보다 "무엇을(What)" 만들지에 집중하여, AI가 예측 가능한 결과를 내도록 유도합니다.

사용 방법 (워크플로우) 이 툴킷은 Specify CLI와 AI 에이전트(Claude, GitHub Copilot 등)를 연동하여 다음 5단계로 진행됩니다.

  1. 원칙 수립 (/speckit.constitution): 프로젝트의 헌법(Constitution)을 만듭니다. (예: 코드 품질 기준, 테스트 표준, UX 원칙 등)

  2. 사양 작성 (/speckit.specify): 구현 기술보다는 기능적 요구사항을 상세히 기술합니다.

  3. 기술 계획 (/speckit.plan): 사용할 기술 스택과 아키텍처를 결정합니다. (예: React + Python 사용, DB 구조 등)

  4. 작업 분해 (/speckit.tasks): 계획을 실행 가능한 단위 작업 리스트로 변환합니다.

  5. 구현 실행 (/speckit.implement): 정의된 작업들을 실제 코드로 구현합니다.

지원하는 AI 에이전트

  • Claude Code, GitHub Copilot, Gemini CLI, Cursor, Windsurf 등 다양한 AI 코딩 도구와 연동됩니다.

  • 터미널에서 specify init 명령어로 프로젝트를 시작할 때 사용할 AI를 선택할 수 있습니다.

2. 리포지토리 파일 및 폴더 구조 설명

깃허브에 올라와 있는 주요 디렉토리와 파일들의 역할은 다음과 같습니다.

  • src/specify_cli/:

    • 이 툴킷의 핵심인 specify 커맨드라인 도구(CLI)의 소스 코드가 들어있습니다. 파이썬으로 작성되었습니다.

  • templates/:

    • AI가 문서를 작성할 때 사용하는 마크다운 템플릿들이 모여 있습니다.

    • spec-template.md (사양서 양식), plan-template.md (구현 계획 양식), tasks-template.md (작업 목록 양식) 등이 포함되어 있어, AI가 이 형식을 따라 체계적인 문서를 생성하게 합니다.

  • scripts/:

    • 프로젝트 초기화나 특정 작업 수행을 돕는 쉘 스크립트 모음입니다. 개발 환경 설정이나 자동화 작업에 사용됩니다.

  • memory/:

    • AI가 프로젝트의 문맥(Context)을 기억하기 위한 설정 파일들이나 예시가 들어있는 폴더로 보입니다. (예: constitution.md 같은 프로젝트 원칙 파일)

  • docs/:

    • 사용자 가이드, 업그레이드 가이드 등 상세 문서가 저장된 곳입니다.

  • media/:

    • README 등에 사용되는 이미지나 로고 파일들이 저장되어 있습니다.

  • 주요 설정 파일들:

    • AGENTS.md: 지원되는 AI 에이전트들의 목록과 설정법을 안내합니다.

    • spec-driven.md: 사양 주도 개발(SDD) 방법론에 대한 상세한 철학을 설명하는 문서입니다.

    • pyproject.toml: 파이썬 프로젝트 의존성 및 빌드 설정 파일입니다.

요약하자면: 이 저장소는 개발자가 AI에게 "그냥 코드 짜줘"라고 하는 대신, "원칙 → 사양 → 계획 → 구현"의 단계를 거쳐 더 정교한 소프트웨어를 만들 수 있도록 돕는 가이드라인(템플릿)과 도구(CLI)를 제공합니다.

처음부터 하는거라면 쉬울텐데, 나는 온갖 개발중인 프로젝트들이 산재해있다.

이럴 때도 SDD로 개발할 수 있을까.

고민? 사치다.

AI한테 바로 물어봤다.

기존 프로젝트(Brownfield)에 Spec-Driven Development(SDD)를 도입하는 것은 아주 좋은 전략입니다. 한 번에 모든 것을 바꾸려 하기보다, 새로운 기능 하나 또는 작은 리팩토링부터 시작하는 것이 좋습니다.

다음은 기존 프로젝트에 SDD를 적용하기 위한 준비 과정과 AI에게 설명하는 방법입니다.

1. 물리적 준비: 필수 파일 및 폴더 세팅

가장 먼저 spec-kit이 작동할 수 있는 환경을 프로젝트 루트에 만들어야 합니다. 수동으로 만들 수도 있지만, CLI를 사용하는 것이 가장 빠릅니다.

  1. 프로젝트 루트에서 초기화: 터미널에서 다음 명령어를 실행하여 현재 폴더(.)에 spec-kit 구조를 생성합니다.

    Bash

    specify init . --ai claude  # (사용하는 AI 모델에 따라 claude, copilot 등으로 변경)

    • 이 명령을 실행하면 .specify/ 폴더가 생성됩니다. 기존 코드는 건드리지 않으니 안심하세요.

  2. 핵심 파일 확인 (.specify/memory/constitution.md): 기존 프로젝트에서 가장 중요한 파일입니다. 이 파일은 "우리 프로젝트의 법"입니다. AI가 코드를 짤 때 기존 스타일을 따르게 하려면 이 파일을 잘 작성해야 합니다.

2. AI에게 설명하는 단계 (워크플로우)

이제 AI(Claude, Cursor 등)에게 말을 걸어 작업을 시작합니다. 기존 프로젝트이므로 "분석 → 원칙 수립 → 사양 정의 → 구현" 순서로 진행합니다.

1단계: 기존 코드 스타일 학습시키기 (Constitution 작성)

AI가 당신의 코딩 스타일을 모르고 제멋대로 짜지 않게 하려면, 먼저 기존 코드를 분석시켜서 constitution.md를 채워야 합니다.

  • AI 프롬프트 예시:

    Plaintext

    /speckit.constitution
현재 프로젝트의 기존 소스 코드들을 분석해서, 이 프로젝트가 따르고 있는 코딩 컨벤션, 아키텍처 패턴, 주요 라이브러리 사용법을 파악해줘.
그리고 그것을 바탕으로 우리가 앞으로 지켜야 할 '개발 원칙(Constitution)'을 작성해줘.
특히 폴더 구조 규칙과 네이밍 컨벤션을 정확히 명시해 줘.

  • 효과: AI가 .specify/memory/constitution.md 파일을 업데이트합니다. 이제부터 AI는 이 규칙을 참고하여 코드를 생성합니다.

2단계: 새 기능 정의하기 (Specify)

이제 추가하려는 기능을 정의합니다. 이때는 코드 이야기보다 기능적 요구사항에 집중합니다.

  • AI 프롬프트 예시:

    Plaintext

    /speckit.specify
기존 회원가입 로직에 '이메일 인증' 기능을 추가하고 싶어.
사용자가 가입 버튼을 누르면 인증 메일이 발송되어야 하고, 링크를 클릭하면 인증 상태가 true로 변해야 해.
기존 DB 테이블인 'Users'에 컬럼을 추가해야 할 수도 있어.

  • 결과: .specify/specs/ 폴더 아래에 새 기능에 대한 사양서(Markdown)가 생성됩니다.

3단계: 기술적 구현 계획 (Plan - 가장 중요!)

기존 프로젝트에서는 이 단계가 핵심입니다. AI가 기존 코드와 충돌하지 않게 계획을 짜도록 유도해야 합니다.

  • AI 프롬프트 예시:

    Plaintext

    /speckit.plan
방금 만든 사양(Spec)을 바탕으로 구현 계획을 세워줘.
단, 우리 프로젝트는 이미 'Controller-Service-Repository' 패턴을 쓰고 있으니 이 구조를 유지해야 해.
기존의 `AuthService.js` 파일을 수정하고, `EmailSender.js` 유틸리티를 새로 만드는 방향으로 계획해 줘.
기존 코드를 깨트리지 않는 범위에서 작성해.

  • 결과: AI가 기존 파일 수정 내역과 신규 파일 생성 내역이 담긴 상세 구현 계획을 작성합니다.

4단계: 구현 (Implement)

계획이 마음에 들면 구현을 지시합니다.

  • AI 프롬프트 예시:

    Plaintext

    /speckit.implement
계획된 대로 코드를 작성해 줘.

3. 요약: 기존 프로젝트 적용 팁

  1. specify init . 명령어로 .specify 폴더를 생성하는 것이 시작입니다.

  2. Constitution(헌법) 파일에 기존 프로젝트의 컨벤션(규칙)을 AI에게 분석시켜 채워 넣으세요. (이게 없으면 AI가 이질적인 코드를 만들어냅니다.)

  3. 명령어(/speckit...)를 사용할 때, 항상 "기존 코드 구조를 유지하라"는 제약 조건을 덧붙이세요.

오.. 굉장히 그럴싸해보였다.

이대로 하면 정말 뭐든지 99프로 vibe coding할 수 잇을 것 만 같다.

근데, 정말 좋은거 맞아?

진짜 엔지니어링 도구로 쓰기 위한 필수적인 체계입니다.

3가지 핵심 포인트로 정리해 드릴게요.

1. "기억 상실"을 막는 강력한 안전장치

지금까지의 AI 코딩(일명 'Vibe Coding')은 채팅창에서 이루어졌습니다. 하지만 채팅은 휘발됩니다. 문맥이 길어지면 AI는 앞의 내용을 까먹거나, 프로젝트의 전체적인 규칙을 무시하고 제멋대로 코드를 짜기 시작하죠.

  • SDD의 장점: constitution.md(헌법)와 spec.md(사양서)가 파일로 저장됩니다.

  • 왜 좋은가: AI는 채팅 기억에 의존하는 게 아니라, 항상 이 파일을 참조합니다. 오늘 작업을 멈추고 일주일 뒤에 다시 와도, AI는 프로젝트의 규칙과 문맥을 완벽하게 기억하고 일을 이어갈 수 있습니다.

2. "설계"와 "구현"의 분리 (이게 진짜 개발)

개발에서 가장 큰 비용은 '잘못된 코드를 수정하는 것'입니다. AI에게 대뜸 "코드 짜줘"라고 하면, 엉뚱한 방향으로 수백 줄을 짜놓고 나중에 고치느라 시간을 다 씁니다.

  • SDD의 장점: 코드를 짜기 전에 Plan(계획) 단계를 강제합니다.

  • 왜 좋은가: "이렇게 짤 거야"라고 계획을 먼저 보여주기 때문에, 사용자가 코딩 전에 논리적 오류를 잡아낼 수 있습니다. 건축으로 치면 벽돌을 쌓기 전에 설계도를 검토하는 과정이 생긴 셈이라 실패 확률이 확 줄어듭니다.

3. '1인 개발자'에게 최고의 사수

혼자 개발하다 보면 컨벤션(규칙)이 무너지고, 코드가 스파게티가 되기 쉽습니다.

  • SDD의 장점: Spec Kit은 AI가 PM(기획자) 역할과 Tech Lead(기술 리더) 역할을 수행하게 만듭니다.

  • 왜 좋은가: "규칙에 맞게 짰어?", "빠진 요구사항 없어?"라고 AI가 문서(Checklist)를 통해 스스로 검증합니다. 혼자 일하지만 마치 체계적인 팀에서 일하는 듯한 품질 관리가 가능해집니다.

⚠️ 단점과 주의할 점 (Overhead)

물론 만능은 아닙니다. "배보다 배꼽이 더 클 때"가 있습니다.

  • 너무 무겁습니다: 단순히 "버튼 색깔 바꿔줘", "버그 하나 고쳐줘" 같은 작은 작업에 Spec → Plan → Task 단계를 거치는 건 시간 낭비입니다.

  • 문서 관리: 코드가 바뀌면 사양서(Spec)도 업데이트해야 하는데, 이게 귀찮아서 문서와 코드가 따로 놀게 될 위험(Sync가 안 맞는 문제)은 여전히 존재합니다.

🧩 결론: 이런 경우에 추천합니다.

만약 간단한 스크립트나 일회성 코드를 짠다면 그냥 지금처럼 채팅으로 하셔도 충분합니다.

하지만 "한 달 이상 유지보수할 내 서비스"를 만들거나, 복잡도가 있는 앱/웹 프로젝트를 하신다면, Spec Kit 도입은 초반에 귀찮더라도 나중에 10배의 시간을 아껴줄 투자가 될 것입니다.

언제나 이론은 달콤하다.

일단 찍먹하고 있으니 좀 더 만들어보자. AI들을 빡세게 굴려보자 한 번.

Discussion

Loading comments...