AI가 작성한 코드, 동작은 하지만 '뭔가 어긋나는' 이유 — Spec-Driven Development(仕様駆動開発)로 AI를 '설계도대로'

AI에게 코드를 작성하게 하는 것이 정말 빨라졌습니다.

"로그인 기능 넣어줘", "이 목록, 검색할 수 있게 해줘"와 같이 부탁하기만 하면, 수십 초 뒤에 그럴싸한 코드가 나옵니다. 처음에는 감동하게 되죠. 하지만 얼마간 사용하다 보면 이런 순간을 마주치지 않나요?

"동작은 한다. 하지만, 뭔가 다르다."

• 예상했던 동작과 미묘하게 어긋남
• 에러 처리(Error handling)가 내 프로젝트의 방식과 다름
• "그게 아니라..."라고 다시 설명하면, 이번에는 다른 부분이 무너짐
• 세 번 정도 대화를 주고받다 보면, 결국 그럴 바엔 직접 쓰는 게 빠르겠다는 생각이 듦

이것은 AI의 잘못이 아니라는 생각이 듭니다. 잘 생각해보면, 우리가 '무엇을 만들고 싶은지'를 제대로 전달하지 못했을 뿐입니다. 머릿속에 있는 완성형을 모호한 한마디로 던져놓고, 나머지는 AI가 독심술이라도 발휘해주길 바랐던 것이죠. 그러니 어긋날 수밖에 없습니다.

최근 이 "모호하게 던지고, 어긋나면 수정한다" 스타일을 부르는 적절한 명칭과 대책이 등장했습니다. 스타일 측면에서는 Vibe Coding(바이브 코딩), 대책 측면에서는 이 기사의 테마인 **Spec-Driven Development(仕様駆動開発, 이하 SDD)**입니다.

한마디로 말하자면, SDD는 다음과 같은 사고방식입니다.

코드를 작성하게 하기 전에 "사양(Specification, 즉 무엇을 만들 것인가)"을 먼저 작성한다. 그리고 그 사양을 "AI를 위한 설계도"로서 전달한다.

"사양서 같은 무거운 건 쓰기 싫은데..."라고 생각하신 분, 잠시만 기다려주세요. 여기서 말하는 사양은 두꺼운 Word 문서 같은 것이 아닙니다. 오히려 AI가 정확하게 동작하도록 만들기 위한 구조화된 메모에 가깝습니다. 그리고 이것이 2026년 AI 개발에서 가장 뜨거운 테마 중 하나가 되고 있습니다.

이 기사에서는,

• 왜 지금 사양을 먼저 작성해야 하는가 (Vibe Coding의 한계)
• SDD의 전체상 (어려운 용어는 모두 쉽게 풀어서 설명합니다)
• 실제로 작성하는 사양 샘플 (그대로 복사해서 사용할 수 있는 것)
• GitHub Spec Kit / Amazon Kiro라는 실재하는 도구 이야기
• 그리고 가장 전하고 싶은 "
  사양을 '실행 가능(executable)'하게 만들기"

라는 단계까지, AI 개발에 아직 익숙하지 않은 사람도 뒤처지지 않도록 순서대로 이야기하겠습니다. 내일부터 업무에서 하나라도 시도해 볼 수 있는 수준까지 가져가 봅시다.

Vibe Coding은 악당이 아닙니다. 간단한 조사나 버릴 예정인 프로토타입이라면 느낌대로 던지는 것이 가장 빠릅니다. 문제는, 제대로 남겨야 하는 코드나 팀에서 다루는 코드에까지 그 느낌(Vibe)을 가져왔을 때 발생합니다. 대표적인 실패 사례가 세 가지 있다고 생각합니다.

실패 모드 ①: 사양이 프롬프트(Prompt)에 흩어져 사라짐

