spec-driven development로 doom-prompting loop 깨기
Source: Dev.to
AI‑지원 코딩에 소프트웨어 엔지니어링 규율을 도입하기
AI 코딩 도구를 사용하는 모든 개발자는 다음과 같은 루프를 경험했습니다: 프롬프트를 입력하고, AI가 코드를 생성하고, 뭔가가 조금 잘못됐고, 다시 프롬프트를 입력하고, AI가 첫 번째 문제를 고치면서 또 다른 문제를 일으키고, 또 다시 프롬프트를 입력한다. 한 시간 뒤면 시작할 때보다 더 깊은 구렁텅이에 빠져, 현재는 doomprompting이라고 불리는 상황에 빠지게 됩니다.
이는 vibe coding이라는, Andrej Karpathy가 만든 AI‑생성 코드를 완전히 이해하지 못한 채 그대로 받아들이는 행위의 어두운 면입니다. Karpathy 자신도 이것이 “버려도 되는 주말 프로젝트에는 크게 나쁘지 않다”고 언급했습니다. 하지만 좀 더 실질적인 작업에 적용하면 이 접근 방식은 곧 무너집니다.
저는 spec‑kit, GitHub의 사양‑주도 개발 툴킷을 사용해 왔으며, 이것이 AI‑지원 코딩에 대한 제 사고 방식을 바꾸어 놓았습니다. 핵심 통찰은 간단합니다: 사양에서 문제를 잡는 것이 코드에서 문제를 잡는 것보다 훨씬 비용이 적게 듭니다.
AI 코딩에 적용된 shift‑left 원칙
Shift‑left 테스트는 개발 초기에 결함을 잡는 것이 나중에 잡는 것보다 비용이 적게 든다는 아이디어입니다. 프로덕션 이슈를 디버깅해 본 사람이라면 직관적으로 알 수 있습니다: 요구사항 단계에서 문제를 찾는 비용은 거의 없고, 코드 리뷰 단계에서는 약간의 재작업이 필요하며, 프로덕션 단계에서는 훨씬 큰 비용이 듭니다.
Spec‑kit은 이 원칙을 AI‑지원 개발에 적용하면서, 심지어 더 왼쪽으로 이동합니다. 코드를 테스트해서 문제를 잡는 대신, 사양을 검토해서 문제를 잡는 것이죠. 네 단계 워크플로우가 이를 명확히 보여줍니다: Specify → Plan → Tasks → Implement. 각 단계마다 진행하기 전에 검토하는 게이트가 있습니다.
이는 정식 소프트웨어 엔지니어링을 공부한 사람에게는 익숙하게 느껴집니다. 대학 프로젝트에서 우리는 종종 코드를 한 줄도 쓰기 전에 사양과 아키텍처에 몇 주를 투자했습니다. 당시엔 과도하게 느껴졌지만, 실제 코딩 단계는 놀라울 정도로 매끄러웠습니다. Spec‑kit은 AI‑지원 개발에 동일한 엄격함을 가져다 줍니다.
spec‑kit이 실제로 제공하는 것
이 툴킷은 에이전트에 구애받지 않으며 Claude Code, GitHub Copilot, Cursor 등 다양한 AI 코딩 도구와 함께 사용할 수 있습니다. 핵심은 구조화된 단계들을 안내하는 슬래시 명령어 집합입니다:
/specify– 무엇을 만들고 있는지 명확히 표현하도록 강제합니다./plan– 조사와 기술 방향을 생성합니다./tasks– 계획을 구체적인 구현 단계로 나눕니다./implement– 해당 작업들을 실행합니다.
각 단계는 문서와 AI 컨텍스트 역할을 하는 Markdown 파일을 생성합니다. 사양, 계획, 작업 목록은 세션 간에 지속되어 AI가 사용자의 의도에 맞게 정렬되도록 하는 메모리 역할을 합니다.
Spec‑kit은 또한 프로젝트 전반에 적용되는 교차 규칙을 정의하는 “constitution”(또는 “principles”) 파일을 도입합니다: 테스트 접근 방식, 코딩 표준, 아키텍처 제약 등. 이러한 비기능 요구사항은 AI가 생성하는 모든 것에 적용됩니다.
일상 업무 흐름의 변화
Spec‑kit을 사용한 제 워크플로우는 전형적인 AI 코딩 루프와 다릅니다. 저는 사양과 작업 목록을 검토·편집하는 데 시간을 투자하고, 그 뒤에 AI가 전체 기능을 구현하도록 합니다. AI를 페어 프로그래머라기보다 작업을 위임받은 개발자로 대합니다. 결과 코드는 인간 팀원의 풀 리퀘스트를 검토하듯 검토합니다.
이 사고 모델이 중요합니다. 페어 프로그래밍에서는 모든 키 입력을 지켜보지만, 위임에서는 사양에 맞는 결과물을 검토합니다. 후자는 AI가 상당한 규모의 기능을 자율적으로 구현할 수 있을 때 더 잘 확장됩니다.
plan 단계가 가장 가치 있게 변했습니다. AI가 기술 방향에 대해 조사하고, 저는 그 과정에서 새로운 것을 배우곤 합니다. 더 중요한 것은 오해를 초기에 잡아낼 수 있다는 점입니다. 한 프로젝트에서는 AI가 IBM Cloud 서버리스 서비스를 VPC에 배포한다고 가정했는데, 이는 나중에 발견되었다면 훨씬 큰 비용이 들었을 상황이었습니다.
이제 모든 코드 변경을 일일이 검토하지 않습니다. 대신 다음과 같이 진행합니다:
- 사양을 꼼꼼히 검토한다.
- 자동 수락(auto‑accept) 상태로 구현을 실행한다.
- 스모크 테스트를 수행한다.
- 전체 변경 세트를 검토한다.
문제가 발생하면 코드 수정에 바로 뛰어들기보다 전체 흐름(plan → tasks → implementation)을 다시 반복합니다. 이렇게 하면 사양이 실제 구축된 내용과 일치하도록 정확히 유지됩니다.
오버헤드에 대한 질문
Spec‑kit은 오버헤드를 추가합니다. 간단한 작업에 대해서는 그 오버헤드가 가치가 없을 수도 있습니다.
하지만 큰 기능일수록 투자가 회수됩니다. 사양을 작성하면서 요구사항을 제대로 고민하게 되고, 아키텍처 문제는 코드에 투자하기 전에 plan 검토 단계에서 드러납니다. 또한 사양 단계에서 모호함을 해소하기 때문에 doom‑prompting 루프를 피할 수 있습니다.
Spec‑kit을 사용할 때 토큰 사용량이 늘어납니다—코드를 작성하기 전에 사양, 계획, 작업 목록을 생성하기 때문이죠. 하지만 이러한 토큰은 진행이 안 되는 무한 프롬프트를 방지함으로써 스스로 상쇄됩니다.
프롬프트 기반 흐름 vs. 코드 파이프라인
Spec‑kit 설계에서 놀랐던 점은, 초기에는 전통적인 프로그래밍 언어와 명시적 제어 흐름으로 대부분의 워크플로우를 구현하려 했다는 것입니다. 대신 Spec‑kit은 최소한의 지원 스크립트와 상세 프롬프트로 흐름을 캡슐화합니다.
최신 모델(frontier models)과 잘 맞습니다. 프롬프트가 자연어로 단계들을 설명하고, AI가 이를 신뢰성 있게 따릅니다. 게이트가 있는 템플릿 방식은 LangGraph와 같은 코드 기반 오케스트레이션 노드 없이도 결정론적인 결과를 제공합니다.
비‑최신 모델은 복잡하고 다단계 지시를 따르는 능력이 부족해 신뢰성이 떨어질 것이라 예상합니다.
모델 외에도 각 AI 어시스턴트가 제공하는 도구가 중요합니다. plan 단계는 웹 검색, 코드베이스 검색, 기타 조사 기능에 크게 의존합니다. Claude Code는 이러한 기능을 기본 제공하며, 깊이 있는 검색을 통해 철저한 조사를 지원합니다. 다른 어시스턴트는 일부 기능이 부족할 수 있고, 조사 도구가 제한될 때 plan 품질에 가장 큰 차이가 나타났습니다.
MCP 도구를 흐름에 앞서 설정하면 결과가 개선됩니다. 예를 들어 Terraform 모듈 레지스트리 검색과 클라우드 공급자 문서 조회를 위한 도구를 미리 구성하면 AI가 더 풍부한 계획을 생성합니다.
인프라스트럭처 코드(IaC) 적용
처음 spec‑kit을 사용할 때는 IaC에도 바로 적용될 것이라 생각했습니다. 진행하면서 IaC는 다음과 같은 특수성을 가지고 있어 별도의 처리가 필요함을 깨달았습니다:
- Terraform 같은 도구의 선언적 특성.
- 클라우드‑중립 요구사항과 공급자‑특정 구현을 구분할 필요.
- 애플리케이션 코드와는 다른 보안·비용 거버넌스 요구.
- 실제 클라우드 공급자 API와 모듈 레지스트리를 통한 검증.
이를 해결하기 위해 iac‑spec‑kit을 만들고 오픈소스로 공개했습니다. 이 프로젝트는 spec‑kit 워크플로우에 IaC‑전용 컨벤션과 검증 단계를 추가해 Terraform, CloudFormation 등과 같은 도구에 실용적으로 적용할 수 있게 합니다.