GitHub Spec Kit 최신 버전 기준
IT/AI
사양 기반 코딩: “빠르다”고 믿다가 19% 느려지는 진짜 이유
“AI에게 맡기면 빨라진다” — 이 믿음이 실제로 생산성을 갉아먹고 있을 수 있습니다. METR의 무작위 대조 실험 결과, 숙련 개발자들이 AI 코딩 도구를 사용했을 때 오히려 19% 더 느려졌습니다. 그리고 이를 해결하기 위해 GitHub이 내놓은 방법이 바로 ‘사양 기반 코딩(Spec-Based Coding)’입니다.
“AI 쓰면 빠를 거야” — 실제로는 어떤 일이 일어나고 있나
많은 분들이 오해하는 부분이 있습니다. AI 코딩 도구를 쓰면 당연히 개발 속도가 빨라질 것이라는 믿음입니다. 그런데 2025년 7월, 비영리 AI 평가 기관 METR이 발표한 무작위 대조 실험(RCT) 결과는 이 직관을 정면으로 뒤집었습니다.
💡 이 수치는 공식 연구 논문과 교차 검증한 결과입니다.
숙련된 오픈소스 개발자 16명을 대상으로 한 실험에서, AI 도구를 허용한 그룹의 태스크 완료 시간이 그렇지 않은 그룹보다 19% 더 길었습니다. 더 충격적인 것은, 참여자들이 실험 전 “24% 빨라질 것”이라 예측했고, 실험이 끝난 후에도 “20% 빨라졌다”고 스스로 믿었다는 점입니다. (출처: METR, “Measuring the Impact of Early-2025 AI on Experienced Open-Source Developers”, arxiv:2507.09089, 2025.07.10)
이것이 독자 여러분께 의미하는 것은 하나입니다. AI가 코드를 빠르게 생성해 주는 것과, 그 코드가 실제로 우리 프로젝트에 쓸 수 있는 코드가 되는 것은 전혀 다른 이야기라는 것입니다.
직접 확인할 수 있는 수치:
$$\text{체감 생산성} – \text{실제 생산성} = +24\% – (-19\%) = 43\%\text{p 의 착각}$$
→ 개발자들은 AI 덕분에 43% 포인트만큼 빨라졌다고 ‘느끼지만’, 실제 성과는 정반대였습니다. AI가 코드를 내놓는 속도와 개발자가 그 코드를 검수·수정·통합하는 데 드는 시간을 합산하면, 순수 작업 시간은 오히려 늘어납니다.
이 문제를 해결하기 위해 GitHub이 2025년 9월 공개한 오픈소스 도구가 바로 Spec Kit이고, 그 핵심에 있는 개념이 사양 기반 코딩(Spec-Based Coding)입니다.
사양 기반 코딩이란 무엇인가: 개념과 등장 배경
사양 기반 코딩(Spec-Based Coding, 또는 Spec-Driven Development)은 코드를 먼저 작성하는 대신, “무엇을, 왜 만들어야 하는지”를 먼저 문서화(사양서)하고, 그 사양서가 코드 생성을 직접 구동하도록 하는 개발 방식입니다. GitHub 공식 블로그는 이를 “코드가 진실의 원천(source of truth)이던 시대에서, 의도(intent)가 진실의 원천이 되는 시대로의 전환”이라고 설명합니다. (출처: GitHub Blog, “Spec-Driven Development with AI”, 2025.09.02)
사양 기반 코딩이 등장한 배경
바이브코딩(Vibe Coding)은 AI에게 자연어로 요청하면 코드가 나오는 방식입니다. 안드레 카파시(Andrej Karpathy)가 2025년 2월 처음 제시한 이 개념은 콜린스 사전의 ‘2025년 올해의 단어’로 선정될 만큼 폭발적으로 퍼졌습니다. 그런데 바이브코딩의 근본적인 문제가 있습니다.
GitHub 공식 문서는 이를 이렇게 표현합니다. “AI에게 ‘사진 공유 기능 추가해줘’라고 하면, AI는 수천 가지 명시되지 않은 요구사항을 스스로 추측해야 한다. 그 추측 중 일부는 반드시 틀린다.” 즉, 모호한 프롬프트 → AI의 추측 → 틀린 방향 → 수정 → 또 추측의 반복이 발생하는 구조입니다.
Microsoft 개발자 블로그가 든 사례 (2025.09.15)
PM은 ‘알림 설정’이 채널별 토글이라고 생각했고, 백엔드 개발자는 단순 온/오프 스위치로 구현했으며, 프론트엔드 개발자는 OS 알림과 연동될 것이라 가정했습니다. 디자이너는 유저 서비스 절반을 재설계해야 하는 목업을 만들었습니다. 이것은 소통 실패가 아니라 공유된 맥락(shared context)의 부재입니다.
사양 기반 코딩은 이 ‘공유된 맥락’을 AI가 읽고 실행할 수 있는 형태로 먼저 만들어 놓음으로써, AI의 추측 오류를 원천 차단합니다.
GitHub Spec Kit 실전 사용법: 4단계로 정리
GitHub이 2025년 9월 오픈소스로 공개한 Spec Kit은 사양 기반 코딩을 실제 워크플로우에 적용하기 위한 도구 모음입니다. Claude Code, GitHub Copilot, Gemini CLI 등 20개 이상의 AI 에이전트를 지원하며, MIT 라이선스로 누구나 무료로 사용할 수 있습니다. (출처: github/spec-kit 공식 저장소, 2026.03 기준)
설치 방법 (한 줄 명령어)
uvx --from git+https://github.com/github/spec-kit.git specify init 프로젝트명 --ai claude
Python 3.11 이상, uv, Git이 설치된 환경에서 실행 (출처: GitHub Spec Kit README)
4단계 워크플로우
Specify (사양 정의)
/speckit.specify 명령 사용. 기술 스택은 언급하지 않고, “무엇을, 왜 만드는지” 사용자 여정(user journey)과 기대 결과만 작성합니다.
Plan (기술 계획)
/speckit.plan 명령 사용. 이 단계에서 비로소 기술 스택, 아키텍처 제약, 보안 요구사항, 레거시 통합 조건을 지정합니다.
Tasks (태스크 분해)
/speckit.tasks 명령 사용. 사양서와 계획서를 바탕으로 독립적으로 검증 가능한 작은 태스크들로 자동 분해합니다.
Implement (구현)
/speckit.implement 명령 사용. AI 에이전트가 태스크 목록을 순서대로(또는 병렬로) 실행하여 코드를 생성합니다.
핵심은 각 단계 사이의 명시적 검증 체크포인트입니다. GitHub 공식 문서는 이를 강조합니다. “AI가 아티팩트를 생성하고, 당신이 그것이 맞는지를 확인한다. 이 역할 분담이 이 접근법의 전부다.” (출처: GitHub Blog, 2025.09.02)
알고 보면 반대입니다: Spec-Based Coding의 두 가지 오해
오해 1: “사양서를 먼저 쓰면 더 느리지 않나요?”
직관적으로는 사양서 작성이 추가 부담처럼 느껴집니다. 그런데 생각해보면, 지금 바이브코딩이 느린 이유가 정확히 이 때문입니다. 사양 없이 AI에게 맡기면 → AI가 추측 → 틀린 결과 → 수정 요청 → 또 다른 부분이 망가지는 무한 루프가 발생합니다. GitHub 공식 블로그는 이를 “코드는 본질적으로 결합 아티팩트(binding artifact)다. 일단 구현하면 거기서 떼어내기 매우 어렵다”고 설명합니다.
반면 사양서는 수정 비용이 거의 없습니다. 사양서에서 방향을 바꾸면 키스트로크 몇 번이지만, 이미 구현된 코드에서 방향을 바꾸면 스프린트 전체를 다시 써야 합니다. 즉, 앞에서 쓰는 30분이 뒤에서 날릴 3일을 막습니다.
오해 2: “사양 기반 코딩은 폭포수(Waterfall) 방식 아닌가요?”
Microsoft 개발자 블로그(2025.09.15)는 이 오해를 명확히 짚습니다. “SDD는 상세하고 딱딱한 요구 문서를 쓰는 것이 아니다. 폭포수 계획도, 미래를 예측하려는 수고도 아니다.” 핵심 차이는 사양서가 ‘살아있는 문서(living document)’라는 점입니다. 코드와 함께 진화하며, 방향을 바꿀 때는 사양서를 먼저 수정하고 AI에게 재생성을 요청하면 됩니다. 애자일과 충돌하지 않고, 오히려 애자일을 더 효율적으로 만드는 방식입니다.
💡 공식 changelog와 실사용 비교를 교차한 분석입니다.
Spec Kit 저장소(2026.03 기준)에는 .NET CLI 도구, Spring Boot + React 플랫폼, ASP.NET CMS 확장(30만 7천 줄 코드베이스), Jakarta EE 런타임 확장(42만 줄 코드베이스) 등 실제 대규모 레거시 프로젝트에 적용한 커뮤니티 데모가 포함되어 있습니다. 이 중 레거시 확장 두 사례는 기존 코드에 대한 사전 사양서나 헌법 없이도 Spec Kit이 작동함을 보여줍니다 — 즉, “기존 프로젝트는 못 쓴다”는 우려는 사실이 아닙니다.
보안 취약점 2.74배 — 여기서 사양 기반 코딩이 달라지는 지점
속도보다 더 심각한 문제가 보안입니다. CodeRabbit이 470개의 오픈소스 GitHub PR을 분석한 결과, AI가 공동 작성한 코드에서 보안 취약점 비율이 사람이 작성한 코드 대비 2.74배 높게 나타났습니다. 전체 이슈 수는 1.7배 더 많았습니다. (출처: CodeRabbit, “State of AI vs Human Code Generation Report”, 2025.12.17)
⚠️ 직접 검증 가능한 수치
$$\text{AI 작성 코드 보안 취약점} = 2.74 \times \text{인간 작성 코드 보안 취약점}$$
→ 프로덕션에 AI 코드를 그대로 올릴 경우, 인간이 쓴 코드 대비 2.74배 많은 보안 구멍을 안고 서비스를 운영하게 됩니다. 고객 데이터를 다루는 서비스라면 이것은 단순한 기술 부채가 아니라 법적 책임 문제로 이어질 수 있습니다.
사양 기반 코딩이 이 문제에 어떻게 대응하는지는 GitHub 공식 문서에서 명확히 설명합니다. “보안 요구사항은 사후에 추가하는 것이 아니라 사양서에서 처음부터 명시된다. 그리고 기술 계획 단계에서 이 제약 조건이 전체 구현을 안내한다.” 즉, AI가 보안을 추측해서 결정하는 것이 아니라, 처음부터 명문화된 보안 규칙을 받아서 코드를 생성합니다.
여기에 더해, Spec Kit의 /speckit.constitution 명령으로 만드는 ‘헌법(constitution.md)’ 파일에 조직의 보안 정책, 테스트 표준, 준수해야 할 규정(컴플라이언스) 요구사항을 사전 정의할 수 있습니다. 이 파일은 이후 모든 구현 단계에서 AI가 참조하는 ‘절대 지켜야 할 원칙’이 됩니다.
바이브코딩 vs 사양 기반 코딩: 어떤 상황에 뭘 써야 하나
사양 기반 코딩이 모든 상황에 최선은 아닙니다. GitHub 공식 문서 역시 바이브코딩이 유효한 상황을 명확히 인정합니다. “빠른 프로토타입이나 아이디어 검증에는 그냥 프롬프팅 방식도 훌륭하다.” 진짜 문제는 이 두 방식을 구분 없이 쓰는 것입니다.
| 구분 | 바이브코딩 | 사양 기반 코딩 |
|---|---|---|
| 최적 상황 | 빠른 PoC, 1회성 스크립트, 아이디어 검증 | 미션크리티컬 서비스, 기존 코드베이스 확장, 팀 협업 |
| 보안 위험 | 높음 (취약점 2.74배 위험) | 낮음 (보안 요구 사전 정의) |
| 장기 유지보수 | 어려움 (컨텍스트 손실) | 용이 (사양서가 컨텍스트 역할) |
| 팀 온보딩 | 어려움 (결정 근거 없음) | 쉬움 (헌법·사양서가 가이드) |
| 시작 비용 | 낮음 (즉시 시작) | 약간 높음 (사양서 작성 필요) |
표 1. 바이브코딩 vs 사양 기반 코딩 상황별 비교 (출처: GitHub Blog 및 Microsoft Dev Blog 내용 교차 정리)
💡 이 분석은 공식 문서와 실사용 데이터를 교차한 결과입니다.
Spec Kit은 현재 20개 이상의 AI 에이전트를 지원합니다. 특히 눈에 띄는 점은 Google의 Antigravity(agy), IBM Bob, Mistral Vibe 같은 비주류 에이전트까지 지원 목록에 포함된다는 것입니다. 이는 사양 기반 코딩이 특정 AI 도구에 종속된 개념이 아니라, 어떤 AI 에이전트를 쓰더라도 적용 가능한 보편적 방법론임을 의미합니다. 오늘 Claude Code를 쓰다가 내일 Gemini CLI로 바꿔도 사양서는 그대로 재활용됩니다.
Q&A — 자주 묻는 질문 5가지
Q1. Spec Kit을 쓰려면 GitHub Copilot 구독이 필요한가요?
▼
아닙니다. Spec Kit 자체는 MIT 라이선스의 무료 오픈소스입니다. Claude Code, Gemini CLI, Codex CLI, Cursor 등 다양한 AI 에이전트와 함께 사용할 수 있으며, GitHub Copilot은 지원되는 에이전트 중 하나일 뿐입니다. 단, 사용하는 AI 에이전트 자체의 구독 비용은 별도로 발생할 수 있습니다.
Q2. 코딩을 전혀 모르는 비개발자도 사양 기반 코딩을 쓸 수 있나요?
▼
사양서 작성(Specify, Plan 단계)은 비개발자도 충분히 할 수 있습니다. 실제로 GitHub 공식 문서는 “기술 스택은 신경 쓰지 말고, 무엇을 왜 만드는지만 생각하라”고 안내합니다. 다만 Tasks 검증 및 Implement 결과 확인 단계에서는 최소한 코드를 읽고 이해하는 능력이 있어야 AI가 방향을 잘못 잡았을 때 바로잡을 수 있습니다.
Q3. METR 연구에서 AI가 오히려 느리게 만든다면, 사양 기반 코딩도 결국 느리지 않나요?
▼
METR 연구에서 측정한 것은 ‘바이브코딩 방식의 AI 도구 사용’입니다. 연구팀도 2026년 2월 업데이트에서 “실험 설계를 바꾸고 있다”고 밝혔는데, 그 핵심이 맥락 제공 방식의 개선입니다. 사양 기반 코딩은 AI에게 충분한 맥락을 사전 제공함으로써 이 병목을 줄이는 접근법입니다. 아직 사양 기반 코딩 방식만을 대상으로 한 대규모 RCT 연구는 발표되지 않았으므로, 현재로서는 “구조화된 접근이 비구조화된 접근보다 유리하다”는 논리적 근거와 실사용 후기를 참고하는 수준입니다.
Q4. 기존에 진행 중인 프로젝트에 Spec Kit을 중간에 도입할 수 있나요?
▼
가능합니다. GitHub 공식 저장소에는 42만 줄 규모의 Jakarta EE 런타임과 30만 줄 규모의 ASP.NET CMS에 사전 사양 없이 Spec Kit을 적용한 데모가 포함되어 있습니다. 기존 코드베이스 확장(Brownfield) 시나리오에서는 새 기능에 대한 사양서만 작성하면 되므로, 처음부터 전체를 다시 문서화할 필요가 없습니다.
Q5. Spec Kit이 생성한 사양서 파일은 어디에 저장되나요?
▼
모든 파일은 프로젝트 루트의 .specify/ 폴더에 일반 마크다운(.md) 형식으로 저장됩니다. 헌법 파일은 .specify/memory/constitution.md에, 기능별 사양서는 .specify/specs/001-기능명/ 구조로 생성됩니다. 마크다운 파일이므로 직접 편집하거나 Git으로 버전 관리가 가능합니다.
마치며 — 속도보다 방향이 먼저입니다
2026년 현재, AI 코딩 도구를 쓰는 개발자 비율은 84%에 달합니다. 그런데 METR의 연구는 단순히 “도구를 쓰느냐 마느냐”가 생산성을 결정하지 않는다고 말합니다. 문제는 어떻게 쓰느냐입니다.
사양 기반 코딩이 말하는 것은 결국 이것입니다. AI는 놀라울 정도로 패턴을 잘 완성하지만, 마음을 읽지는 못합니다. 내가 원하는 것을 명확하게 말하지 않으면, AI는 추측할 수밖에 없고, 그 추측이 쌓일수록 코드베이스는 나도 모르는 방향으로 흘러갑니다.
사양서는 AI를 위한 것이 아닙니다. 사실은 우리 자신을 위한 것입니다. 내가 무엇을 만들고 싶은지를 먼저 분명히 하는 훈련, 그것이 AI 시대에 개발자가 갖춰야 할 가장 중요한 역량일지도 모릅니다.
본 포스팅 참고 자료
- GitHub Blog — “Spec-Driven Development with AI” (2025.09.02)
- GitHub Spec Kit 공식 저장소 (github/spec-kit, MIT License)
- Microsoft Developer Blog — “Diving Into Spec-Driven Development With GitHub Spec Kit” (2025.09.15)
- METR — “Measuring the Impact of Early-2025 AI on Experienced Open-Source Developers” (2025.07.10)
- CodeRabbit — “State of AI vs Human Code Generation Report” (2025.12.17)
- arXiv:2507.09089 — METR 연구 논문 원문
※ 본 포스팅은 2026년 3월 15일 기준으로 작성되었습니다. GitHub Spec Kit, AI 에이전트 지원 목록, 연구 결과 해석 등은 이후 업데이트로 변경될 수 있습니다. 본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있으며, 최신 정보는 공식 문서를 통해 확인하시기 바랍니다.
댓글 남기기