명세 기반 개발(Spec-Driven Development, SDD)을 통한 AI 드리프트 해결하기

현대의 AI 보조 개발 워크플로우는 종종 '전화기 게임(game of telephone)'처럼 느껴지곤 합니다. Claude Code에게 기능을 구현해 달라고 요청했지만, Cursor가 그 결과로 나온 코드를 다르게 해석하고, GitHub Copilot이 정리 과정에서 세 번째의 모순된 해석을 도입하는 상황을 겪을 수 있습니다. 이러한 현상은 'AI 드리프트(AI drift)'라고 불리며, 각 에이전트가 자신만의 가설을 바탕으로 작동하고 프로젝트의 논리적 공백을 자신의 내부적 환각(hallucination)으로 채우기 때문에 발생합니다.

명세 기반 개발(Spec-Driven Development, SDD)은 공유된 진실의 원천(shared source of truth)을 구축함으로써 이러한 드리프트를 제거하도록 설계된 프레임워크입니다. AI 에이전트가 코드 한 줄을 작성하기 전에 공식적인 명세를 작성하고 이를 준수하도록 강제함으로써, SDD는 스택 내의 모든 도구가 동일한 플레이북을 읽고 있음을 보장합니다.

핵심 아키텍처: 진실의 세 가지 기둥

SDD 접근 방식의 핵심은 세 가지 근본적인 Markdown 파일의 생성에 있습니다. 이 파일들은 프로젝트의 헌법 역할을 하며, 모든 AI 에이전트는 행동을 취하기 전에 반드시 이를 참조해야 합니다:

requirements.md: 시스템이 무엇을 해야 하는지 정의합니다. 모든 기능이 추적 가능하도록 'shall' 언어와 고유한 요구사항 ID(예: REQ-001)를 사용합니다.
design.md: 시스템이 어떻게 구축될 것인지 정의합니다. 이는 데이터 모델, 아키텍처 및 구조적 결정을 다룹니다.
tasks.md: 원자적이고 순서가 정해진 구현 계획입니다. 각 작업은 요구사항 ID와 명시적으로 연결되어 있어, 목적 없는 코드가 작성되는 것을 방지합니다.

범용 지침 블록 (Universal Instruction Block, UIB)

다양한 도구 전반에 걸쳐 이러한 명세를 강제하기 위해, SDD는 '범용 지침 블록(Universal Instruction Block)'을 사용합니다. 이는 Cursor를 위한 .cursorrules, Claude Code를 위한 CLAUDE.md, 그리고 GitHub Copilot을 위한 .github/copilot-instructions.md를 포함한 다양한 AI 도구의 설정 파일에 주입되는 표준화된 명령 세트입니다.

이 블록은 AI 에이전트에게 강력한 제약을 가합니다:

필수 읽기: 에이전트는 어떤 행동을 취하기 전에 요구사항, 설계, 작업 파일을 전체적으로 읽어야 합니다.
엄격한 준수: 에이전트는 requirements.md에 나열되지 않은 요구사항을 구현하거나, design.md를 먼저 업데이트하지 않고 데이터 모델을 변경하는 것이 금지됩니다.
이탈 프로토콜: 만약 에이전트가 구현 과정에서 설계와 달라져야 한다고 판단할 경우, 즉시 중단하고 충돌 내용을 설명한 뒤, 명세를 업데이트하기 위해 사용자의 승인을 기다려야 합니다.

구현 및 리트로피팅(Retrofitting)

SDD 기술의 강점 중 하나는 프로젝트 생명주기 단계에서의 유연성입니다:

그린필드 프로젝트 (Greenfield Projects)

새로운 프로젝트의 경우, 이 기술은 사용자와 대화형 인터뷰를 진행하여 일련의 타겟 질문을 던지고, 이를 통해 초기 명세 파일을 처음부터 생성합니다.

기존 코드 리트로피팅 (Retrofitting Existing Code)

이미 구축된 코드베이스의 경우, 이 기술은 프로젝트의 현재 상태를 역공학하여 요구사항 및 설계 파일의 v0-retrofit 버전을 생성합니다. 추론된 필드는 [TO VERIFY]로 표시하여, 개발의 첫 단계를 기능 구현이 아닌 검증 과정으로 전환합니다.

엄격한 검증 및 CI

많은 프롬프트 기반 도구와 달리, SDD 기술은 자체적인 신뢰성을 보장하기 위해 포괄적인 테스트 스위트를 포함합니다. 이 프로젝트는 세 가지 단계에 걸쳐 130개의 어설션(assertion)을 제공합니다:

Phase 2A (정적 어설션): 생성된 파일의 구조적 무결성을 보장하기 위해 Python을 통해 64개의 체크를 실행합니다.
Phase 2B (행동 테스트): AI가 상호작용 중에 어떻게 행동하는지 검증하기 위해 13개의 라이브 세션 테스트를 수행합니다.
Phase 2C (생성 품질): 출력 품질이 시간이 지나도 일관되게 유지되도록 커밋된 픽스처(fixtures)와 비교하여 53개의 체크를 수행합니다.

이는 GitHub Actions 워크플로우에 통합되어, 기술이 발전함에 따라 기능이 퇴보하는 것을 방지하는 '하드 게이트(hard gate)' 역할을 합니다.

비판적 관점 및 고려 사항

SDD 프레임워크가 일관성을 위한 구조화된 경로를 제공하지만, community의 일부 개발자들은 확장성 및 기존 대안에 대해 중요한 지점을 제기했습니다.

컨텍스트 붕괴 (The Risk of Context Rot)

한 가지 우려 사항은 프로젝트가 커짐에 따라 requirements.md와 tasks.md 파일을 매우 크게 만들 수 있다는 점입니다. 커뮤니티 멤버들이 언급했듯이, 매우 큰 명세 파일은 '컨텍스트를 부패하게(rot your context)' 만들 수 있으며, 이는 시스템이 방지하고자 하는 바로 그 환각과 드리프트를 유발할 수 있습니다.

경쟁 환경

SDD는 AI 오케스트레이션 플러그인이라는 혼잡한 분야에 진입했습니다. 숙련된 사용자들은 superpowers, get-shit-done, 그리고 spec kit과 같은 더 성숙한 대안들을 언급하며, SDD 접근 방식이 규율 있는 방식이긴 하지만, 구조화된 AI 엔지니어링을을 향한 더 넓은 움직임의 일부임을 시사했습니다.

이러한 비판에도 불구하고, 초기 도입자들은 성공 사례를 보고하고 있습니다. 한 사용자는 SDD 접근 방식을 사용하여 스크래퍼 체크포인트 매니저 명세를 생성한 결과, 생성된 명세에 대한 엄격한 준수 덕분에 기존 로직보다 '상당한 개선'이 이루어졌다고 언급했습니다.