Specification-Driven Development, SDD

https://github.com/github/spec-kit/blob/main/spec-driven.md

권력의 역전

수십 년 동안 코드는 왕이었습니다. 사양은 코드에 봉사했으며, “진짜 작업”인 코딩이 시작되면 버려지는 비계에 불과했습니다. 우리는 개발을 안내하기 위해 PRD를 작성하고, 구현을 알리기 위해 설계 문서를 만들고, 아키텍처를 시각화하기 위해 다이어그램을 그렸습니다. 그러나 이 모든 것은 항상 코드 자체에 종속적이었습니다. 코드는 진실이었습니다. 그 외의 모든 것은 기껏해야 좋은 의도에 불과했습니다. 코드는 진실의 원천이었고, 코드가 앞으로 나아가면서 사양은 좀처럼 따라가지 못했습니다. 자산(코드)과 구현이 하나이기 때문에, 코드를 기반으로 병렬 구현을 갖는 것은 쉽지 않습니다.

사양 주도 개발(SDD)은 이 권력 구조를 뒤집습니다. 사양이 코드를 위해 존재하는 것이 아니라, 코드가 사양을 위해 존재합니다. PRD(제품 요구사항 문서-사양)는 구현을 위한 안내서가 아니라, 구현을 생성하는 원천입니다. 기술 계획은 코딩을 알리는 문서가 아니라, 코드를 생성하는 정밀한 정의입니다. 이것은 소프트웨어를 만드는 방식에 대한 점진적 개선이 아닙니다. 무엇이 개발을 이끄는지에 대한 근본적인 재고입니다.

사양과 구현 사이의 간극은 소프트웨어 개발의 시작부터 문제였습니다. 우리는 더 나은 문서화, 더 상세한 요구사항, 더 엄격한 프로세스로 이 간극을 메우려 했습니다. 하지만 이런 접근법은 간극을 불가피한 것으로 받아들입니다. 간극을 좁히려 할 뿐, 결코 없애지 못합니다. SDD는 사양과 그로부터 파생된 구체적 구현 계획이 실행 가능해짐으로써 이 간극을 없앱니다. 사양에서 구현 계획으로, 그리고 코드로 생성이 이루어질 때, 간극은 존재하지 않습니다. 오직 변환만 있을 뿐입니다.

이러한 변환이 이제 가능해진 것은 AI가 복잡한 사양을 이해하고 구현 계획을 만들며, 상세한 구현 계획을 생성할 수 있게 되었기 때문입니다. 하지만 구조 없는 AI 생성은 혼란을 초래합니다. SDD는 사양과 그에 따른 구현 계획을 통해 구조를 제공합니다. 이들은 충분히 정밀하고 완전하며 모호함이 없어야 실제로 동작하는 시스템을 생성할 수 있습니다. 사양이 주된 산출물이 되고, 코드는 특정 언어와 프레임워크에서의 표현(구현 계획에서 파생된 구현)입니다.

이 새로운 세계에서 소프트웨어 유지보수란 사양을 발전시키는 것입니다. 개발팀의 의도는 자연어(“의도 주도 개발(intent-driven development)”), 디자인 자산, 핵심 원칙, 기타 가이드라인으로 표현됩니다. 개발의 공통 언어는 더 높은 수준으로 이동하며, 코드는 마지막 단계의 접근 방식이 됩니다.

디버깅이란 잘못된 코드를 고치는 것이 아니라, 잘못된 코드를 생성하는 사양과 구현 계획을 고치는 것입니다. 리팩토링이란 명확성을 위해 구조를 재정비하는 것입니다. 전체 개발 워크플로우는 사양을 중심 진실로 재조직하며, 구현 계획과 코드는 지속적으로 재생성되는 산출물이 됩니다. 앱에 새로운 기능을 추가하거나 창의적으로 새로운 병렬 구현을 만드는 것도 사양을 다시 방문하고 새로운 구현 계획을 만드는 과정입니다. 이 과정은 0 -> 1, (1’, ..), 2, 3, N입니다.

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

SDD 워크플로우의 실제

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

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

