스펙 중심 개발(SDD) 동향 및 전략

배경

2025년 AI 코딩 에이전트 시대, *Vibe Coding*(감각적 코딩)에서 *Spec-Driven Development*(명세 중심 개발)로 패러다임이 전환 중이다.

“Vibe Coding is dead. Long live Spec-Driven Development.”

직접 경험한 sks-gateway 프로젝트의 리팩토링 실패와 v2 스펙 파이프라인 구축 과정을 바탕으로, SDD의 2025년 동향과 전략을 정리한다.

SDD란 무엇인가?

정의

Spec-Driven Development(SDD): 코드 작성 전 형식화된 명세(specification)를 먼저 작성하고, 이를 AI 에이전트가 코드로 변환하는 개발 방법론.

핵심 원칙

명세가 진실의 원천(Source of Truth)
인간은 “무엇을(What)”, AI는 “어떻게(How)”
재현 가능성: 같은 명세 → 같은 코드

SDD의 3가지 수준 (Martin Fowler)

수준	명칭	설명
Level 1	Spec-first	명세 작성 후 사용, 완료 후 폐기
Level 2	Spec-anchored	명세를 유지하며 지속 업데이트
Level 3	Spec-as-source	명세만 편집, 코드는 자동 생성

2025년 SDD 동향

주요 도구들

GitHub Spec Kit (2025-11)

오픈소스 툴킷
4단계 워크플로우: Specify → Plan → Tasks → Implement
Claude Code, GitHub Copilot, Gemini CLI 통합
명령어: /specify, /plan, /tasks

uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT>

Kiro (Amazon Q)

가장 단순: Requirements → Design → Tasks
마크다운 기반 3단계 워크플로우
문제점: 소규모 버그 수정도 과도한 오버헤드

Tessl Framework

유일하게 Spec-anchored 지향
@generate, @test 태그로 코드 자동 생성
비공개 베타 단계

”Living Spec” 개념 (Arcturus Labs)

정적 문서가 아니라 코드와 함께 진화하는 명세. 코드 변경 시 → 명세도 함께 업데이트 → PR에 포함.

핵심 통찰:

자연어 명세는 본질적으로 모호함
AI는 인간처럼 맥락을 축적하지 못함
해결책: 계층적 명세 구조 + 대화를 통한 명확화

SDD의 한계

상황	SDD 적합성
기업 프로젝트, 명확한 요구사항	매우 적합
탐색적 작업, 프로토타이핑	부적합 (Vibe Coding 권장)
UI 중심 작업	제한적 (비시각적 명세의 한계)
소규모 버그 수정	오버킬

나의 SDD 경험: sks-gateway 프로젝트

리팩토링 실패 사례 (2025-11-24)

feature/refactor-phase2a-modules 브랜치에서 대규모 리팩토링 시도:

gq_gateway.c 10,679줄 → 8개 모듈 동시 분리
결과: 빌드 실패

실패 원인

빌드 환경 없이 대규모 리팩토링
한꺼번에 너무 많은 파일 분리
원본 코드 참조 없이 분리
의존성 관계 무시

핵심 교훈

“한 번에 하나의 함수만 이동하고, 즉시 빌드 테스트. 실패하면 즉시 롤백. 커밋은 항상 빌드 가능해야 함.”

v2 스펙 파이프라인 (성공 사례)

연동규격서 (org-mode)           [원본 - 사람이 읽는 문서]
     │
     ▼ Phase 0 (수동 추출) ✅