"아, 거기는 관리자만 편집할 수 있게 해줘", "금액은 부가세 포함으로 해줘"와 같은 중요한 결정 사항들을 채팅 도중에 툭툭 전달하곤 하죠. 그런데 그것들은 대화가 흘러가는 순간 사라집니다. 3일 뒤의 나도, 옆 팀 동료도 그 결정을 알지 못합니다. 사양이 AI와의 대화 로그의 바다 속에 가라앉아 있는 상태입니다.

실패 모드 ②: 드리프트(Drift, 사양과 코드의 어긋남)

처음에는 의도대로 잘 동작했는데, 계속해서 추가 및 수정을 반복하다 보면 어느샌가 원래 설계에서 조금씩 벗어나게 됩니다. 이를 **드리프트(Drift, 표류)**라고 합니다. 하나하나의 어긋남은 작더라도, 이것이 쌓이면 "동작은 하지만 아무도 전체상을 설명할 수 없는 코드"가 만들어집니다. Amazon은 바로 이 문제를 지목하며 "구조 없이 AI에게 만들게 하면, 로컬에서는 동작하지만 아키텍처에서 드리프트하여 엣지 케이스(Edge case)를 놓치고, 운영 환경에서 무너진다"라고 말하고 있습니다.

실패 모드 ③: 리뷰할 수 없음

리뷰하는 입장에서는 "그래서, 이것은 결국 무엇을 충족해야 정답인가?"라는 기준(수락 조건, Acceptance criteria)이 어디에도 없습니다. 그래서 "동작하는 것 같으니 OK" 같은 감상 위주의 리뷰가 됩니다. 기준이 없는 곳에서는 제대로 된 리뷰가 태어날 수 없습니다.

이 세 가지의 뿌리는 같습니다. "무엇을 만드는가"가 AI에게도 인간에게도 제대로 남는 형태로 작성되지 않았다는 점입니다. SDD는 여기에 미리 손을 쓰자는 발상입니다.

흥미로운 점은, 이것이 개인의 의견 수준이 아니라 이미 대기업들이 진지하게 도구를 내놓고 있다는 사실입니다. 사실만을 나열하겠습니다.

GitHub Spec Kit… GitHub이 공개한 OSS 도구 키트(github/spec-kit). Constitution → Specify → Plan → Tasks → Implement

이러한 흐름으로 사양 주도 개발 (Spec-Driven Development, SDD)을 지원합니다. Copilot / Claude / Gemini / Codex / Windsurf / Kiro 등 30종류의 AI 에이전트와 연동할 수 있으며, 특정 도구에 종속(Lock-in)되지 않는 것이 특징입니다. -
Amazon Kiro… Amazon이 2026년 5월 7일에 국제 전개를 시작한 에이전트형 IDE (Code OSS = VS Code의 토대 위에 구축). 기존 Amazon Q Developer의 대체제로, "사양을 먼저 작성한 후 구현한다"를 핵심으로 삼고 있습니다.

즉, "AI에게 맡기는 시대이기에 더욱 설계의 작법이 중요해진다"는 방향으로 업계 전체가 키를 돌리기 시작했습니다. 구현이 빨라진 만큼, 병목 현상이 "무엇을 만들 것인가에 대한 설계와 합의"로 옮겨갔다고 생각합니다.

여기서 아키파파(あきらパパ)가 줄곧 중요하게 생각하는 사고방식과 연결됩니다. "무엇을 만들 것인가 (What)"와 "왜 만드는가 (Why)"를 생각하는 것은 인간, "어떻게 만드는가 (How)"를 수행하는 것은 AI. SDD는 이 역할 분담을 그대로 개발 플로우에 녹여낸 방법론입니다.

"사양"이라는 말이 딱딱하게 느껴질 뿐, 내용은 심플합니다. 요리에 비유하면 이해하기 쉽습니다.