이 사양 과정 전반에 걸쳐, 리서치 에이전트가 중요한 맥락을 수집합니다. 라이브러리 호환성, 성능 벤치마크, 보안 영향 등을 조사합니다. 조직의 제약 조건도 자동으로 발견되어 적용됩니다. 회사의 데이터베이스 표준, 인증 요구사항, 배포 정책 등이 모든 사양에 원활하게 통합됩니다.

PRD로부터 AI는 요구사항을 기술적 결정에 매핑하는 구현 계획을 생성합니다. 모든 기술 선택에는 문서화된 근거가 있습니다. 모든 아키텍처 결정은 특정 요구사항으로 추적됩니다. 이 과정 전반에 걸쳐, 일관성 검증이 지속적으로 품질을 개선합니다. AI는 사양의 모호함, 모순, 누락을 일회성 게이트가 아니라 지속적 개선의 일부로 분석합니다.

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

피드백 루프는 초기 개발을 넘어 확장됩니다. 운영 지표와 사고는 단순히 핫픽스를 유발하는 것이 아니라, 다음 재생성을 위한 사양을 업데이트합니다. 성능 병목은 새로운 비기능 요구사항이 되고, 보안 취약점은 모든 미래 생성에 영향을 미치는 제약이 됩니다. 사양, 구현, 운영 현실 간의 이 반복적 상호작용에서 진정한 이해가 생기고, 전통적 SDLC가 연속적 진화로 변모합니다.

SDD가 지금 중요한 이유

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

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

둘째, 소프트웨어 복잡성은 기하급수적으로 증가하고 있습니다. 현대 시스템은 수십 개의 서비스, 프레임워크, 의존성을 통합합니다. 이러한 모든 요소를 원래 의도와 일치시키는 수작업 프로세스는 점점 더 어려워집니다. SDD는 사양 기반 생성을 통해 체계적 정렬을 제공합니다. 프레임워크는 인간 중심이 아니라 AI 중심 지원을 제공하거나, 재사용 가능한 컴포넌트 중심으로 설계될 수 있습니다.

셋째, 변화의 속도가 가속화되고 있습니다. 요구사항은 그 어느 때보다 빠르게 변합니다. 피벗은 더 이상 예외가 아니라, 당연한 일입니다. 현대 제품 개발은 사용자 피드백, 시장 상황, 경쟁 압력에 기반한 빠른 반복을 요구합니다. 전통적 개발은 이러한 변화를 혼란으로 간주합니다. 각 피벗은 문서, 설계, 코드 전반에 수동으로 변경을 전파해야 합니다. 그 결과는 속도를 제한하는 느리고 신중한 업데이트이거나, 기술 부채가 쌓이는 빠르고 무모한 변경입니다.

SDD는 “만약 비즈니스 요구로 티셔츠를 더 많이 팔기 위해 애플리케이션을 다시 구현하거나 변경해야 한다면, 어떻게 구현하고 실험할 것인가?“와 같은 가상/시뮬레이션 실험을 지원할 수 있습니다.

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

핵심 원칙

사양을 공통 언어로: 사양이 주된 산출물이 됩니다. 코드는 특정 언어와 프레임워크에서의 표현입니다. 소프트웨어 유지보수란 사양을 발전시키는 것입니다.

실행 가능한 사양: 사양은 실제로 동작하는 시스템을 생성할 만큼 정밀하고 완전하며 모호함이 없어야 합니다. 이는 의도와 구현 사이의 간극을 없앱니다.

지속적 개선: 일관성 검증은 일회성 게이트가 아니라, 지속적으로 이루어집니다. AI는 사양의 모호함, 모순, 누락을 지속적으로 분석합니다.

리서치 기반 맥락: 리서치 에이전트가 사양 과정 전반에 걸쳐 기술적 옵션, 성능 영향, 조직적 제약을 조사합니다.

양방향 피드백: 운영 현실이 사양 진화에 반영됩니다. 지표, 사고, 운영 경험이 사양 개선의 입력이 됩니다.

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

구현 접근법

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

반복적 사양 개발을 위한 AI 어시스턴트
기술적 맥락 수집을 위한 리서치 에이전트
사양을 구현으로 변환하는 코드 생성 도구
사양 우선 워크플로우에 맞춘 버전 관리 시스템
사양 문서의 AI 기반 일관성 검사