spec/extracted/*.json           [기계 처리 가능 - SSOT]
     │
     ▼ Phase 1-2 (YAML 정형화) ✅
spec/protocol_fields.yaml       [정규화된 스키마]
spec/protocol_state_machines.yaml
     │
     ▼ Phase 5 (코드 생성)
scripts/generate_protocol.py → src/generated/protocol.zig

핵심 원칙

“같은 연동규격서 → 같은 YAML → 같은 코드”

SSOT (Single Source of Truth): =extracted/*.json=이 원본
순차 진행: Phase 0 → 1 → 2 → … (동시 진행 금지)
검증 필수: 각 Phase 완료 시 리뷰어 검증
재현 가능: SOURCE_DATE_EPOCH 지원

에이전트 친화적 아키텍처 원칙

원칙	설명
명료한 경계	파일당 500줄 이하, 모듈 간 명시적 인터페이스
명시적 상태	전역 변수 최소화, Context 구조체 사용
불변 우선	상태 직접 수정 X, 새 상태 생성 후 교체
단방향 흐름	Event → Handler → State Change → Side Effect
파일 = 이슈	1개 파일 = 1개 bd 이슈 = 에이전트 작업 단위

SDD 전략: 내가 배운 것

전략 1: 계층적 명세 구조

High-level (추상)
    │
    └── 비즈니스 요구사항
         │
Mid-level (설계)
    │
    └── 상태머신, 타입 정의
         │
Low-level (구현)
    │
    └── 실제 코드 (가장 상세한 명세)

전략 2: bd 기반 작업 단위

# 파일 단위 이슈 생성
bd create "state/device.zig 구현" -t task
bd create "event/zigbee.zig 구현" -t task
 
# 작업 진행
bd update sks-xxx --status in_progress
# ... 구현 ...
zig build && zig build test
git commit -m "feat(device): implement DeviceStore"
bd close sks-xxx --reason "구현 완료"

전략 3: 점진적 접근 (절대 규칙)

잘못된 방법	올바른 방법
8개 모듈 동시 분리	1개 함수씩 이동
빌드 없이 대량 수정	매 수정 후 빌드
기능 테스트 없음	분리 후 동작 확인

전략 4: Living Spec 적용

1. 명세 변경 필요 발견
2. 명세 파일 수정
3. 코드 수정
4. 동일 PR에 명세 + 코드 변경 포함
5. 명세와 코드가 항상 동기화

결론: 스펙 중심의 AI 협업

SDD가 필요한 이유

AI 에이전트는 모호함을 해석하지 못한다. 명확한 명세 없이는 “의도와 다른 코드”가 생성된다.

내 워크플로우 (2025년 기준)

1. 요구사항 정의 (자연어)
2. 형식화된 명세 작성 (YAML/JSON/타입)
3. AI 에이전트에게 명세 제공
4. 생성된 코드 검증
5. 명세-코드 동기화 유지

핵심 인사이트

“스펙은 코드의 설계도가 아니라, 코드의 DNA다.”

에이전트 시대에 스펙은 선택이 아니라 필수. 명세가 없으면 AI는 추측하고, 추측은 버그를 낳는다.

PM 조언: sks-gateway SDD 전환 로드맵

현황 진단

sks-gateway 프로젝트는 이미 SDD Level 2 (Spec-anchored) 방향으로 가고 있습니다:

요소	현재 상태	SDD 성숙도
연동규격서 → YAML 추출	✅ Phase 0-2 완료	Level 2 진입
코드 생성 파이프라인	⚠️ Phase 5 대기	Level 2 목표
Living Spec 동기화	❌ 수동	Level 2 미달
에이전트 작업 분배	✅ bd + 파일 단위	양호

핵심 권고사항

1. Phase 3-5 완료 우선순위 높여라

명세만 있고 코드 생성이 없으면 SDD가 아니라 *문서화*에 불과하다.

현재: 연동규격서 → YAML (완료) → ??? → 코드 (수동)
목표: 연동규격서 → YAML → generate_protocol.py → protocol.zig (자동)

2. Living Spec 프로세스 도입

연동규격서가 변경되면:

1. extracted/*.json 업데이트
2. YAML 스키마 수정
3. 코드 재생성
4. 동일 PR에 1-3 모두 포함

3. 검증 자동화 구축

현재: GPT 팀 수동 검증 → Claude 리뷰
권장: CI/CD 파이프라인에 스펙-코드 일관성 검사 추가
 
예시:
- YAML 스키마 파싱 테스트
- 생성된 코드 컴파일 테스트
- 필드 수 일치 검증

4. 에이전트 역할 명확화

에이전트	담당 영역	bd 태그
GPT 팀	연동규격서 분석, 테이블 추출	`gpt_task`
Claude (architect)	구조 설계, 검증, 의존성 관리	`claude-task`
Claude (refactor)	코드 생성기, 모듈 분리	`refactor`

5. 리팩토링과 SDD 분리

경고: C 레거시 리팩토링과 v2 SDD 파이프라인을 동시에 진행하지 마라.

권장 순서:

v2 SDD 파이프라인 완성 (Phase 3-5)
새 코드 생성 검증
레거시 C 코드 점진적 교체

90일 로드맵

기간	목표	핵심 산출물
Week 1-4	Phase 3-5 완료	`generate_protocol.py --validate`
Week 5-8	CI/CD 검증 자동화	GitHub Actions 파이프라인
Week 9-12	Living Spec 프로세스 정착	스펙 변경 PR 템플릿

성공 지표

재현성: 다른 에이전트가 같은 스펙으로 같은 코드 생성
동기화: 연동규격서 ↔ YAML ↔ 코드 간 불일치 0건
자동화: 수동 개입 없이 스펙 → 코드 생성 가능

리스크 및 완화

리스크	완화 전략
연동규격서 빈번한 변경	버전 관리, 차이점 추적 자동화
에이전트 간 해석 차이	타입 시스템 강화, 검증 테스트
레거시 코드 의존성	Zig 래퍼로 점진적 교체

Sources

메타

작성: 2025-11-26 (Claude Opus 4.5 + junghanacs)
bd 이슈: org-uhk
상태: Living Document

스펙 주도 개발 (Spec-Driven Development) 번역

원문 출처: https://github.com/github/spec-kit/blob/main/spec-driven.md

권력의 역전 (The Power Inversion)

수십 년 동안 코드가 왕이었습니다. 스펙(Specification)은 코드를 위해 봉사했습니다. 스펙은 우리가 구축한 비계(scaffolding)였고, “진짜 작업”인 코딩이 시작되면 버려지는 것이었습니다. 우리는 개발을 안내하기 위해 PRD(Product Requirements Document)를 작성했고, 구현을 알리기 위해 설계 문서를 만들었으며, 아키텍처를 시각화하기 위해 다이어그램을 그렸습니다. 하지만 이것들은 항상 코드 자체에 종속되어 있었습니다. 코드가 진실이었습니다. 나머지는 기껏해야 선한 의도에 불과했습니다. 코드가 진실의 원천(source of truth)이었고, 코드가 앞으로 나아가는 동안 스펙은 거의 보조를 맞추지 못했습니다. 자산(asset)과 구현(implementation)이 하나이기 때문에, 코드에서 빌드를 시도하지 않고 병렬 구현을 갖는 것은 쉽지 않습니다.

스펙 주도 개발(Spec-Driven Development, SDD)은 이러한 권력 구조를 역전시킵니다. 스펙은 코드를 위해 봉사하지 않고, 코드가 스펙을 위해 봉사합니다. PRD는 구현을 위한 가이드가 아니라 구현을 생성하는 원천입니다. 기술 계획(Technical Plan)은 코딩을 알리는 문서가 아니라 코드를 생성하는 정밀한 정의입니다. 이것은 소프트웨어를 구축하는 방식의 점진적 개선이 아닙니다. 개발을 주도하는 것에 대한 근본적인 재고입니다.

스펙과 구현 사이의 간극은 소프트웨어 개발이 시작된 이래 계속 문제가 되어왔습니다. 우리는 더 나은 문서화, 더 상세한 요구사항, 더 엄격한 프로세스로 이를 메우려고 노력해왔습니다. 이러한 접근법들은 간극을 불가피한 것으로 받아들이기 때문에 실패합니다. 간극을 좁히려고 시도하지만 결코 제거하지는 못합니다. SDD는 스펙과 스펙에서 태어난 구체적인 구현 계획을 실행 가능하게 만듦으로써 간극을 제거합니다. 스펙과 구현 계획이 코드를 생성할 때, 간극은 없고 오직 변환(transformation)만 있습니다.

이러한 변환은 이제 가능합니다. AI가 복잡한 스펙을 이해하고 구현할 수 있으며, 상세한 구현 계획을 만들 수 있기 때문입니다. 하지만 구조 없는 원시 AI 생성은 혼란을 만들어냅니다. SDD는 작동하는 시스템을 생성할 수 있을 만큼 정밀하고, 완전하며, 명확한 스펙과 후속 구현 계획을 통해 그 구조를 제공합니다. 스펙이 주요 산출물(primary artifact)이 됩니다. 코드는 특정 언어와 프레임워크에서 (구현 계획으로부터의 구현으로서) 표현이 됩니다.

이 새로운 세계에서 소프트웨어 유지보수는 스펙을 진화시키는 것을 의미합니다. 개발팀의 의도(intent)는 자연어(“의도 주도 개발(intent-driven development)”), 디자인 자산(design assets), 핵심 원칙 및 기타 가이드라인으로 표현됩니다. 개발의 *공통어(lingua franca)*는 더 높은 수준으로 이동하며, 코드는 라스트마일 접근법입니다.

디버깅은 잘못된 코드를 생성하는 스펙과 구현 계획을 수정하는 것을 의미합니다. 리팩토링은 명확성을 위한 재구조화를 의미합니다. 전체 개발 워크플로우는 스펙을 중심 진실의 원천으로 하고, 구현 계획과 코드를 지속적으로 재생성되는 출력물로 하여 재조직됩니다. 우리가 창의적인 존재이기 때문에 새로운 기능으로 앱을 업데이트하거나 새로운 병렬 구현을 만드는 것은, 스펙을 재검토하고 새로운 구현 계획을 만드는 것을 의미합니다. 따라서 이 프로세스는 0 -> 1, (1’, ..), 2, 3, N입니다.

개발팀은 창의성, 실험, 비판적 사고에 집중합니다.

실무에서의 SDD 워크플로우 (The SDD Workflow in Practice)

워크플로우는 아이디어로 시작합니다---종종 모호하고 불완전합니다. AI와의 반복적인 대화를 통해 이 아이디어는 포괄적인 PRD가 됩니다. AI는 명확화 질문을 하고, 엣지 케이스를 식별하며, 정밀한 수락 기준(acceptance criteria)을 정의하는 데 도움을 줍니다. 전통적인 개발에서 며칠이 걸리는 회의와 문서화 작업이 몇 시간의 집중된 스펙 작업으로 이루어집니다. 이는 전통적인 SDLC(Software Development Life Cycle)를 변화시킵니다---요구사항과 설계가 개별 단계가 아닌 지속적인 활동이 됩니다. 이는 *팀 프로세스*를 지원하며, 여기서 팀이 검토한 스펙이 표현되고 버전 관리되며, 브랜치에서 생성되고, 병합됩니다.

제품 관리자가 수락 기준을 업데이트하면, 구현 계획은 영향받은 기술적 결정을 자동으로 플래그합니다. 아키텍트가 더 나은 패턴을 발견하면, PRD는 새로운 가능성을 반영하도록 업데이트됩니다.

이 스펙 프로세스 전반에 걸쳐, 연구 에이전트(research agents)가 중요한 컨텍스트를 수집합니다. 라이브러리 호환성, 성능 벤치마크, 보안 영향을 조사합니다. 조직의 제약사항이 발견되고 자동으로 적용됩니다---회사의 데이터베이스 표준, 인증 요구사항, 배포 정책이 모든 스펙에 원활하게 통합됩니다.

PRD로부터, AI는 요구사항을 기술적 결정으로 매핑하는 구현 계획을 생성합니다. 모든 기술 선택에는 문서화된 근거가 있습니다. 모든 아키텍처 결정은 특정 요구사항으로 추적됩니다. 이 프로세스 전반에 걸쳐 일관성 검증(consistency validation)이 지속적으로 품질을 향상시킵니다. AI는 스펙의 모호성, 모순, 격차를 분석합니다---일회성 게이트가 아니라 지속적인 개선으로서 말입니다.

코드 생성은 스펙과 구현 계획이 충분히 안정되는 즉시 시작되지만, “완전”할 필요는 없습니다. 초기 생성은 탐색적일 수 있습니다---스펙이 실제로 타당한지 테스트합니다. 도메인 개념은 데이터 모델이 됩니다. 사용자 스토리는 API 엔드포인트가 됩니다. 수락 시나리오는 테스트가 됩니다. 이는 스펙을 통해 개발과 테스트를 병합합니다---테스트 시나리오는 코드 이후에 작성되는 것이 아니라, 구현과 테스트 모두를 생성하는 스펙의 일부입니다.

피드백 루프는 초기 개발을 넘어 확장됩니다. 프로덕션 메트릭과 인시던트는 단순히 핫픽스를 유발하지 않고, 다음 재생성을 위해 스펙을 업데이트합니다. 성능 병목은 새로운 비기능 요구사항(non-functional requirements)이 됩니다. 보안 취약점은 모든 미래 생성에 영향을 미치는 제약사항이 됩니다. 스펙, 구현, 운영 현실 사이의 이 반복적 춤은 진정한 이해가 나오는 곳이며, 전통적인 SDLC가 지속적 진화로 변화하는 곳입니다.

왜 지금 SDD가 중요한가 (Why SDD Matters Now)

세 가지 트렌드가 SDD를 가능할 뿐만 아니라 필요하게 만듭니다:

첫째, AI 역량이 자연어 스펙이 신뢰성 있게 작동하는 코드를 생성할 수 있는 임계점에 도달했습니다. 이것은 개발자를 대체하는 것이 아닙니다---스펙에서 구현으로의 기계적 번역을 자동화함으로써 그들의 효과성을 증폭시키는 것입니다. 탐색과 창의성을 증폭시키고, “처음부터 다시 시작”을 쉽게 지원하며, 추가, 삭제, 비판적 사고를 지원할 수 있습니다.

둘째, 소프트웨어 복잡성이 기하급수적으로 계속 증가하고 있습니다. 현대 시스템은 수십 개의 서비스, 프레임워크, 의존성을 통합합니다. 수동 프로세스를 통해 이 모든 조각들을 원래 의도와 일치시키는 것은 점점 더 어려워집니다. SDD는 스펙 주도 생성을 통해 체계적인 정렬을 제공합니다. 프레임워크는 인간 우선 지원이 아닌 AI 우선 지원을 제공하도록 진화하거나, 재사용 가능한 컴포넌트를 중심으로 설계할 수 있습니다.

셋째, 변화의 속도가 가속화됩니다. 요구사항은 오늘날 그 어느 때보다 훨씬 빠르게 변경됩니다. 피봇(Pivoting)은 더 이상 예외적이지 않습니다---예상되는 것입니다. 현대 제품 개발은 사용자 피드백, 시장 상황, 경쟁 압력을 기반으로 한 빠른 반복을 요구합니다. 전통적인 개발은 이러한 변경을 방해물로 취급합니다. 각 피봇은 문서화, 설계, 코드 전반에 걸쳐 변경사항을 수동으로 전파해야 합니다. 그 결과는 속도를 제한하는 느리고 신중한 업데이트이거나, 기술 부채를 축적하는 빠르고 무모한 변경입니다.

SDD는 가정(what-if)/시뮬레이션 실험을 지원할 수 있습니다: “티셔츠를 더 많이 팔기 위한 비즈니스 요구를 촉진하기 위해 애플리케이션을 다시 구현하거나 변경해야 한다면, 어떻게 구현하고 실험할 것인가?”

SDD는 요구사항 변경을 장애물에서 일반적인 워크플로우로 변환합니다. 스펙이 구현을 주도할 때, 피봇은 수동 재작성이 아닌 체계적인 재생성이 됩니다. PRD의 핵심 요구사항을 변경하면, 영향받은 구현 계획이 자동으로 업데이트됩니다. 사용자 스토리를 수정하면, 해당 API 엔드포인트가 재생성됩니다. 이것은 초기 개발에 관한 것만이 아닙니다---불가피한 변경을 통해 엔지니어링 속도를 유지하는 것에 관한 것입니다.

핵심 원칙 (Core Principles)

공통어로서의 스펙 (Specifications as the Lingua Franca): 스펙이 주요 산출물이 됩니다. 코드는 특정 언어와 프레임워크에서의 표현이 됩니다. 소프트웨어 유지보수는 스펙을 진화시키는 것을 의미합니다.

실행 가능한 스펙 (Executable Specifications): 스펙은 작동하는 시스템을 생성할 수 있을 만큼 정밀하고, 완전하며, 명확해야 합니다. 이는 의도와 구현 사이의 간극을 제거합니다.

지속적인 개선 (Continuous Refinement): 일관성 검증은 일회성 게이트가 아니라 지속적으로 발생합니다. AI는 스펙의 모호성, 모순, 격차를 지속적인 프로세스로 분석합니다.

연구 주도 컨텍스트 (Research-Driven Context): 연구 에이전트는 스펙 프로세스 전반에 걸쳐 기술 옵션, 성능 영향, 조직 제약사항을 조사하며 중요한 컨텍스트를 수집합니다.

양방향 피드백 (Bidirectional Feedback): 프로덕션 현실이 스펙 진화를 알립니다. 메트릭, 인시던트, 운영 학습이 스펙 개선을 위한 입력이 됩니다.

탐색을 위한 브랜치 (Branching for Exploration): 동일한 스펙에서 여러 구현 접근법을 생성하여 성능, 유지보수성, 사용자 경험, 비용 등 다양한 최적화 목표를 탐색합니다.

구현 접근법 (Implementation Approaches)

오늘날 SDD를 실천하려면 기존 도구를 조합하고 프로세스 전반에 걸쳐 규율을 유지해야 합니다. 이 방법론은 다음과 같이 실천될 수 있습니다:

반복적인 스펙 개발을 위한 AI 어시스턴트
기술 컨텍스트 수집을 위한 연구 에이전트
스펙을 구현으로 번역하기 위한 코드 생성 도구
스펙 우선 워크플로우에 적응된 버전 관리 시스템
스펙 문서의 AI 분석을 통한 일관성 검사

핵심은 스펙을 진실의 원천으로 취급하고, 코드를 반대가 아닌 스펙을 위해 봉사하는 생성된 출력물로 취급하는 것입니다.

명령어로 SDD 간소화 (Streamlining SDD with Commands)

SDD 방법론은 스펙 → 계획 → 작업 워크플로우를 자동화하는 세 가지 강력한 명령어를 통해 크게 향상됩니다:

`/speckit.specify` 명령어

이 명령어는 단순한 기능 설명(사용자 프롬프트)을 자동 저장소 관리와 함께 완전하고 구조화된 스펙으로 변환합니다:

자동 기능 번호 부여: 기존 스펙을 스캔하여 다음 기능 번호 결정 (예: 001, 002, 003)
브랜치 생성: 설명에서 의미 있는 브랜치 이름을 생성하고 자동으로 생성
템플릿 기반 생성: 요구사항으로 기능 스펙 템플릿을 복사하고 커스터마이즈
디렉토리 구조: 모든 관련 문서를 위한 적절한 specs/[branch-name]/ 구조 생성

`/speckit.plan` 명령어

기능 스펙이 존재하면, 이 명령어는 포괄적인 구현 계획을 생성합니다:

스펙 분석: 기능 요구사항, 사용자 스토리, 수락 기준을 읽고 이해
헌법 준수 (Constitutional Compliance): 프로젝트 헌법(constitution)과 아키텍처 원칙과의 정렬 보장
기술적 번역: 비즈니스 요구사항을 기술 아키텍처와 구현 세부사항으로 변환
상세한 문서화: 데이터 모델, API 계약, 테스트 시나리오를 위한 지원 문서 생성
빠른 시작 검증 (Quickstart Validation): 주요 검증 시나리오를 담은 빠른 시작 가이드 생성

`/speckit.tasks` 명령어

계획이 생성된 후, 이 명령어는 계획과 관련 설계 문서를 분석하여 실행 가능한 작업 목록을 생성합니다:

입력: plan.md=(필수)를 읽고, 있다면 =data-model.md, contracts/, =research.md=도 읽음
작업 도출: 계약(contracts), 엔티티, 시나리오를 구체적인 작업으로 변환
병렬화: 독립적인 작업을 =[P]=로 표시하고 안전한 병렬 그룹 개요 작성
출력: Task 에이전트가 실행할 수 있도록 기능 디렉토리에 tasks.md 작성

예시: 채팅 기능 구축 (Example: Building a Chat Feature)

다음은 이 명령어들이 전통적인 개발 워크플로우를 어떻게 변환하는지 보여줍니다:

전통적 접근법:

1. 문서에 PRD 작성 (2-3시간)
2. 설계 문서 생성 (2-3시간)
3. 프로젝트 구조 수동 설정 (30분)
4. 기술 스펙 작성 (3-4시간)
5. 테스트 계획 생성 (2시간)
총: 약 12시간의 문서 작업

SDD 명령어 접근법:

# 1단계: 기능 스펙 생성 (5분)
/speckit.specify Real-time chat system with message history and user presence
 
# 자동으로 수행:
# - "003-chat-system" 브랜치 생성
# - specs/003-chat-system/spec.md 생성
# - 구조화된 요구사항으로 채움
 
# 2단계: 구현 계획 생성 (5분)
/speckit.plan WebSocket for real-time messaging, PostgreSQL for history, Redis for presence
 
# 3단계: 실행 가능한 작업 생성 (5분)
/speckit.tasks
 
# 자동으로 생성:
# - specs/003-chat-system/plan.md
# - specs/003-chat-system/research.md (WebSocket 라이브러리 비교)
# - specs/003-chat-system/data-model.md (Message와 User 스키마)
# - specs/003-chat-system/contracts/ (WebSocket 이벤트, REST 엔드포인트)
# - specs/003-chat-system/quickstart.md (주요 검증 시나리오)
# - specs/003-chat-system/tasks.md (계획에서 도출된 작업 목록)

15분 안에 다음을 얻습니다:

사용자 스토리와 수락 기준을 포함한 완전한 기능 스펙
기술 선택과 근거를 포함한 상세한 구현 계획
코드 생성을 위한 준비된 API 계약과 데이터 모델
자동 및 수동 테스트 모두를 위한 포괄적인 테스트 시나리오
기능 브랜치에 적절히 버전 관리된 모든 문서

구조화된 자동화의 힘 (The Power of Structured Automation)

이 명령어들은 단순히 시간을 절약하는 것이 아닙니다---일관성과 완전성을 강제합니다:

잊혀진 세부사항 없음: 템플릿이 비기능 요구사항에서 오류 처리까지 모든 측면을 고려하도록 보장
추적 가능한 결정: 모든 기술 선택이 특정 요구사항으로 연결됨
살아있는 문서화 (Living Documentation): 스펙이 코드를 생성하기 때문에 코드와 동기화 유지
빠른 반복: 요구사항을 변경하고 며칠이 아닌 몇 분 만에 계획을 재생성

명령어들은 스펙을 정적 문서가 아닌 실행 가능한 산출물로 취급함으로써 SDD 원칙을 구현합니다. 스펙 프로세스를 필요악에서 개발의 추진력으로 변환합니다.

템플릿 주도 품질: 구조가 LLM을 어떻게 제약하여 더 나은 결과를 만드는가

이 명령어들의 진정한 힘은 자동화뿐만 아니라, 템플릿이 LLM 행동을 더 높은 품질의 스펙으로 안내하는 방식에 있습니다. 템플릿은 LLM의 출력을 생산적인 방식으로 제약하는 정교한 프롬프트로 작용합니다:

1. 조기 구현 세부사항 방지

기능 스펙 템플릿은 명시적으로 지시합니다:

- ✅ 사용자가 필요한 것과 이유에 집중
- ❌ 구현 방법 회피 (기술 스택, API, 코드 구조 없음)

이 제약은 LLM이 적절한 추상화 수준을 유지하도록 강제합니다. LLM이 자연스럽게 “React와 Redux를 사용하여 구현”으로 뛰어들 수 있을 때, 템플릿은 “사용자는 데이터의 실시간 업데이트가 필요함”에 집중하도록 유지합니다. 이러한 분리는 구현 기술이 변경되더라도 스펙이 안정적으로 유지되도록 보장합니다.

2. 명시적 불확실성 마커 강제

두 템플릿 모두 [NEEDS CLARIFICATION] 마커 사용을 의무화합니다:

사용자 프롬프트에서 이 스펙을 생성할 때:
1. **모든 모호성 표시**: [NEEDS CLARIFICATION: 구체적인 질문] 사용
2. **추측하지 않음**: 프롬프트가 무언가를 명시하지 않으면, 표시

이는 그럴듯하지만 잠재적으로 잘못될 수 있는 가정을 만드는 일반적인 LLM 행동을 방지합니다. “로그인 시스템”이 이메일/비밀번호 인증을 사용한다고 추측하는 대신, LLM은 =[NEEDS CLARIFICATION: 인증 방법이 명시되지 않음 - 이메일/비밀번호, SSO, OAuth?]=로 표시해야 합니다.

3. 체크리스트를 통한 구조화된 사고

템플릿은 스펙을 위한 “단위 테스트” 역할을 하는 포괄적인 체크리스트를 포함합니다:

### 요구사항 완전성
- [ ] [NEEDS CLARIFICATION] 마커가 남아있지 않음
- [ ] 요구사항이 테스트 가능하고 명확함
- [ ] 성공 기준이 측정 가능함

이러한 체크리스트는 LLM이 출력을 체계적으로 자체 검토하도록 강제하여, 그렇지 않으면 놓칠 수 있는 격차를 포착합니다. LLM에게 품질 보증 프레임워크를 제공하는 것과 같습니다.

4. 게이트를 통한 헌법 준수

구현 계획 템플릿은 단계 게이트를 통해 아키텍처 원칙을 강제합니다:

### Phase -1: Pre-Implementation Gates
#### Simplicity Gate (Article VII)
- [ ] ≤3개 프로젝트 사용?
- [ ] 미래 대비(future-proofing) 없음?
#### Anti-Abstraction Gate (Article VIII)
- [ ] 프레임워크를 직접 사용?
- [ ] 단일 모델 표현?

이러한 게이트는 LLM이 모든 복잡성을 명시적으로 정당화하도록 하여 과도한 엔지니어링을 방지합니다. 게이트가 실패하면, LLM은 “복잡성 추적(Complexity Tracking)” 섹션에 이유를 문서화해야 하며, 아키텍처 결정에 대한 책임성을 만듭니다.

5. 계층적 세부사항 관리

템플릿은 적절한 정보 아키텍처를 강제합니다:

**중요**: 이 구현 계획은 높은 수준이고 읽기 쉬워야 합니다.
코드 샘플, 상세한 알고리즘, 또는 광범위한 기술 스펙은
적절한 `implementation-details/` 파일에 배치되어야 합니다

이는 스펙이 읽을 수 없는 코드 덤프가 되는 일반적인 문제를 방지합니다. LLM은 적절한 세부 수준을 유지하는 법을 배우고, 메인 문서를 탐색 가능하게 유지하면서 복잡성을 별도 파일로 추출합니다.

6. 테스트 우선 사고

구현 템플릿은 테스트 우선 개발을 강제합니다:

### 파일 생성 순서
1. API 스펙으로 `contracts/` 생성
2. 테스트 파일을 순서대로 생성: contract → integration → e2e → unit
3. 테스트를 통과시키기 위한 소스 파일 생성

이 순서 제약은 LLM이 구현 전에 테스트 가능성과 계약에 대해 생각하도록 보장하여, 더 견고하고 검증 가능한 스펙으로 이어집니다.

7. 추측성 기능 방지

템플릿은 명시적으로 추측을 억제합니다:

- [ ] 추측성 또는 "필요할 수도 있는" 기능 없음
- [ ] 모든 단계가 명확한 전제조건과 산출물을 가짐

이는 LLM이 구현을 복잡하게 만드는 “있으면 좋은” 기능을 추가하는 것을 막습니다. 모든 기능은 명확한 수락 기준을 가진 구체적인 사용자 스토리로 추적되어야 합니다.

복합 효과 (The Compound Effect)

이러한 제약들은 함께 작동하여 다음과 같은 스펙을 생성합니다:

완전함: 체크리스트가 아무것도 잊혀지지 않도록 보장
명확함: 강제된 명확화 마커가 불확실성을 강조
테스트 가능함: 프로세스에 내장된 테스트 우선 사고
유지보수 가능함: 적절한 추상화 수준과 정보 계층
구현 가능함: 구체적인 산출물을 가진 명확한 단계

템플릿은 LLM을 창의적 작가에서 규율 있는 스펙 엔지니어로 변환하여, 진정으로 개발을 주도하는 일관되게 높은 품질의 실행 가능한 스펙을 생성하도록 역량을 집중시킵니다.

헌법적 기반: 아키텍처 규율 강제 (The Constitutional Foundation)

SDD의 핵심에는 헌법(constitution)이 있습니다---스펙이 코드가 되는 방식을 지배하는 불변의 원칙 집합입니다. 헌법(memory/constitution.md)은 시스템의 아키텍처 DNA로 작용하여, 생성된 모든 구현이 일관성, 단순성, 품질을 유지하도록 보장합니다.

개발의 아홉 가지 조항 (The Nine Articles of Development)

헌법은 개발 프로세스의 모든 측면을 형성하는 아홉 가지 조항을 정의합니다:

조항 I: 라이브러리 우선 원칙 (Library-First Principle)

모든 기능은 독립 실행형 라이브러리로 시작해야 합니다---예외 없이. 이는 처음부터 모듈식 설계를 강제합니다:

Specify의 모든 기능은 독립 실행형 라이브러리로 존재를 시작해야 합니다.
재사용 가능한 라이브러리 컴포넌트로 먼저 추상화되지 않고
애플리케이션 코드 내에 직접 구현되어서는 안 됩니다.

이 원칙은 스펙이 모놀리식 애플리케이션이 아닌 명확한 경계와 최소한의 의존성을 가진 모듈식, 재사용 가능한 코드를 생성하도록 보장합니다. LLM이 구현 계획을 생성할 때, 기능을 라이브러리로 구조화해야 합니다.

조항 II: CLI 인터페이스 의무 (CLI Interface Mandate)

모든 라이브러리는 명령줄 인터페이스를 통해 기능을 노출해야 합니다:

모든 CLI 인터페이스는 다음을 따라야 합니다:
- 텍스트를 입력으로 받음 (stdin, 인수, 또는 파일을 통해)
- 텍스트를 출력으로 생성 (stdout을 통해)
- 구조화된 데이터 교환을 위한 JSON 형식 지원

이는 관찰 가능성과 테스트 가능성을 강제합니다. LLM은 불투명한 클래스 내부에 기능을 숨길 수 없습니다---모든 것이 텍스트 기반 인터페이스를 통해 접근 가능하고 검증 가능해야 합니다.

조항 III: 테스트 우선 명령 (Test-First Imperative)

가장 변혁적인 조항---테스트 전에는 코드 없음:

협상 불가: 모든 구현은 엄격한 테스트 주도 개발을 따라야 합니다.
다음 이전에 구현 코드를 작성해서는 안 됩니다:
1. 단위 테스트 작성
2. 사용자가 테스트를 검증하고 승인
3. 테스트가 실패함을 확인 (Red phase)

이는 전통적인 AI 코드 생성을 완전히 역전시킵니다. 코드를 생성하고 작동하기를 바라는 대신, LLM은 먼저 행동을 정의하는 포괄적인 테스트를 생성하고, 승인을 받고, 그 다음에만 구현을 생성해야 합니다.

조항 VII & VIII: 단순성과 반추상화 (Simplicity and Anti-Abstraction)

이 쌍을 이루는 조항들은 과도한 엔지니어링에 맞섭니다:

섹션 7.3: 최소 프로젝트 구조
- 초기 구현을 위한 최대 3개 프로젝트
- 추가 프로젝트는 문서화된 정당화 필요
 
섹션 8.1: 프레임워크 신뢰
- 프레임워크를 래핑하는 대신 직접 사용

LLM이 자연스럽게 정교한 추상화를 만들 수 있을 때, 이 조항들은 모든 복잡성 계층을 정당화하도록 강제합니다. 구현 계획 템플릿의 “Phase -1 Gates”는 이러한 원칙을 직접 강제합니다.

조항 IX: 통합 우선 테스트 (Integration-First Testing)

격리된 단위 테스트보다 실제 테스트를 우선시합니다:

테스트는 현실적인 환경을 사용해야 합니다:
- 모의 객체보다 실제 데이터베이스 선호
- 스텁보다 실제 서비스 인스턴스 사용
- 구현 전 계약 테스트 필수

이는 생성된 코드가 이론뿐만 아니라 실제로 작동하도록 보장합니다.

템플릿을 통한 헌법 강제 (Constitutional Enforcement Through Templates)

구현 계획 템플릿은 구체적인 체크포인트를 통해 이러한 조항들을 운영화합니다:

### Phase -1: Pre-Implementation Gates
#### Simplicity Gate (Article VII)
- [ ] ≤3개 프로젝트 사용?
- [ ] 미래 대비 없음?
 
#### Anti-Abstraction Gate (Article VIII)
- [ ] 프레임워크를 직접 사용?
- [ ] 단일 모델 표현?
 
#### Integration-First Gate (Article IX)
- [ ] 계약 정의됨?
- [ ] 계약 테스트 작성됨?

이러한 게이트는 아키텍처 원칙을 위한 컴파일 타임 검사로 작용합니다. LLM은 게이트를 통과하거나 “복잡성 추적” 섹션에 정당화된 예외를 문서화하지 않고는 진행할 수 없습니다.

불변 원칙의 힘 (The Power of Immutable Principles)

헌법의 힘은 그 불변성에 있습니다. 구현 세부사항은 진화할 수 있지만, 핵심 원칙은 일정하게 유지됩니다. 이는 다음을 제공합니다:

시간에 걸친 일관성: 오늘 생성된 코드는 내년에 생성된 코드와 동일한 원칙을 따름
LLM 간 일관성: 다른 AI 모델이 아키텍처적으로 호환되는 코드를 생성
아키텍처 무결성: 모든 기능이 시스템 설계를 훼손하지 않고 강화
품질 보증: 테스트 우선, 라이브러리 우선, 단순성 원칙이 유지보수 가능한 코드를 보장

헌법의 진화 (Constitutional Evolution)

원칙은 불변이지만, 그 적용은 진화할 수 있습니다:

섹션 4.2: 수정 프로세스
이 헌법의 수정은 다음을 요구합니다:
- 변경 근거의 명시적 문서화
- 프로젝트 유지관리자의 검토 및 승인
- 하위 호환성 평가

이는 방법론이 안정성을 유지하면서 학습하고 개선할 수 있도록 합니다. 헌법은 날짜가 있는 수정안으로 자체 진화를 보여주며, 원칙이 실제 경험을 바탕으로 어떻게 개선될 수 있는지 보여줍니다.

규칙을 넘어: 개발 철학 (Beyond Rules: A Development Philosophy)

헌법은 단순한 규칙집이 아닙니다---LLM이 코드 생성에 대해 생각하는 방식을 형성하는 철학입니다:

불투명성보다 관찰 가능성: 모든 것이 CLI 인터페이스를 통해 검사 가능해야 함
영리함보다 단순성: 단순하게 시작하고, 입증된 필요성이 있을 때만 복잡성 추가
격리보다 통합: 인공적인 환경이 아닌 실제 환경에서 테스트
모놀리스보다 모듈성: 모든 기능이 명확한 경계를 가진 라이브러리

이러한 원칙을 스펙 및 계획 프로세스에 포함함으로써, SDD는 생성된 코드가 단순히 기능적인 것만이 아니라 유지보수 가능하고, 테스트 가능하며, 아키텍처적으로 건전하도록 보장합니다. 헌법은 AI를 코드 생성기에서 시스템 설계 원칙을 존중하고 강화하는 아키텍처 파트너로 변환합니다.

변혁 (The Transformation)

이것은 개발자를 대체하거나 창의성을 자동화하는 것이 아닙니다. 기계적 번역을 자동화함으로써 인간의 역량을 증폭시키는 것입니다. 스펙, 연구, 코드가 함께 진화하는 긴밀한 피드백 루프를 만드는 것이며, 각 반복이 의도와 구현 사이의 더 깊은 이해와 더 나은 정렬을 가져옵니다.

소프트웨어 개발은 의도와 구현 사이의 정렬을 유지하기 위한 더 나은 도구가 필요합니다. SDD는 단순히 코드를 안내하는 것이 아니라 코드를 생성하는 실행 가능한 스펙을 통해 이러한 정렬을 달성하기 위한 방법론을 제공합니다.

junghanacs🧠

Table of Contents

Backlinks

스펙 중심 개발(SDD) 동향 및 전략