즉흥 요리 (Vibe Coding): 냉장고를 열고 그 자리의 기분에 따라 만든다. 맛있을 때도 있지만, 같은 맛을 두 번 다시 만들 수 없고 타인이 재현할 수도 없다. -
레시피를 쓰고 나서 만든다 (SDD): 재료, 분량, 순서, "이렇게 되면 완성"이라는 기준을 먼저 적는다. 누가 만들어도 같은 맛이 나고 개선하기도 쉽다.

사양이란, 결국 **"완성되면 이렇게 되어 있어야 한다는 상태를 미리 글로 나타낸 것"**입니다. 그뿐입니다. SDD는 이 레시피를 먼저 작성하고, 조리(구현)를 AI에게 맡긴다는 발상입니다.

GitHub Spec Kit의 흐름을 따르면, SDD에서는 단계별로 4종류의 문서(산출물)를 만듭니다. 이를 의인화하면 다음과 같은 팀이 됩니다.

등장인물 (파일)	역할	한마디로 말하면
헌법 (constitution.md)	프로젝트의 절대 규칙	"우리 팀은 이런 방침으로 간다"라는 전체 헌법. 품질·테스트·설계 원칙
사양 (spec.md)	무엇을·왜 만드는가	유저 스토리와 수락 조건. How는 쓰지 않음 (What/Why만)
계획 (plan.md)	어떻게 만드는가	기술 스택·아키텍처·설계 판단
태스크 (tasks.md)	절차의 분해	구현 가능한 단위로 나눈 순서가 있는 To-Do 리스트

포인트는 이 4명이 위에서부터 순서대로 바통을 넘겨주는 것입니다. 헌법이 전체 전제를 정하고, 사양이 "무엇을" 확정하며, 계획이 "어떻게"를 결정하고, 태스크가 "절차"로 나눕니다. 그리고 마지막으로 구현 (Implement) 단계에서 AI가 태스크를 하나씩 해결해 나갑니다.

각 단계의 산출물이 다음 단계의 "AI에게 전달할 구조화된 문맥 (Context)"이 됩니다. 이 부분이 SDD의 핵심입니다. 모호한 한마디가 아니라 쌓아 올린 설계도를 전달하기 때문에 AI가 경로를 이탈하기 어렵습니다.

조금 추상적인 이야기를 해보겠습니다. 최근 자주 언급되는 **Context Engineering (문맥 설계)**라는 용어, SDD는 바로 이것의 실천판입니다.

Prompt Engineering… 기막힌 한마디 (프롬프트)를 짜내는 기술 -
Context Engineering… AI에게 전달할 "문맥 그 자체"를 설계하는 기술

단 한 번의 멋진 프롬프트로 승부하는 것이 아니라, 헌법·사양·계획·태스크라는 쌓아 올린 문맥을 준비하여 AI가 올바르게 움직일 수 있는 무대를 만드는 것. SDD는 "좋은 프롬프트를 쓰는 것"보다 한 단계 높은, "좋은 문맥을 구성하는" 접근법이라고 이해하시면 됩니다.

실제 흐름을 지도로 나타내면 다음과 같습니다. 각 페이즈에서 "인간이 결정할 것"과 "AI에게 맡길 것"을 명확히 나누는 것이 요령입니다.

페이즈	할 일	인간이 결정함	AI에게 맡김
① Constitution	프로젝트 헌법 만들기	품질·테스트·설계 원칙, 양보할 수 없는 방침	원칙의 문서화·누락 지적
...

중요한 것은 인간이 사라지는 것이 아니라는 점입니다. 오히려 인간은 더 상류 단계인 "의도", "합의", "판단"에 집중합니다. 손을 움직이는 양은 줄어들지만, 머리를 쓰는 곳이 바뀌는 것입니다. 구현자에서 설계자·평가자로 말이죠.

이제부터는 직접 손을 움직이는 파트입니다. 주제는 어느 프로젝트에나 있을 법한 **「태스크 관리 앱의 태스크 생성 API」**로 하겠습니다. 고유한 정보는 전혀 사용하지 않는 범용적인 더미(Dummy) 주제입니다. 그대로 복사해서 본인의 주제로 교체하여 사용하세요.