핵심은 사양을 진실의 원천으로 취급하고, 코드는 사양을 위해 생성되는 산출물로 다루는 것입니다.

Claude 명령어로 SDD 간소화

SDD 방법론은 사양 및 계획 워크플로우를 자동화하는 두 가지 강력한 Claude 명령어로 크게 향상됩니다.

`‎⁠new_feature⁠` 명령어

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

자동 기능 번호 부여: 기존 사양을 스캔하여 다음 기능 번호(예: 001, 002, 003)를 결정합니다.
브랜치 생성: 설명에서 의미 있는 브랜치 이름을 생성하고 자동으로 만듭니다.
템플릿 기반 생성: 기능 사양 템플릿을 복사해 요구사항에 맞게 맞춤화합니다.
디렉터리 구조: 모든 관련 문서를 위한 ‎⁠specs/[branch-name]/⁠ 구조를 생성합니다.

`‎⁠generate_plan⁠` 명령어

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

사양 분석: 기능 요구사항, 사용자 스토리, 수용 기준을 읽고 이해합니다.
헌법 준수: 프로젝트 헌법과 아키텍처 원칙과의 정렬을 보장합니다.
기술적 번역: 비즈니스 요구사항을 기술 아키텍처 및 구현 세부사항으로 변환합니다.
상세 문서화: 데이터 모델, API 계약, 테스트 시나리오에 대한 지원 문서를 생성합니다.
수동 테스트 계획: 각 사용자 스토리에 대한 단계별 검증 절차를 만듭니다.

예시: 채팅 기능 구축

이 명령어들이 전통적 개발 워크플로우를 어떻게 변화시키는지 살펴보겠습니다.

전통적 접근법:

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

SDD 명령어 접근법:

# 1단계: 기능 사양 생성(5분)
/new_feature 실시간 채팅 시스템(메시지 기록 및 사용자 존재감 포함)

# 자동으로 수행:
# - 브랜치 "003-chat-system" 생성
# - specs/003-chat-system/feature-spec.md 생성
# - 구조화된 요구사항으로 채움

# 2단계: 구현 계획 생성(10분)
/generate_plan 실시간 메시징용 WebSocket, 기록용 PostgreSQL, 존재감용 Redis

# 자동으로 생성:
# - specs/003-chat-system/implementation-plan.md
# - specs/003-chat-system/implementation-details/
#   - 00-research.md(WebSocket 라이브러리 비교)
#   - 02-data-model.md(메시지 및 사용자 스키마)
#   - 03-api-contracts.md(WebSocket 이벤트, REST 엔드포인트)
#   - 06-contract-tests.md(메시지 흐름 시나리오)
#   - 08-inter-library-tests.md(데이터베이스-WebSocket 통합)
# - specs/003-chat-system/manual-testing.md

15분 만에 다음이 준비됩니다.

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

구조화된 자동화의 힘

이 명령어들은 단순히 시간을 절약하는 것이 아니라, 일관성과 완전성을 보장합니다.

누락 없는 세부사항: 템플릿이 비기능 요구사항부터 오류 처리까지 모든 측면을 고려하게 합니다.
추적 가능한 결정: 모든 기술적 선택이 특정 요구사항으로 연결됩니다.
살아있는 문서화: 사양이 코드를 생성하므로 항상 동기화됩니다.
빠른 반복: 요구사항을 변경하고, 계획을 몇 분 만에 재생성할 수 있습니다.

이 명령어들은 사양을 실행 가능한 산출물로 취급함으로써 SDD 원칙을 구현합니다. 사양 과정을 필수 악이 아니라, 개발을 이끄는 힘으로 전환합니다.

템플릿 기반 품질: 구조가 LLM의 결과를 어떻게 개선하는가

이 명령어의 진정한 힘은 자동화뿐 아니라, 템플릿이 LLM의 행동을 더 높은 품질의 사양으로 유도하는 데 있습니다. 템플릿은 LLM의 출력을 생산적으로 제한하는 정교한 프롬프트 역할을 합니다.

1. 성급한 구현 세부사항 방지

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

- ✅ 사용자가 무엇을 필요로 하고, 왜 필요한지에 집중
- ❌ 구현 방법(기술 스택, API, 코드 구조) 언급 금지

