Specification-Driven Development (SDD)

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

GitHub - github/spec-kit: 💫 Toolkit to help you get started with Spec-Driven Development

 

Specification-Driven Development (SDD)

파워 인버전

수십 년 동안 코드는 왕이었습니다. 명세는 코드를 위한 것이었습니다. 우리가 세운 발판과 같았고, 코딩이라는 "진짜 작업"이 시작되면 버려졌습니다. 개발을 안내하기 위해 PRD를 작성하고, 구현을 위한 설계 문서를 만들고, 아키텍처를 시각화하기 위해 다이어그램을 그렸습니다. 하지만 이러한 것들은 항상 코드 자체에 종속되었습니다. 코드는 진실이었고, 그 외의 모든 것은 기껏해야 좋은 의도였습니다. 코드는 진실의 원천이었고, 코드가 발전함에 따라 명세는 거의 보조를 맞추지 못했습니다. 자산(코드)과 구현은 하나이기 때문에, 코드를 기반으로 구축하지 않고는 병렬 구현을 하는 것이 쉽지 않습니다.

사양 주도 개발(SDD)은 이러한 권력 구조를 뒤집습니다. 사양은 코드를 위한 것이 아니라, 코드가 사양을 위한 것입니다. 제품 요구 사항 문서(PRD)는 구현을 위한 지침이 아니라, 구현을 생성하는 소스입니다. 기술 계획은 코딩에 필요한 정보를 제공하는 문서가 아니라, 코드를 생성하는 정확한 정의입니다. SDD는 소프트웨어 개발 방식을 점진적으로 개선하는 것이 아니라, 개발을 주도하는 요소를 근본적으로 재고하는 것입니다.

사양과 구현 사이의 간극은 소프트웨어 개발이 시작된 이래로 끊임없이 문제였습니다. 우리는 더 나은 문서화, 더 상세한 요구사항, 더 엄격한 프로세스를 통해 이 간극을 메우려고 노력해 왔습니다. 하지만 이러한 접근 방식은 간극을 불가피한 것으로 받아들이기 때문에 실패합니다. 간극을 줄이려고 노력할 뿐, 결코 완전히 없애지는 못합니다. SDD는 사양과 사양에서 도출된 구체적인 구현 계획을 실행 가능하게 만들어 이러한 간극을 해소합니다. 사양과 구현 계획이 코드를 생성할 때, 간극은 존재하지 않습니다. 오직 변형만이 존재할 뿐입니다.

이러한 변화는 AI가 복잡한 사양을 이해하고 구현하며, 세부적인 구현 계획을 수립할 수 있기 때문에 이제 가능해졌습니다. 하지만 구조가 없는 원시 AI 생성은 혼란을 야기합니다. SDD는 작동 시스템을 생성할 만큼 정확하고 완전하며 명확한 사양과 후속 구현 계획을 통해 이러한 구조를 제공합니다. 사양은 주요 아티팩트가 되고, 코드는 특정 언어와 프레임워크를 사용한 (구현 계획에 따른) 표현이 됩니다.

이 새로운 세상에서 소프트웨어 유지 관리는 사양의 진화를 의미합니다. 개발팀의 의도는 자연어(" 의도 주도 개발 "), 설계 자산, 핵심 원칙 및 기타 지침으로 표현됩니다. 개발의 공통어는 더 높은 수준으로 이동하며, 코드는 최종 단계의 접근 방식입니다.