먼저 프로젝트의 '절대 규칙'입니다. 이것은 기능별로 작성하는 것이 아니라, 프로젝트 전체에 대해 한 번 작성하는 것입니다.

# 프로젝트 헌법 (constitution.md)
## 제1조: 품질의 원칙
- 모든 공개 API에는 정상계(Normal case)·이상계(Abnormal case) 자동 테스트를 반드시 포함한다
...

이것이 있으면 AI에게 "우리 헌법에 따라"라고 말하는 것만으로, 매번 테스트나 유효성 검사(Validation) 방침을 다시 설명할 필요가 없습니다. 팀의 암묵지(Tacit knowledge)를 명시적인 규칙으로 바꾸는 것입니다.

다음은 기능별 사양(Specification)입니다. 여기서는 「어떻게 구현할 것인가 (How)」는 일절 쓰지 않습니다. 어디까지나 「무엇을・왜・어떻게 되어야 완성인가」만을 작성합니다.

# 사양: 태스크 생성 API (spec.md)
## 목적 (Why)
사용자가 자신의 태스크를 등록할 수 있도록 한다. 등록된 태스크는
...

주목해야 할 점이 두 가지 있습니다.

첫 번째는 수락 조건(Acceptance Criteria)에 AC-1과 같은 번호를 부여하는 것입니다. 이것이 나중에 「테스트와의 대응(Traceability, 추적성)」에서 효과를 발휘합니다.

두 번째는 [NEEDS CLARIFICATION] 마커입니다. 사양을 쓰다 보면 반드시 "어라, 이 부분은 결정되지 않았네" 하는 부분이 나옵니다. 그것을 추측으로 채우지 않고,

「미확정」이라고 명시하며 멈추는 것. 이것이 정말 중요합니다. 모호한 상태로 구현에 들어가면, AI가 멋대로 편의에 맞게 해석하여 나중에 "그런 의도가 아니었다"라는 상황이 발생합니다. 모호함은 구현보다 앞서서 제거해야 합니다.

사양이 OK가 된 후에야 비로소 「어떻게 만들 것인가」를 생각합니다.

# 계획: 태스크 생성 API (plan.md)
## 기술 스택
- 언어/FW: TypeScript + Express
...

여기서 [NEEDS CLARIFICATION]이 남아 있다면, 본래 계획 단계로 넘어가서는 안 됩니다. Spec Kit에는 plan 단계 전에 모호함을 제거하는 /speckit.clarify라는 전용 단계가 있을 정도로 이 부분을 중요하게 여깁니다.

마지막으로, 계획을 「순서가 있는 작업 목록」으로 분해합니다. AI가 하나씩 처리할 수 있는 입도(Granularity)로 만드는 것이 요령입니다.

# 태스크 분해 (tasks.md)
## 전제
- 각 태스크는 「테스트를 먼저 작성한다 (TDD)」 순서로 나열한다
...

여기까지 오면 AI에게 전달하는 것은 "로그인 기능 만들어줘"가 아니라, 헌법＋사양＋계획＋태스크라는, 차곡차곡 쌓인 설계도가 됩니다. 같은 AI라도 나오는 코드의 정밀도가 완전히 달라집니다.

"손으로 전부 쓰기엔 너무 힘들 것 같은데..."라고 생각하시겠죠. 안심하세요. 방금 설명한 흐름을 반자동으로 수행해 주는 도구가 이미 존재합니다.

OSS(Open Source Software)이므로 누구나 사용할 수 있습니다. 도입 이미지는 다음과 같습니다 (세부 사항은 버전에 따라 달라지므로 반드시 공식 README를 확인하세요).

# Spec Kit을 사용할 수 있게 하기 (uvx 경유 예시)
uvx --from git+https://github.com/github/spec-kit.git specify init my-project