이 제약은 LLM이 적절한 추상화 수준을 유지하게 합니다. LLM이 “React와 Redux로 구현”이라고 자연스럽게 말하고 싶을 때, 템플릿은 “사용자는 데이터의 실시간 업데이트가 필요하다”에 집중하게 만듭니다. 이 분리는 구현 기술이 바뀌어도 사양이 안정적으로 유지되도록 합니다.

2. 명시적 불확실성 표시 강제

두 템플릿 모두 ‎⁠[NEEDS CLARIFICATION]⁠ 표시를 의무화합니다. 이 사양을 사용자 프롬프트로 생성할 때:

1. **모든 모호함 표시**: [NEEDS CLARIFICATION: 구체적 질문] 사용
2. **추측 금지**: 프롬프트에 명시되지 않은 것은 표시

이는 LLM이 그럴듯하지만 잘못된 추측을 하는 것을 방지합니다. 예를 들어 “로그인 시스템”이 이메일/비밀번호 인증을 쓴다고 추측하는 대신, ‎⁠[NEEDS CLARIFICATION: 인증 방식 미지정 - 이메일/비밀번호, SSO, OAuth?]⁠로 표시해야 합니다.

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

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

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

이 체크리스트는 LLM이 체계적으로 출력을 자체 검토하게 하여, 놓칠 수 있는 부분을 잡아냅니다. 일종의 품질 보증 프레임워크입니다.

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

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

### -1단계: 사전 구현 게이트
#### 단순성 게이트(제7조)
- [ ] 3개 이하 프로젝트 사용?
- [ ] 미래 대비 설계 없음?
#### 반추상화 게이트(제8조)
- [ ] 프레임워크 직접 사용?
- [ ] 단일 모델 표현?

이 게이트는 LLM이 모든 복잡성을 명시적으로 정당화하게 만듭니다. 게이트를 통과하지 못하면, “복잡성 추적” 섹션에 그 이유를 문서화해야 합니다.

5. 계층적 세부사항 관리

템플릿은 적절한 정보 구조를 강제합니다.

**중요**: 이 구현 계획은 고수준이고 읽기 쉬워야 합니다.
코드 샘플, 상세 알고리즘, 방대한 기술 사양은 반드시 `implementation-details/` 파일에 별도로 작성해야 합니다.

이는 사양이 읽기 어려운 코드 덤프로 변하는 문제를 방지합니다. LLM은 주요 문서는 읽기 쉽게 유지하고, 복잡성은 별도 파일로 분리하는 법을 배웁니다.

6. 테스트 우선 사고

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

### 파일 생성 순서
1. API 사양이 담긴 `contracts/` 생성
2. 테스트 파일 생성 순서: 계약 → 통합 → e2e → 단위
3. 테스트를 통과시키기 위해 소스 파일 생성

이 순서 제약은 LLM이 구현보다 테스트 가능성과 계약을 먼저 생각하게 하여, 더 견고하고 검증 가능한 사양을 만듭니다.

7. 추측성 기능 방지

템플릿은 추측을 명시적으로 금지합니다.

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

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

복합 효과

이 제약들은 다음과 같은 사양을 만들어냅니다.

완전함: 체크리스트로 누락 방지
모호하지 않음: 명확화 표시로 불확실성 강조
테스트 가능: 테스트 우선 사고 내재화
유지보수 용이: 적절한 추상화와 정보 구조
구현 가능: 명확한 단계와 구체적 산출물

템플릿은 LLM을 창의적 작가에서 규율 있는 사양 엔지니어로 변화시켜, 일관되고 고품질의 실행 가능한 사양을 생성하게 합니다.

헌법적 기반: 아키텍처 규율의 강제

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

개발의 9개 조항

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

제1조: 라이브러리 우선 원칙

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

Specify의 모든 기능은 반드시 독립형 라이브러리로 시작해야 한다.
애플리케이션 코드 내에서 직접 구현되는 기능은
반드시 재사용 가능한 라이브러리 컴포넌트로 추상화되어야 한다.

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

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

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

모든 CLI 인터페이스는 반드시:
- 텍스트 입력을 받아야 함(stdin, 인자, 파일)
- 텍스트 출력을 생성해야 함(stdout)
- 구조화된 데이터 교환을 위해 JSON 형식 지원