디버깅은 잘못된 코드를 생성하는 사양과 구현 계획을 수정하는 것을 의미합니다. 리팩토링은 명확성을 위해 구조를 재구축하는 것을 의미합니다. 전체 개발 워크플로는 사양을 핵심 정보의 원천으로 삼고, 구현 계획과 코드를 지속적으로 재생성되는 출력으로 삼아 재구성됩니다. 새로운 기능으로 앱을 업데이트하거나 새로운 병렬 구현을 만드는 것은 (창의적인 존재이기 때문에) 사양을 다시 검토하고 새로운 구현 계획을 만드는 것을 의미합니다. 따라서 이 과정은 0 -> 1, (1', ..), 2, 3, N입니다.

개발팀은 창의성, 실험정신, 비판적 사고에 중점을 둡니다.

실제 SDD 워크플로

워크플로는 종종 모호하고 불완전한 아이디어에서 시작됩니다. AI와의 반복적인 대화를 통해 이 아이디어는 포괄적인 PRD가 됩니다. AI는 명확한 질문을 던지고, 경계 조건을 파악하며, 정확한 승인 기준을 정의하는 데 도움을 줍니다. 기존 개발 방식에서는 며칠씩 회의와 문서 작성에 소요될 수 있는 작업이 몇 시간 만에 집중적인 사양 작업으로 완료됩니다. 이는 기존 SDLC를 혁신합니다. 요구 사항과 설계가 개별 단계가 아닌 지속적인 활동이 됩니다. 이는 팀에서 검토한 사양을 표현하고 버전 관리하며, 분기별로 생성하고 병합하는 팀 프로세스 를 지원합니다 .

제품 관리자가 승인 기준을 업데이트하면 구현 계획에 영향을 받는 기술적 결정 사항이 자동으로 표시됩니다. 아키텍트가 더 나은 패턴을 발견하면 PRD가 업데이트되어 새로운 가능성을 반영합니다.

이 사양 프로세스 전반에 걸쳐 연구 담당자들은 중요한 맥락을 수집합니다. 라이브러리 호환성, 성능 벤치마크, 그리고 보안 관련 사항들을 조사합니다. 조직적 제약 조건들은 자동으로 발견되고 적용되며, 회사의 데이터베이스 표준, 인증 요구 사항, 그리고 배포 정책은 모든 사양에 완벽하게 통합됩니다.

AI는 PRD를 통해 요구사항을 기술적 결정에 매핑하는 구현 계획을 생성합니다. 모든 기술 선택에는 명확한 근거가 있으며, 모든 아키텍처 결정은 특정 요구사항으로 거슬러 올라갑니다. 이 프로세스 전반에 걸쳐 일관성 검증을 통해 품질이 지속적으로 향상됩니다. AI는 모호성, 모순, 그리고 격차를 파악하기 위해 사양을 분석하는데, 이는 일회성 조치가 아니라 지속적인 개선 과정입니다.

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

피드백 루프는 초기 개발 단계를 넘어 확장됩니다. 프로덕션 지표와 인시던트는 단순히 핫픽스를 유발하는 것이 아니라, 다음 세대를 위한 사양을 업데이트합니다. 성능 병목 현상은 새로운 비기능적 요구사항이 되고, 보안 취약점은 모든 미래 세대에 영향을 미치는 제약 조건이 됩니다. 사양, 구현, 그리고 운영 현실 사이의 이러한 반복적인 과정을 통해 진정한 이해가 형성되고, 기존 SDLC가 지속적인 진화로 전환됩니다.

지금 SDD가 중요한 이유

SDD를 가능하게 할 뿐만 아니라 필수로 만드는 세 가지 추세는 다음과 같습니다.

첫째, AI 역량은 자연어 사양을 통해 안정적으로 작동하는 코드를 생성할 수 있는 한계점에 도달했습니다. 이는 개발자를 대체하는 것이 아니라, 사양에서 구현으로의 기계적인 번역을 자동화하여 개발자의 효율성을 높이는 것입니다. 탐구와 창의성을 증폭시키고, "다시 시작하기"를 쉽게 지원하고, 덧셈, 뺄셈, 그리고 비판적 사고를 지원할 수 있습니다.

둘째, 소프트웨어 복잡성은 기하급수적으로 증가하고 있습니다. 최신 시스템은 수십 개의 서비스, 프레임워크, 그리고 종속성을 통합합니다. 수동 프로세스를 통해 이러한 모든 요소들을 원래 의도에 맞게 정렬하는 것은 점점 더 어려워지고 있습니다. SDD는 사양 기반 생성을 통해 체계적인 정렬을 제공합니다. 프레임워크는 인간 중심 지원이 아닌 AI 중심 지원을 제공하거나 재사용 가능한 구성 요소를 중심으로 설계되도록 발전할 수 있습니다.

셋째, 변화의 속도가 가속화되고 있습니다. 오늘날 요구사항은 그 어느 때보다 훨씬 빠르게 변화합니다. 피벗팅(pivoting)은 더 이상 예외적인 현상이 아니라, 이미 예상된 현상입니다. 현대 제품 개발은 사용자 피드백, 시장 상황, 그리고 경쟁 압력에 기반한 신속한 반복 작업을 요구합니다. 전통적인 개발 방식은 이러한 변화를 일종의 혼란으로 간주합니다. 각 피벗팅은 문서, 설계, 그리고 코드를 통해 변경 사항을 수동으로 전파해야 합니다. 그 결과, 속도가 제한되는 느리고 신중한 업데이트가 이루어지거나, 기술 부채가 누적되는 빠르고 무모한 변경이 초래됩니다.

SDD는 가정/시뮬레이션 실험을 지원할 수 있습니다. "T셔츠 판매 증가라는 사업적 필요성을 홍보하기 위해 애플리케이션을 다시 구현하거나 변경해야 하는 경우, 어떻게 구현하고 실험해야 할까요?"

SDD는 요구사항 변경을 장애물에서 정상적인 워크플로로 전환합니다. 명세가 구현을 주도할 때, 피벗은 수동 재작성이 아닌 체계적인 재생성으로 전환됩니다. PRD에서 핵심 요구사항을 변경하면 영향을 받는 구현 계획이 자동으로 업데이트됩니다. 사용자 스토리를 수정하면 해당 API 엔드포인트가 재생성됩니다. 이는 단순히 초기 개발에 국한되지 않습니다. 불가피한 변경에도 엔지니어링 속도를 유지하는 것이 중요합니다.

핵심 원칙

링구아 프랑카로서의 사양 : 사양은 주요 산출물이 됩니다. 코드는 특정 언어와 프레임워크로 표현됩니다. 소프트웨어를 유지 관리한다는 것은 사양을 발전시키는 것을 의미합니다.

실행 가능한 사양 : 사양은 작동 시스템을 생성할 수 있을 만큼 정확하고, 완전하며, 명확해야 합니다. 이를 통해 의도와 구현 사이의 간극을 없앨 수 있습니다.

지속적인 개선 : 일관성 검증은 일회성 게이트가 아닌 지속적으로 진행됩니다. AI는 모호성, 모순, 그리고 격차를 파악하기 위해 사양을 지속적인 프로세스로 분석합니다.

연구 중심 맥락 : 연구 담당자는 사양 설정 프로세스 전반에 걸쳐 중요한 맥락을 수집하고 기술적 옵션, 성과 영향, 조직적 제약을 조사합니다.

양방향 피드백 : 생산 현실은 사양 진화에 영향을 미칩니다. 지표, 사고, 그리고 운영 과정에서 얻은 교훈은 사양 개선을 위한 입력 자료가 됩니다.

탐색을 위한 분기 : 동일한 사양에서 여러 구현 방식을 생성하여 성능, 유지 관리, 사용자 경험, 비용 등 다양한 최적화 목표를 탐색합니다.

구현 접근 방식

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

• 반복적인 사양 개발을 위한 AI 어시스턴트
• 기술적 맥락을 수집하기 위한 연구 에이전트
• 사양을 구현으로 변환하기 위한 코드 생성 도구
• 사양 우선 워크플로에 맞게 조정된 버전 제어 시스템
• AI 분석을 통한 사양 문서의 일관성 검사

핵심은 사양을 진실의 원천으로 취급하고, 사양을 구현하는 생성된 출력으로 코드를 사용하는 것이지, 그 반대가 아니라는 것입니다.

명령을 사용하여 SDD 간소화

SDD 방법론은 사양 → 계획 → 작업 워크플로를 자동화하는 세 가지 강력한 명령을 통해 크게 향상되었습니다.

명령/specify​

이 명령은 간단한 기능 설명(사용자 프롬프트)을 자동 저장소 관리 기능을 갖춘 완전하고 구조화된 사양으로 변환합니다.

1. 자동 기능 번호 매기기 : 기존 사양을 스캔하여 다음 기능 번호(예: 001, 002, 003)를 결정합니다.
2. 브랜치 생성 : 설명에서 의미적 브랜치 이름을 생성하고 자동으로 생성합니다.
3. 템플릿 기반 생성 : 요구 사항에 맞게 기능 사양 템플릿을 복사하고 사용자 정의합니다.
4. 디렉토리 구조specs/[branch-name]/ : 모든 관련 문서에 대한 적절한 구조를 만듭니다.

명령/plan​

기능 사양이 존재하면 이 명령은 포괄적인 구현 계획을 만듭니다.

1. 사양 분석 : 기능 요구 사항, 사용자 스토리 및 승인 기준을 읽고 이해합니다.
2. 헌법 준수 : 프로젝트 헌법 및 건축 원칙과의 일치를 보장합니다.
3. 기술 번역 : 비즈니스 요구 사항을 기술 아키텍처 및 구현 세부 정보로 변환합니다.
4. 상세 문서 : 데이터 모델, API 계약 및 테스트 시나리오에 대한 지원 문서를 생성합니다.
5. 빠른 시작 검증 : 주요 검증 시나리오를 포착하는 빠른 시작 가이드를 생성합니다.

명령/tasks​

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

1. 입력 : 읽기 plan.md(필수) 및 존재하는 경우, data-model.md, contracts/및research.md
2. 작업 파생 : 계약, 엔터티 및 시나리오를 특정 작업으로 변환합니다.
3. 병렬화 : 독립적인 작업을 표시 [P]하고 안전한 병렬 그룹을 간략하게 설명합니다.
4. 출력 : tasks.md태스크 에이전트가 실행할 수 있도록 기능 디렉토리에 기록합니다.

예: 채팅 기능 구축

이러한 명령이 기존 개발 워크플로를 어떻게 변화시키는지 살펴보겠습니다.

전통적인 접근 방식:

1. Write a PRD in a document (2-3 hours)
2. Create design documents (2-3 hours)
3. Set up project structure manually (30 minutes)
4. Write technical specifications (3-4 hours)
5. Create test plans (2 hours)
Total: ~12 hours of documentation work

 

명령을 사용한 SDD 접근 방식:

# Step 1: Create the feature specification (5 minutes)
/specify Real-time chat system with message history and user presence

# This automatically:
# - Creates branch "003-chat-system"
# - Generates specs/003-chat-system/spec.md
# - Populates it with structured requirements

# Step 2: Generate implementation plan (5 minutes)
/plan WebSocket for real-time messaging, PostgreSQL for history, Redis for presence

# Step 3: Generate executable tasks (5 minutes)
/tasks

# This automatically creates:
# - specs/003-chat-system/plan.md
# - specs/003-chat-system/research.md (WebSocket library comparisons)
# - specs/003-chat-system/data-model.md (Message and User schemas)
# - specs/003-chat-system/contracts/ (WebSocket events, REST endpoints)
# - specs/003-chat-system/quickstart.md (Key validation scenarios)
# - specs/003-chat-system/tasks.md (Task list derived from the plan)

 

15분 안에 다음을 얻을 수 있습니다.

• 사용자 스토리와 수용 기준이 포함된 완전한 기능 사양
• 기술 선택 및 근거를 포함한 자세한 구현 계획
• 코드 생성을 위한 API 계약 및 데이터 모델 준비 완료
• 자동 및 수동 테스트를 위한 포괄적인 테스트 시나리오
• 모든 문서는 기능 브랜치에서 적절하게 버전이 지정됩니다.

구조화된 자동화의 힘

이러한 명령은 시간을 절약할 뿐만 아니라 일관성과 완전성을 강화합니다.

1. 잊혀진 세부 사항 없음 : 템플릿은 비기능적 요구 사항부터 오류 처리까지 모든 측면이 고려되도록 보장합니다.
2. 추적 가능한 결정 : 모든 기술적 선택은 특정 요구 사항으로 연결됩니다.
3. 살아있는 문서 : 사양은 코드를 생성하기 때문에 코드와 동기화 상태를 유지합니다.
4. 빠른 반복 : 며칠이 아닌 몇 분 만에 요구 사항을 변경하고 계획을 재생성합니다.

이 명령들은 명세를 정적인 문서가 아닌 실행 가능한 아티팩트로 취급함으로써 SDD 원칙을 구현합니다. 명세 작성 과정을 필요악에서 개발의 원동력으로 전환합니다.

템플릿 기반 품질: 구조가 더 나은 결과를 위해 LLM을 제한하는 방식

이러한 명령의 진정한 힘은 단순히 자동화에만 있는 것이 아니라, 템플릿이 LLM 동작을 더 높은 품질의 사양으로 유도하는 방식에 있습니다. 템플릿은 LLM의 출력을 생산적인 방식으로 제한하는 정교한 프롬프트 역할을 합니다.

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

기능 사양 템플릿은 다음을 명시적으로 지시합니다.

- ✅ Focus on WHAT users need and WHY
- ❌ Avoid HOW to implement (no tech stack, APIs, code structure)

 

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

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

두 템플릿 모두 마커 사용을 요구합니다 [NEEDS CLARIFICATION].

When creating this spec from a user prompt:
1. **Mark all ambiguities**: Use [NEEDS CLARIFICATION: specific question]
2. **Don't guess**: If the prompt doesn't specify something, mark it

 

이렇게 하면 LLM에서 흔히 발생하는, 그럴듯하지만 잠재적으로 잘못된 가정을 하는 현상을 방지할 수 있습니다. LLM은 "로그인 시스템"이 이메일/비밀번호 인증을 사용한다고 추측하는 대신, 이를 "로그인 시스템"으로 표시해야 합니다 [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?].

3. 체크리스트를 통한 체계적인 사고

템플릿에는 사양에 대한 "단위 테스트" 역할을 하는 포괄적인 체크리스트가 포함되어 있습니다.

### Requirement Completeness
- [ ] No [NEEDS CLARIFICATION] markers remain
- [ ] Requirements are testable and unambiguous
- [ ] Success criteria are measurable

 

이러한 체크리스트는 LLM이 자신의 결과물을 체계적으로 자체 검토하도록 하여, 그렇지 않으면 간과될 수 있는 빈틈을 포착하도록 합니다. 이는 LLM에 품질 보증 프레임워크를 제공하는 것과 같습니다.

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

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

### Phase -1: Pre-Implementation Gates
#### Simplicity Gate (Article VII)
- [ ] Using ≤3 projects?
- [ ] No future-proofing?
#### Anti-Abstraction Gate (Article VIII)
- [ ] Using framework directly?
- [ ] Single model representation?

 

이러한 게이트는 LLM이 복잡성의 원인을 명시적으로 제시하도록 하여 과도한 엔지니어링을 방지합니다. 게이트가 실패할 경우, LLM은 "복잡성 추적" 섹션에 그 이유를 문서화하여 아키텍처 결정에 대한 책임을 부여해야 합니다.

5. 계층적 세부 관리

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

**IMPORTANT**: This implementation plan should remain high-level and readable.
Any code samples, detailed algorithms, or extensive technical specifications
must be placed in the appropriate `implementation-details/` file

 

이를 통해 사양이 읽을 수 없는 코드 덤프가 되는 일반적인 문제를 방지할 수 있습니다. LLM은 적절한 세부 정보 수준을 유지하고, 주요 문서의 탐색 가능성을 유지하면서도 각 파일의 복잡성을 추출하는 방법을 학습합니다.

6. 테스트 우선 사고방식

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

### File Creation Order
1. Create `contracts/` with API specifications
2. Create test files in order: contract → integration → e2e → unit
3. Create source files to make tests pass

 

이러한 순서 제약 조건은 LLM이 구현하기 전에 테스트 가능성과 계약에 대해 생각하도록 하여 보다 견고하고 검증 가능한 사양을 도출합니다.

7. 추측적 특징 방지

템플릿은 추측을 명백히 금지합니다.

- [ ] No speculative or "might need" features
- [ ] All phases have clear prerequisites and deliverables

 

이렇게 하면 LLM이 구현을 복잡하게 만드는 "있으면 좋은" 기능들을 추가하는 것을 막을 수 있습니다. 모든 기능은 명확한 수용 기준이 있는 구체적인 사용자 스토리를 기반으로 해야 합니다.

복합 효과

이러한 제약 조건은 함께 작용하여 다음과 같은 사양을 생성합니다.

• 완료 : 체크리스트를 통해 아무것도 잊지 않도록 합니다.
• 모호하지 않음 : 강제 명확화 마커는 불확실성을 강조합니다.
• 테스트 가능 : 테스트 우선 사고방식이 프로세스에 내장됨
• 유지 관리 가능 : 적절한 추상화 수준 및 정보 계층
• 구현 가능 : 구체적인 성과물을 포함한 명확한 단계

템플릿은 LLM을 창의적인 작가에서 규율 있는 사양 엔지니어로 전환시켜, 지속적으로 높은 품질의 실행 가능한 사양을 생산하고 개발을 진정으로 촉진하는 역량을 집중시킵니다.

헌법적 기반: 건축 규율 강화

SDD의 핵심에는 명세가 코드로 구현되는 방식을 규정하는 불변의 원칙인 헌법이 있습니다. 헌법( memory/constitution.md)은 시스템의 아키텍처 DNA 역할을 하며, 생성된 모든 구현이 일관성, 단순성, 그리고 품질을 유지하도록 보장합니다.

개발의 9가지 조항

헌법은 개발 과정의 모든 측면을 형성하는 9개 조항을 정의합니다.

제1조: 도서관 우선 원칙

모든 기능은 예외 없이 독립형 라이브러리로 시작해야 합니다. 따라서 처음부터 모듈형 설계가 필수적입니다.

Every feature in Specify MUST begin its existence as a standalone library.
No feature shall be implemented directly within application code without
first being abstracted into a reusable library component.

 

이 원칙은 명세가 단일 애플리케이션이 아닌 모듈화되고 재사용 가능한 코드를 생성하도록 보장합니다. LLM은 구현 계획을 생성할 때 명확한 경계와 최소한의 종속성을 가진 라이브러리 형태로 기능을 구조화해야 합니다.

제2조: CLI 인터페이스 의무

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

All CLI interfaces MUST:
- Accept text as input (via stdin, arguments, or files)
- Produce text as output (via stdout)
- Support JSON format for structured data exchange

 

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

제3조: 테스트 우선의 의무

가장 혁신적인 기사 - 테스트 전에는 코드가 없습니다.

This is NON-NEGOTIABLE: All implementation MUST follow strict Test-Driven Development.
No implementation code shall be written before:
1. Unit tests are written
2. Tests are validated and approved by the user
3. Tests are confirmed to FAIL (Red phase)

 

이는 기존 AI 코드 생성 방식을 완전히 뒤집습니다. 코드를 생성하고 작동하기를 바라는 대신, LLM은 먼저 동작을 정의하는 포괄적인 테스트를 생성하고 승인을 받은 후에야 구현을 생성해야 합니다.

제7조 및 제8조: 단순성과 추상화 방지

다음의 기사는 과도한 엔지니어링을 비판합니다.

Section 7.3: Minimal Project Structure
- Maximum 3 projects for initial implementation
- Additional projects require documented justification

Section 8.1: Framework Trust
- Use framework features directly rather than wrapping them

 

LLM이 자연스럽게 정교한 추상화를 생성할 수 있는 상황에서, 이러한 문서들은 LLM이 모든 복잡성을 정당화하도록 강요합니다. 구현 계획 템플릿의 "1단계 게이트"는 이러한 원칙을 직접적으로 강화합니다.

제9조: 통합 우선 테스트

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

Tests MUST use realistic environments:
- Prefer real databases over mocks
- Use actual service instances over stubs
- Contract tests mandatory before implementation

 

이렇게 하면 생성된 코드가 이론뿐만 아니라 실제로도 작동합니다.

템플릿을 통한 헌법 시행

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

### Phase -1: Pre-Implementation Gates
#### Simplicity Gate (Article VII)
- [ ] Using ≤3 projects?
- [ ] No future-proofing?

#### Anti-Abstraction Gate (Article VIII)
- [ ] Using framework directly?
- [ ] Single model representation?

#### Integration-First Gate (Article IX)
- [ ] Contracts defined?
- [ ] Contract tests written?

 

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

불변의 원칙의 힘

헌법의 힘은 불변성에 있습니다. 시행 세부 사항은 변경될 수 있지만, 핵심 원칙은 변함없이 유지됩니다. 이는 다음과 같은 이점을 제공합니다.

1. 시간 경과에 따른 일관성 : 오늘 생성된 코드는 내년에 생성된 코드와 동일한 원칙을 따릅니다.
2. LLM 간 일관성 : 다양한 AI 모델이 아키텍처적으로 호환되는 코드를 생성합니다.
3. 건축적 무결성 : 모든 기능은 시스템 설계를 약화시키는 것이 아니라 강화합니다.
4. 품질 보장 : 테스트 우선, 라이브러리 우선, 단순성 원칙은 유지 관리 가능한 코드를 보장합니다.

헌법적 진화

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

Section 4.2: Amendment Process
Modifications to this constitution require:
- Explicit documentation of the rationale for change
- Review and approval by project maintainers
- Backwards compatibility assessment

 

이를 통해 방법론은 안정성을 유지하면서 학습하고 개선할 수 있습니다. 헌법은 오랜 시간 동안 개정되어 온 내용을 통해 그 자체로 진화해 왔으며, 실제 경험을 바탕으로 원칙을 어떻게 개선할 수 있는지를 보여줍니다.

규칙을 넘어: 개발 철학

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

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

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

변형

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

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

Spec-Driven Development 워크플로우 재정리

🎯 핵심 개념

Spec-Driven Development는 전통적인 개발 방식을 뒤집는 접근법입니다. 코드 중심이 아닌 사양(Specification) 중심으로 개발하며, 사양이 직접 실행 가능한 구현체를 생성합니다.

📊 워크플로우 단계

1단계: 프로젝트 초기화

# 기본 프로젝트 생성
specify init <프로젝트명> --ai <AI도구>

# 현재 디렉토리에서 초기화
specify init --here --ai claude

지원 AI 도구:

• Claude Code
• GitHub Copilot
• Gemini CLI
• Cursor

2단계: 사양 정의 (/specify)

• 목적: "무엇을" 만들지와 "왜" 필요한지 정의
• 특징: 기술 스택은 언급하지 않음
• 결과물: specs/001-기능명/spec.md 파일 생성

/specify 사진을 앨범으로 정리할 수 있는 애플리케이션 구축. 
앨범은 날짜별로 그룹화되고 드래그앤드롭으로 재정리 가능. 
앨범 내 사진은 타일 인터페이스로 미리보기.

3단계: 기술 계획 수립 (/plan)

• 목적: 기술 스택과 아키텍처 선택
• 결과물:
  • plan.md - 구현 계획
  • data-model.md - 데이터 모델
  • api-spec.json - API 명세
  • research.md - 기술 조사
  • quickstart.md - 시작 가이드

/plan Vite 사용, 최소한의 라이브러리만 활용. 
바닐라 HTML, CSS, JavaScript 위주. 
로컬 SQLite 데이터베이스에 메타데이터 저장.

4단계: 작업 목록 생성 (/tasks)

• 목적: 실행 가능한 작업 목록 생성
• 결과물: 구체적인 구현 태스크 리스트

5단계: 구현 및 반복

• AI 에이전트가 실제 코드 구현
• 빌드 오류 해결
• 런타임 오류 수정
• 기능 검증 및 개선

🔄 개발 단계별 접근법

단계 포커스 주요 활동

0-to-1 개발 (Greenfield)	처음부터 생성	• 초기 사양 작성<br>• 기술 스택 선택<br>• 프로토타입 구축
창의적 탐색	병렬 구현	• 여러 기술 스택 실험<br>• 대안 탐색<br>• 최적 솔루션 선택
반복적 개선 (Brownfield)	기존 코드 현대화	• 기능 추가/수정<br>• 리팩토링<br>• 업그레이드

📁 프로젝트 구조

프로젝트/
├── memory/
│   ├── constitution.md          # 프로젝트 원칙
│   └── constitution_update_checklist.md
├── scripts/
│   ├── create-new-feature.sh   # 새 기능 생성
│   ├── setup-plan.sh           # 계획 설정
│   └── update-claude-md.sh     # 문서 업데이트
├── specs/
│   └── 001-기능명/
│       ├── spec.md             # 사양 문서
│       ├── plan.md             # 구현 계획
│       ├── data-model.md       # 데이터 모델
│       ├── contracts/          # API 계약
│       └── research.md         # 기술 조사
└── templates/                  # 템플릿 파일들

✅ 모범 사례

1. 사양 작성 시
   • 가능한 한 명확하고 구체적으로 작성
   • "무엇"과 "왜"에 집중 (기술적 세부사항 X)
   • 사용자 관점에서 기능 설명
2. 계획 수립 시
   • 조직의 제약사항 고려 (클라우드, 기술 스택)
   • 과도한 엔지니어링 방지
   • Constitution 원칙 준수
3. 구현 시
   • 점진적 개선 접근
   • 체크리스트 활용한 검증
   • 병렬 연구 작업 활용
4. 반복 개선
   • 리뷰 & 승인 체크리스트 검증
   • 피드백 즉시 반영
   • 지속적인 문서 업데이트

오류가 발생했을 때는 특별한 명령어 없이 그냥 AI 에이전트에게 직접 오류를 보고하고 수정을 요청하면 됩니다.

📌 명령어별 사용 시점

/specify - 새로운 기능 정의할 때만

# ❌ 잘못된 사용
/specify 드래그앤드롭 오류를 수정해줘

# ✅ 올바른 사용
/specify 사용자 프로필 관리 기능을 추가해줘. 
프로필 사진 업로드와 개인정보 수정이 가능해야 해.

/plan - 기술 계획 수립할 때만

# ❌ 잘못된 사용
/plan API 오류를 고쳐줘

# ✅ 올바른 사용
/plan React에서 Next.js로 마이그레이션하자. 
SSR을 활용하고 Vercel에 배포할 예정이야.

/tasks - 작업 목록 생성할 때만

# ✅ 새로운 기능의 구현 작업 나열
/tasks 프로필 기능 구현을 위한 작업 목록을 만들어줘

🔧 오류 수정 요청 방법

직접 요청 (명령어 없이)

# ✅ 빌드 오류
"npm run build 실행 시 다음 오류 발생:
Module not found: Can't resolve '@/components/TaskCard'
이 문제 해결해줘"

# ✅ 런타임 오류
"드래그앤드롭할 때 카드가 사라져. 
브라우저 콘솔에 이런 오류가 나와:
Uncaught TypeError: Cannot read property 'dragEnd' of undefined
수정해줘"

# ✅ 로직 오류
"댓글을 수정하면 다른 사용자 이름으로 저장돼. 
현재 로그인한 사용자 정보가 제대로 전달되지 않는 것 같아. 
확인하고 수정해줘"

# ✅ UI/UX 문제
"칸반 보드의 칼럼이 화면 밖으로 넘어가서 
가로 스크롤이 생겨. 반응형으로 수정해줘"

💡 효율적인 오류 수정 워크플로우

1. 오류 발견
   "태스크 삭제 버튼이 작동하지 않아"

2. 원인 분석 요청
   "왜 작동하지 않는지 코드를 확인해봐"

3. 수정 요청
   "문제를 수정해줘"

4. 테스트 요청
   "수정한 후 제대로 작동하는지 테스트해봐"

5. 관련 기능 점검
   "삭제 기능과 연관된 다른 부분도 확인해줘"

🎯 요약

상황 사용 방법 예시

새 기능 추가	/specify 사용	/specify 알림 기능 추가
기술 스택 변경	/plan 사용	/plan PostgreSQL을 MySQL로 변경
오류 수정	직접 요청	"로그인 오류 수정해줘"
버그 수정	직접 요청	"이 버그 고쳐줘: [오류 내용]"
코드 개선	직접 요청	"이 함수를 리팩토링해줘"
성능 최적화	직접 요청	"페이지 로딩 속도를 개선해줘"

📝 실제 대화 예시

You: "사용자가 자기 댓글이 아닌데도 수정 버튼이 보여. 
     현재 로그인한 사용자 ID와 댓글 작성자 ID를 
     비교하는 로직을 확인하고 수정해줘"

AI: "네, 확인해보니 TaskCard.js의 85번 줄에서 
    사용자 ID 비교 로직에 문제가 있네요. 
    수정하겠습니다... [코드 수정]"

You: "수정 후 테스트해봐"

AI: "테스트 완료했습니다. 이제 본인 댓글만 
    수정 버튼이 표시됩니다."

핵심: /specify, /plan, /tasks는 새로운 것을 만들 때만 사용하고, 기존 코드의 오류나 버그 수정은 평범한 대화로 요청하면 됩니다!