도입하면 대응 에이전트(Claude / Copilot / Gemini / Codex 등)로부터 다음과 같은 슬래시 커맨드(Slash command)를 사용할 수 있게 됩니다.

커맨드	역할
/speckit.constitution	프로젝트 헌법을 만든다
/speckit.specify	사양 (spec.md)을 만든다 — 무엇을/왜
/speckit.clarify	사양의 모호함 (확인 필요 사항)을 제거한다
/speckit.plan	기술 계획 (plan.md)을 만든다
/speckit.tasks	태스크 (tasks.md)로 분해한다
/speckit.analyze	결과물 간의 정합성을 체크한다
/speckit.implement	태스크를 실행하여 구현한다

흐름상으로는, constitution으로 토대를 만들고, specify로 기능의 사양을 작성하며, clarify로 모호함을 제거한 뒤, plan → tasks → implement 순으로 진행합니다.

내려갑니다. 각 단계에서 AI에게 모든 것을 떠넘기는 것이 아니라, 인간이 내용을 확인하고 수정하는 것이 올바른 사용법입니다. 30종의 에이전트(Agent)에 대응하며, 툴을 교체하더라도 동일한 흐름을 사용할 수 있다는 점이 강점입니다.

또 다른 선택지는 Amazon이 2026년 5월에 국제 전개를 시작한 Kiro입니다. VS Code 기반의 에이전트형 IDE로, 처음부터 「Spec(사양)」, 「Steering(규약)」이라는 개념이 내장되어 있습니다. Steering 파일에 코딩 규약을 작성해 두면, 에이전트가 매번 그에 따라 움직입니다. Spec Kit의 「헌법(Constitution)」과 유사한 발상입니다.

여기서 오해하지 말아야 할 점은, SDD의 본질은 툴이 아니라 "순서"라는 것입니다. "구현하기 전에, 무엇을 만들 것인지를 구조화하여 작성한다". 이것만 지킨다면, 툴을 도입하기 전이라도 단순히 Markdown 파일을 4장(constitution / spec / plan / tasks) 두는 것만으로도 오늘부터 바로 시작할 수 있습니다. 오히려 처음에는 그 편이 무엇이 일어나고 있는지 이해하기 쉽습니다. 툴은 익숙해진 뒤 "이걸 매번 손으로 쓰기 귀찮다"라고 느껴질 때 도입해도 충분합니다.

자, 이제부터가 가장 전달하고 싶은 핵심입니다.

SDD를 "사양서를 먼저 작성하는 것"만으로 끝내버리면, 예전 방식의 "써놓고 만족하는 사양서"로 역행하게 됩니다. 써놓고 아무도 보지 않고, 코드와 어긋나도 알아채지 못하는, 바로 그 사양서 말입니다. 그러면 의미가 없습니다.

SDD가 진정으로 효과를 발휘하는 것은, 사양을 "실행 가능(executable)"하게 만들었을 때입니다. 이것이 무슨 뜻인지 순서대로 설명하겠습니다.

아까의 spec.md에서, 수락 조건(Acceptance Criteria, AC)에 AC-1과 같은 번호를 매겼었죠. 그것을 테스트 코드와 1대1로 대응시키는 것입니다.

// tasks.create.spec.test.ts
// spec.md의 수락 조건(AC)과 테스트를 1대1로 대응시킨다
import { describe, it, expect } from "vitest";
...

이렇게 하면, "사양을 충족하는가"를 인간의 감상이 아니라, 테스트의 성패를 통해 기계적으로 판정할 수 있게 됩니다. AC-1부터 AC-5까지 모두 초록색(Pass)이라면 사양을 충족한 것이고, 빨간색(Fail)이라면 충족하지 못한 것입니다. 리뷰의 기준이 "돌아가는 것 같다"에서 "모든 AC를 통과했다"로 바뀌는 것입니다.