이는 가시성과 테스트 가능성을 보장합니다. LLM은 기능을 불투명한 클래스 내부에 숨길 수 없으며, 모든 것은 텍스트 기반 인터페이스로 접근·검증 가능해야 합니다.

제3조: 테스트 우선 원칙

가장 변혁적인 조항—코드보다 테스트가 먼저입니다.

이 조항은 타협 불가: 모든 구현은 엄격한 테스트 주도 개발을 따라야 한다.
구현 코드를 작성하기 전에 반드시:
1. 단위 테스트 작성
2. 테스트가 사용자에 의해 검증 및 승인됨
3. 테스트가 실패함(Red 단계) 확인

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

제7·8조: 단순성 및 반추상화

이 쌍의 조항은 과도한 엔지니어링을 방지합니다.

7.3절: 최소 프로젝트 구조
- 초기 구현에 최대 3개 프로젝트
- 추가 프로젝트는 문서화된 근거 필요

8.1절: 프레임워크 신뢰
- 프레임워크 기능을 직접 사용

LLM이 복잡한 추상화를 만들고 싶을 때, 이 조항은 모든 계층의 복잡성을 정당화하게 만듭니다. 구현 계획 템플릿의 “사전 구현 게이트”가 이 원칙을 직접 강제합니다.

제9조: 통합 우선 테스트

고립된 단위 테스트보다 실제 환경 테스트를 우선시합니다.

테스트는 반드시 현실적인 환경을 사용해야 한다.
- 모의(mock) 대신 실제 데이터베이스 선호
- 스텁 대신 실제 서비스 인스턴스 사용
- 구현 전 계약 테스트 필수

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

템플릿을 통한 헌법 강제

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

### -1단계: 사전 구현 게이트
#### 단순성 게이트(제7조)
- [ ] 3개 이하 프로젝트 사용?
- [ ] 미래 대비 설계 없음?

#### 반추상화 게이트(제8조)
- [ ] 프레임워크 직접 사용?
- [ ] 단일 모델 표현?

#### 통합 우선 게이트(제9조)
- [ ] 계약 정의됨?
- [ ] 계약 테스트 작성됨?

이 게이트는 아키텍처 원칙의 컴파일 타임 체크 역할을 합니다. LLM은 게이트를 통과하거나, “복잡성 추적” 섹션에 정당한 예외를 문서화하지 않으면 진행할 수 없습니다.

불변 원칙의 힘

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

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

헌법의 진화

원칙은 불변이지만, 적용 방식은 진화할 수 있습니다.

4.2절: 개정 절차
이 헌법의 수정에는 반드시:
- 변경 근거의 명시적 문서화
- 프로젝트 유지관리자의 검토 및 승인
- 하위 호환성 평가

이는 방법론이 현실 경험에 따라 학습·개선되면서도 안정성을 유지할 수 있게 합니다. 헌법은 자체 개정 이력을 날짜와 함께 보여주며, 원칙이 실제 경험에 따라 어떻게 정제될 수 있는지 시연합니다.

규칙을 넘어: 개발 철학

헌법은 단순한 규칙집이 아니라, LLM이 코드 생성을 사고하는 방식을 형성하는 철학입니다.

가시성 우선: 모든 것은 CLI 인터페이스로 검사 가능해야 함
단순성 우선: 처음에는 단순하게, 필요가 입증될 때만 복잡성 추가
통합 우선: 인위적 환경이 아니라 실제 환경에서 테스트
모듈성 우선: 모든 기능은 명확한 경계의 라이브러리

이 원칙을 사양 및 계획 과정에 내재화함으로써, SDD는 생성된 코드가 단순히 동작하는 것에 그치지 않고, 유지보수 가능하고, 테스트 가능하며, 아키텍처적으로 건전하도록 보장합니다. 헌법은 AI를 코드 생성기에서 시스템 설계 원칙을 존중하고 강화하는 아키텍처 파트너로 변화시킵니다.

변화

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

소프트웨어 개발에는 의도와 구현의 정렬을 유지할 더 나은 도구가 필요합니다. SDD는 사양이 코드를 단순히 안내하는 것이 아니라, 코드를 생성함으로써 이 정렬을 달성하는 방법론을 제공합니다.