여기서 한 걸음 더 나아갑니다. "수락 조건에 적었는데 테스트가 존재하지 않는 경우"를 기계로 검출합니다. 헌법 제2조 "수락 조건은 반드시 하나 이상의 테스트에 대응시켜야 한다"를 사람의 선의가 아니라 시스템으로 지키는 것입니다.

# scripts/check_traceability.py
# spec.md의 AC-x가 테스트 파일 내에서 참조되고 있는지 확인한다
import re
...

그리고 이것을 CI(GitHub Actions)에 통합하여, **미대응 수락 조건이 있다면 머지(Merge)할 수 없는 게이트(Gate)**로 만듭니다.

# .github/workflows/spec-gate.yml
name: spec-gate
on: [pull_request]
...

이렇게 하면 어떤 일이 벌어질까요? 사양에 새로운 수락 조건을 추가했는데 테스트를 작성하는 것을 잊었다면, CI가 빨간색으로 변하며 알려줍니다. 사양이 "써놓고 끝"이 아니라, 코드와 항상 동기화되는 "살아있는 사양"이 되는 것입니다. 이것이 바로 「실행 가능 사양」입니다.

마지막으로 드리프트(Drift) 대책입니다. 코드를 수정했는데 사양 업데이트를 잊거나, 반대로 사양만 바꾸고 코드가 따라오지 못하는 등의 어긋남을 정기적으로 찾아냅니다. 완전 자동화는 어렵지만, AI에게 차이점 리뷰(Diff Review)를 시키는 것만으로도 상당히 효과적입니다(프롬프트는 다음 장에서 소개하겠습니다).

추적성(Traceability)을 표로 관리하면 드리프트를 한눈에 파악할 수 있습니다.

수락 조건	테스트	구현	상태
AC-1	✅ 있음	✅ 있음	동기화
...	드리프트 (테스트 미생성)

"AC-4는 구현했는데 테스트가 없다"는 사실이 표에서도, CI에서도 빛납니다. 어긋남을 "누구의 잘못"이 아니라 "관측 가능한 사실"로 다룹니다. 이 부분은 아키텍타(Akira Papa)가 항상 말하는 "비난의 축이 아니라 배려의 축"과 같습니다. 사람을 비난하지 않고, 시스템으로 어긋남을 찾아내는 것이죠.

솔직히 말씀드리겠습니다. SDD도 만능은 아닙니다. 오히려 과하면 역효과로 느려질 수 있습니다. 흔히 빠지는 함정과 철수 기준을 표로 정리해 두겠습니다.

함정	증상	대처	철수 기준
과잉 사양 (overspec)	글자 하나 고치는데 사양서 3장을 업데이트함	작은 변경에는 SDD를 사용하지 않음	사양을 쓰는 시간 > 구현하는 시간이 지속된다면, 해당 기능은 SDD 대상에서 제외한다
드리프트 (Drift) 방치	코드만 수정하고 사양을 업데이트하지 않음	CI 게이트 + 차분 리뷰 (diff review)를 정례화	표가 "드리프트"로 가득 차면, 일단 구현을 멈추고 사양을 현 상태에 맞춘다
모호함 방치	[NEEDS CLARIFICATION]을 채우지 않고 구현으로 넘어감	clarify를 필수 단계로 지정	미확정 사항이 3개 이상 남은 상태로 구현을 진행하려 하면 중단한다
전부 SDD화	프로토타입·조사 단계에까지 사양을 요구	버릴 전제의 코드는 바이브 코딩 (Vibe Coding)으로 충분함	"이것은 버릴 코드"라고 알고 있다면 사양을 쓰지 않는다
헌법의 형식화	헌법은 있지만 아무도 따르지 않음	헌법을 "테스트 가능한 규칙"으로 압축	지켜지지 않는 조항은 지킬 수 있는 입도(granularity)로 다시 쓰거나 삭제한다

가장 많은 사례는 **"과잉 사양"**이라고 생각합니다. SDD가 효과를 발휘하는 곳은 남길 코드, 팀이 함께 만지는 코드, 프로덕션에서 동작하는 코드입니다. 반대로, 잠깐 테스트해보고 싶을 뿐이거나 버릴 전제의 프로토타입이라면, 느낌 가는 대로 만드는 것(Vibe Coding)이 더 빠릅니다. 모든 것을 사양화하려고 하지 마세요. 이것이 정말 중요합니다.

판단의 구호는 심플합니다. "이것, 다음 주에 나나 누군가가 다시 만질까?". 만질 것이라면 사양을 씁니다. 만지지 않는다면(버린다면) 쓰지 않습니다. 그뿐입니다.

SDD 전체를 통해 인간과 AI의 역할 분담을 정리하면 다음과 같습니다. 이것이 이 기사에서 가장 전달하고 싶은 표일지도 모릅니다.

공정	인간이 하는 일 (판단·의도)	AI에게 맡기는 일 (생성·실행)
헌법	양보할 수 없는 방침·품질 기준을 결정	문장화, 누락 사항 지적
...

보시다시피, 인간이 사라지기는커녕 상류 단계의 "판단"의 무게가 더 커지고 있습니다. 코드를 치는 양은 줄어들지만, "무엇을 만들 것인가", "어디까지가 완성인가", "이대로 진행해도 되는가"를 결정하는 것은 여전히 인간의 일입니다. AI는 그 판단을 고속으로 실행해 주는 매우 우수한 구현 파트너입니다. 주도권은 놓지 않되, 손은 마음껏 빌린다. 이것이 딱 적절한 거리감이 아닐까 합니다.

마지막으로, 내일부터 바로 사용할 수 있는 프롬프트 3개를 남겨둡니다. 복사해서 { } 안의 내용만 교체해 사용하세요.

사양을 작성했다면, 구현으로 넘어가기 전에 이것을 통과시키세요. 추측으로 구현되는 사고가 급격히 줄어듭니다.

당신은 사양 리뷰 전문가입니다. 다음 사양(spec.md)을 읽고,
"구현자나 AI가 추측으로 채워버릴 법한 모호한 점"을 찾아내십시오.
# 출력 규칙
...

사양이 확정되었다면, AC(Acceptance Criteria, 수락 조건)를 테스트 설계도로 전환합니다. 실행 가능한 사양으로 가는 입구입니다.

다음 수락 조건(AC)을 자동 테스트 케이스 목록으로 변환하십시오.
# 출력 규칙
- 각 테스트에 대응하는 AC-x의 ID를 반드시 명시할 것 (추적성 확보를 위해)
...

정기적으로, 혹은 PR(Pull Request) 전에 실행합니다. 사양과 코드의 괴리를 AI가 찾아내게 합니다.

당신은 사양과 코드의 정합성을 체크하는 리뷰어입니다.
다음의 "사양"과 "구현 코드"를 대조하여, 차이(drift)를 보고하십시오.
# 관점
...

이 3개 프롬프트의 공통점은 **"AI가 멋대로 단정 짓지 않게 하고, 판단은 인간에게 되돌린다"**는 형태를 취하고 있다는 점입니다. AI는 모호함을 찾거나, 변환하거나, 차분(diff)을 내는 데 능숙합니다. 하지만 "이대로 간다"라고 결정하는 것은 인간입니다. 역할 분담을 여기서도 흔들리지 않게 하는 것이 요령입니다.

내용이 길어졌으므로 마지막으로 요약하겠습니다.

• AI로 구현이 빨라진 만큼, 병목 구간은 **"무엇을 만들 것인가에 대한 설계와 합의"**로 이동했다.
• 바이브 코딩 (Vibe Coding, 느낌대로 던지기)은 사양이 대화 속에 묻히거나, 드리프트가 발생하거나, 리뷰가 불가능해지는 3가지 이유로 조용히 사고를 일으킨다.
• Spec-Driven Development는 코드 작성 전에 "헌법·사양·계획·태스크"를 구조화하여 작성하고, 이를 AI를 위한 설계도로 만드는 방법론이다 (GitHub Spec Kit / Amazon Kiro 등이 실제 도구로 존재).
• 사양을 **"실행 가능"**하게 만들면 (수락 조건 $\rightarrow$ 테스트 $\rightarrow$ CI 게이트 $\rightarrow$ 추적성), 단순히 써놓고 만족하는 사양서 단계에서 졸업할 수 있다.
• 단, 모든 것을 SDD화하지 마라. 남길 코드에만 사용하라. 버릴 코드는 느낌대로 해도 괜찮다.

자, 첫걸음입니다. 갑자기 전부 다 할 필요는 없습니다. 오늘 할 일은 이것뿐입니다.

다음에 만들 작은 기능 하나를 선택하기 (API 1개, 화면 1개 정도) - 해당 기능의 spec.md를 한 장 작성한다.

• 수락 조건(Acceptance Criteria, AC)에 AC-1, AC-2...와 같이 번호를 매긴다 (방법(How)은 쓰지 않는다).
• 프롬프트 ①을 실행하여 모호한 점 3가지를 없앤다.
• 프롬프트 ②를 통해 수락 조건을 테스트로 변환하고, 거기서부터 구현에 들어간다.

이것만으로도 AI의 출력이 "뭔가 어긋나 있네"에서 "대체로 맞네"로 바뀌는 것을 아마 체감할 수 있을 것입니다.

마지막으로, 개인적인 이야기를 조금만 하겠습니다.

사양(Specification)이라는 것이 귀찮은 의무처럼 느껴지기 쉽지만, 아키라 파파(あきらパパ)는 이를 **"내일의 나에게 남기는 쪽지"**라고 생각합니다. 오늘의 내가 "무엇을 만들고 싶었는지"를 제대로 언어화해서 남겨두는 것입니다. 그렇게 하면 내일의 나도, 옆 팀 동료도, 그리고 AI도 망설임 없이 움직일 수 있습니다. 3일 뒤에 "어라, 이거 대체 왜 만들었더라?"라며 머리를 싸매는 미래를 미리 방지하는 감각이죠.

그것은 즉, 내일의 내가 "그때 사양서 써줘서 고마워요"라고 말하게 만드는 선택인 것입니다.

그리고 하나 더. AI 시대는 코드를 치는 속도로 차이가 나는 시대가 아니게 되어가고 있습니다. 차이가 나는 지점은 **"무엇을 만들지 설계할 수 있는 능력"과 "그것을 남길 수 있는 체계를 갖추고 있는가"**입니다. 사양이라는 설계도는 쓰면 쓸수록 자신의 자산이 됩니다. 코드는 AI가 몇 번이고 다시 생성할 수 있지만, "무엇을 만들어야 하는가"를 꿰뚫어 보고 언어로 표현하는 능력은 AI에게 통째로 맡길 수 없는, 당신의 가치 그 자체입니다.

구현자에서 설계자로. 손을 움직이는 사람에서 설계도를 그리는 사람으로. 그 첫걸음은 단 한 장의 spec.md에서 시작할 수 있습니다.

내일의 내가 "고마워요"라고 말해줄 그 한 걸음, 괜찮으시다면 오늘 한번 내디뎌 보세요.

• GitHub Spec Kit (github/spec-kit) 공식 리포지토리 / 문서
• Microsoft for Developers 블로그 "Diving Into Spec-Driven Development With GitHub Spec Kit"
• Amazon Kiro 공식 문서 (Specs / Steering)

※ 도구의 커맨드 이름 및 도입 절차는 버전에 따라 달라질 수 있습니다. 실제로 사용할 때는 반드시 각 공식의 최신 문서를 확인해 주세요.