바이브 코딩을 넘어 Github Spec Kit으로 구현하는 SDD(Spec Driven Development) and hermes, harness

728x90

0. 들어가며 — 바이브 코딩, 그 다음은?

바이브 코딩(Vibe Coding)은 아이디어를 몇 시간 만에 동작하는 코드로 바꿔 준다. 프로토타입을 만들 때는 이보다 빠른 방법이 없다. 하지만 그렇게 만들어진 코드가 유지보수 가능한 시스템으로 살아남는가는 전혀 다른 문제다. 이 글은 임정환 교수님의 Spec-Driven AI Development 강의 내용을 바탕으로, 바이브 코딩의 한계를 짚고 그 대안으로 떠오른 SDD(Spec-Driven Development)와 이를 구현하는 GitHub Spec Kit, 그리고 에이전트를 통제하는 틀인 Agent Harness까지를 하나의 흐름으로 정리한 것이다.

본격적으로 들어가기 전에 한 가지 전제를 깔아 두자. 에이전틱 코딩의 세계는 변화 속도가 너무 빨라서 지금 정리한 내용이 내일 또 어떻게 바뀔지 모른다. "AI 시대에 작년은 조선시대, 재작년은 석기시대"라는 농담이 농담으로 들리지 않는 이유다. 그래서 더더욱, 도구가 바뀌어도 살아남는 개발 방법론의 뼈대를 붙잡아 둘 필요가 있다.

1. 왜 바이브 코딩만으로는 부족한가

바이브 코딩은 전형적인 바텀업(Bottom-up) 접근이다. 일단 코드를 만들어 눈에 보이는 결과부터 확인하고, 마음에 들지 않으면 다시 프롬프트를 던진다. 이 방식의 강점과 약점은 명확하다.

• 바텀업은 속도는 빠르지만 방향을 잃기 쉽다. 화면 하나하나는 그럴듯한데, 전체 그림이 어디로 가는지는 아무도 모른다.
• 바이브 코딩은 국소 최적화에는 강하지만 시스템에는 취약하다. 개별 함수·컴포넌트 수준의 품질은 높아도, 모듈 간 계약과 아키텍처 일관성은 보장되지 않는다.
• 요구사항과 코드 사이에는 반드시 소프트웨어 공학적 계층(요구사항 정의 → 설계 → 작업 분해)이 필요하다. 이 계층을 생략하면 코드는 나오지만 시스템은 나오지 않는다.

시니어 개발자들이 AI 시대에 오히려 PRD(제품 요구사항 문서), FR(기능 요구사항), UC(유스케이스) 같은 고전적인 산출물로 회귀하는 이유가 여기에 있다. 그 공백이 만들어 내는 위험을 이미 몸으로 겪어 봤기 때문이다. 이것은 후퇴가 아니라 복잡도를 관리하는 유일하게 검증된 방법이다.

바텀업 개발이 실패하는 이유는 코드를 못 짜서가 아니라, 요구사항과 코드 사이의 공학을 생략하기 때문이다.

테스트 관점에서도 같은 결론이 나온다. TDD가 뒷받침되지 않는 바이브 코딩은 "개발"이라기보다 일회성 생산에 가깝다. 만들 수는 있지만 고칠 수 없고, 고칠 수 없는 코드는 자산이 아니라 부채다.

TDD 없는 바이브 코딩은 ‘개발’이 아니라 ‘일회성 생산’이다. 개발은 되지만 유지보수가 안 된다.

2. Spec-Driven Development(SDD)란?

SDD는 위 문제에 대한 정면 돌파다. 핵심은 개발의 순서를 뒤집는 것이다.

코드를 먼저 짜는 것이 아니라, 명세(Spec)를 작성하면 그 명세가 실행되어 코드가 생성되게 한다. 명세가 개발의 중심(Source of Truth)이 되는 구조다.

기존 개발에서 명세서는 코드가 완성되는 순간 낡기 시작하는 문서였다. SDD에서는 반대로 명세가 살아 있는 실행 대상이고, 코드는 명세로부터 파생되는 산출물이다. 요구사항이 바뀌면 코드를 고치는 것이 아니라 명세를 고치고 다시 생성한다. AI 코딩 에이전트가 충분히 강력해진 지금에서야 비로소 현실이 된 접근이다.

아래 강의 영상과 논문은 이 글 전체의 출처이자 더 깊이 파고들 수 있는 자료다. (출처: 임정환 교수님)

Spec-Driven AI Development – Episode 1

Spec-Driven AI Development – Episode 2

The ONLY guide you’ll need for GitHub Spec Kit

관련 논문: arxiv.org/pdf/2602.00180v1

3. GitHub Spec Kit — SDD를 실현하는 오픈소스 툴킷

Spec Kit은 GitHub이 공개한 SDD 실현용 오픈소스 툴킷이다. 개발자가 ‘코드를 바로 작성하는 방식’에서 벗어나 명세를 중심으로 개발하도록, 단계별 슬래시 명령어와 문서 템플릿, 자동화 스크립트를 제공한다.

GitHub - github/spec-kit: 💫 Toolkit to help you get started with Spec-Driven Development

3.1 5단계 파이프라인

Spec Kit의 워크플로우는 다섯 단계로 이루어지며, 각 단계는 명확한 산출물 파일을 남긴다. 앞 단계의 산출물이 다음 단계의 입력이 되는 구조라서, 전체 과정 자체가 하나의 소프트웨어 공학 계층으로 동작한다.

단계	슬래시 명령어	산출물	역할
① Constitution	/speckit.constitution	constitution.md	프로젝트의 불변 원칙·규칙·기준 수립
② Specify	/speckit.specify	spec.md + 기능 브랜치	무엇을(What)·왜(Why) — 요구사항 명세
└ Clarify (선택)	/speckit.clarify	spec.md 보강	구조화된 질문으로 모호한 요구사항 구체화
③ Plan	/speckit.plan	plan.md, data-model.md	어떻게(How) — 기술 스택, 물리적 폴더 구조
④ Tasks	/speckit.tasks	tasks.md	실행 가능한 작업 단위로 분해
⑤ Implement	/speckit.implement	완성된 브랜치	작업을 순차 실행하여 구현 완료

여기에 품질을 보강하는 부가 명령이 있다. /speckit.analyze는 spec·plan·tasks 산출물 간의 일관성을 교차 검증하고(tasks 이후, implement 이전), /speckit.checklist는 요구사항의 완전성·명확성을 점검하는 체크리스트를 생성한다(plan 이후).

3.2 빠른 시작

# Specify CLI 설치 (uv 필요)
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# 프로젝트 초기화
specify init <project-name>

3.3 지원 에이전트와 철학

Spec Kit은 특정 AI 도구에 종속되지 않는다. GitHub Copilot, Claude Code, Gemini CLI, Cursor 등 다양한 AI 코딩 에이전트와 연동되며, 초기화 시점에 어떤 에이전트용 템플릿을 설치할지 선택한다. 설계 철학은 네 가지로 요약된다.

• 기술 독립적 — 언어·프레임워크 제한 없음
• 엔터프라이즈 요구 충족 — 조직 단위의 규칙·거버넌스를 헌법으로 명문화
• 사용자 중심 개발 — 사용자 스토리가 명세의 최상위 단위
• AI 기반 개발 프로세스 자동화 강화 — 사람은 명세와 검증에, 에이전트는 구현에 집중

4. 실습 — Spec Kit + Copilot으로 Todolist 앱 만들기

개념만으로는 감이 오지 않으니, Windows 환경에서 Next.js 기반 todolist 앱을 SDD 방식으로 처음부터 끝까지 만들어 본 기록이다.

4.1 환경 준비

PowerShell 스크립트 실행 정책을 완화하고, 필요하면 VS Code 설정을 초기화한 뒤 시작한다.

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
Get-ExecutionPolicy   # RemoteSigned

# (선택) VS Code 설정 초기화
rm -r $HOME\.vscode
rm -r $HOME\AppData\Roaming\Code

uv로 사용 가능한 Python을 확인하고(cpython 3.14.2 사용), Specify CLI를 설치한다.

uv python list          # 설치된/설치 가능한 Python 확인
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
uv tool list             # specify-cli v0.0.22 확인

4.2 Next.js 프로젝트 생성

npx create-next-app@latest todolist-app --typescript --eslint --tailwind --app --disable-git

React Compiler 활성화, src/ 디렉토리 미사용, import alias는 기본값 @/*를 선택했다. Next.js 16.1.4 + React 19 + TypeScript 5(strict) + Tailwind CSS 4 구성이다.

4.3 specify init — Spec Kit 이식

생성된 프로젝트 디렉토리 안에서 specify init .을 실행하면, AI 어시스턴트(copilot)와 스크립트 타입(PowerShell)을 선택한 뒤 템플릿이 병합된다. 이 과정에서 다음이 생긴다.

• .specify/memory/constitution.md — 프로젝트 헌법(불변 원칙)
• .specify/templates/ — spec·plan·tasks·checklist 문서 템플릿
• .specify/scripts/powershell/ — 기능 브랜치 생성 등 자동화 스크립트
• .github/agents/, .github/prompts/ — 워크플로우별 Copilot 에이전트·프롬프트 정의 9종

한 가지 주의: 에이전트 폴더에 인증 토큰 같은 민감 정보가 저장될 수 있으므로 .github/ 일부를 .gitignore에 추가하라는 보안 안내가 출력된다.

4.4 VS Code 통합 설정

.vscode/settings.json에 Spec Kit 프롬프트 파일 자동 추천과 스크립트 자동 승인을 걸어 두면 Copilot Chat에서 슬래시 명령이 매끄럽게 이어진다.

{
  "chat.promptFilesRecommendations": {
    "speckit.constitution": true,
    "speckit.specify": true,
    "speckit.clarify": true,
    "speckit.plan": true,
    "speckit.tasks": true,
    "speckit.analyze": true,
    "speckit.implement": true
  },
  "chat.tools.terminal.autoApprove": {
    ".specify/scripts/bash/": true,
    ".specify/scripts/powershell/": true
  }
}

4.5 프로젝트 헌법과 언어 규칙

/speckit.constitution으로 헌법을 세우기 전에, .github/copilot-instructions.md에 팀 규칙을 명문화했다. 핵심은 언어 사용 규칙과 커밋 컨벤션이다.

• 모든 AI 응답(설명·요약·진행 보고·산출물)과 코드 주석은 한국어로 작성한다.
• 단, 브랜치명·파일명·폴더명·코드 내 식별자(변수/함수/타입/컴포넌트명)는 영어를 사용한다.
• 커밋 메시지는 type(scope): "한국어 설명" 형식 — type은 feat·fix·docs·refactor·test·chore, scope는 const·spec·plan·task·impl.

feat(impl): "TodoList 컴포넌트 구현"
fix(task): "타입 오류 수정"
test(spec): "E2E 테스트 추가"
docs(const): "README 업데이트"

헌법에는 Library-First(모든 기능은 독립 라이브러리로 시작), Test-First(테스트 작성 → 승인 → 구현의 TDD 필수), 관찰 가능성, 단순성 같은 불변 원칙을 담았다. 파일·네이밍 규칙(파일명 kebab-case, 컴포넌트 PascalCase, 함수·변수 camelCase), Server Component 우선, React Compiler 환경에서 불필요한 useMemo/useCallback 지양 같은 코딩 규약도 함께 명시했다. Copilot 커스터마이징에 대해서는 아래 공식 문서와 커뮤니티 저장소가 좋은 출발점이다.

Customize chat to your workflow

Use custom instructions in VS Code

GitHub - github/awesome-copilot: Community-contributed instructions, prompts, and configurations to help you make the most of Gi

4.6 결과 — 58개 작업 전부 완료

/speckit.specify → /speckit.plan → /speckit.tasks → /speckit.implement를 거쳐 58/58 작업(100%)이 완료됐다. Phase 1~2(셋업·공통 기반)부터 US1 할일 추가 MVP, US2 완료 토글, US3 삭제+5초 Undo, US4 필터링, US5 localStorage 영속화, US6 다크모드·반응형, 마지막 문서화·성능·접근성 폴리시까지 전 구간을 TDD로 진행했다.

검증 항목	결과
단위 테스트 (Vitest 4 + Testing Library)	59개 통과 / 0 실패, 커버리지 100%
E2E 테스트 (Playwright, 3개 브라우저)	33개 시나리오 통과 / 0 실패
프로덕션 빌드 / 린트	성공 / 통과
성능 (p95)	필터 전환 < 50ms, 완료 토글 < 30ms, 추가 < 40ms (목표 100ms)

산출물 문서(spec.md, plan.md, tasks.md, research.md, README.md)가 코드와 함께 남는다는 점이 중요하다. E2E는 Playwright로 Chromium·Firefox·WebKit을 한 번에 검증했다.

GitHub - microsoft/playwright: Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and

TDD에서 User Story는 ‘무엇을 테스트해야 하는가’를 정의하는 가장 상위 수준의 명세다.

5. 협업 규칙 — Git 병합 전략 통일

SDD는 기능 단위 브랜치를 만들어 내므로, 팀 차원에서 병합 방식을 하나로 통일해 두는 것이 중요하다. 한 팀에서는 하나의 merge 방식을 정해 일관되게 사용한다.

구분	Fast-forward	3-way merge	Squash merge
병합 커밋	없음	있음	없음
히스토리	직선	분기 구조 유지	직선
브랜치 기록	없음	있음	없음
충돌 가능성	없음	있음	있음
주 사용 환경	단순 작업	협업	정리 목적

• FF merge → 개인 브랜치, 단기 작업
• 3-way merge → 팀 협업, 추적 가능한 히스토리가 필요할 때
• Squash merge → PR 단위로 히스토리를 깔끔하게 정리할 때

6. Agent Harness — 에이전트를 통제하는 바깥 틀

Agent가 통제되지 않으면 마지막에 남는 것은 청구서다.

SDD가 ‘무엇을 만들 것인가’를 통제한다면, 하네스(Harness)는 ‘에이전트가 어떻게 실행되는가’를 통제한다. 하네스란 원래 테스트 공학에서 온 용어로, 대상을 감싸서 실행·통제·검증하는 바깥 환경을 뜻한다. 에이전트에게 따라야 하는 규범을 만들어 씌우는 것 — 그것이 Agent Harness다. 프레임워크·테스트와 자주 혼동되므로 차이를 정리해 두자.

구분	Harness	Framework	Test
목적	실행·통제·검증	개발 규칙 제공	결과 검증
범위	환경 전체	코드 구조	개별 시나리오
위치	시스템 외곽	시스템 내부	Harness 내부
재현성	매우 중요	부차적	중요

상용 제품으로는 SDLC 전반을 AI 에이전트로 관리하는 Harness.io가 대표적이고, 오픈소스 진영에서는 LangChain·LangGraph 기반의 Deep Agents가 있다. Deep Agents는 계획 도구, 파일시스템 백엔드, 서브에이전트 생성 능력을 갖춘 전형적인 에이전트 하네스다. 에이전트 간 메시징을 다리 놓는 hermes 같은 브리지 계층도 같은 문제의식 — 에이전트를 열어 두되 통제 가능하게 — 위에 서 있다.

Harness: AI for DevOps, Testing, AppSec, and Cost Optimization

GitHub - langchain-ai/deepagents: Deep Agents is an agent harness built on langchain and langgraph. Deep Agents are equipped wit

6.1 Human-in-the-loop(HITL)

하네스의 핵심 안전장치가 Human-in-the-loop이다. 모델이 파일 쓰기나 SQL 실행처럼 검토가 필요한 행동을 제안하면, 미들웨어가 실행을 일시 정지하고 사람의 승인·수정·거부를 기다린다. ‘에이전트에게 다 맡기되, 되돌리기 어려운 행동 앞에서는 반드시 사람이 문지기가 된다’는 원칙의 구현이다.

Human-in-the-loop - Docs by LangChain

6.2 온톨로지 — 조직 데이터를 이해하는 LLM의 시작점

에이전트를 조직에 들이면 곧바로 부딪히는 문제가 있다. 에이전트가 우리 회사의 ‘고객’, ‘주문’, ‘정산’이 무엇인지 모른다는 것이다. 파편화된 데이터를 개념과 관계로 연결해 주는 온톨로지(Ontology)가 LLM 기반 의사결정의 시작점이 되는 이유다. 하네스가 행동을 통제한다면, 온톨로지는 이해의 기반을 통제한다.

조직 데이터를 이해하는 LLM의 시작점: 온톨로지(Ontology) - Deskroom | 블로그

7. Forward Deployed Engineer(FDE) — 일하는 방식의 변화

도구가 바뀌면 엔지니어의 역할도 바뀐다. 팔란티어(Palantir)가 만든 직군인 FDE(Forward Deployed Engineer, 전방 배치 엔지니어)는 고객 현장에 나가 고객의 문제를 직접 소프트웨어로 풀어내는 엔지니어다. 팔란티어는 이제 이 역할마저 AI로 확장했다. AI FDE는 대화형 명령으로 Foundry 플랫폼을 대신 조작해 주는 에이전트다.

Palantir

현장의 속도감은 이렇다. 과거에는 고객 미팅에서 요구사항을 받아 와 몇 주 뒤 데모를 보여줬다면, 지금은 미팅 시작 후 종료 전에 개념 증명(PoC, Proof of Concept)을 완성해 보여준다. SDD와 에이전틱 코딩이 만든 새로운 표준이다.

8. 계속 바뀌는 도구와 모델, 그리고 다음 흐름

8.1 디버깅 파트너로서의 프런티어 모델

구현은 에이전트가 하더라도, 막혔을 때 함께 파고들 프런티어 모델은 여전히 중요하다. 코딩·에이전트 특화 모델로는 Anthropic의 Claude Opus 계열과 OpenAI의 GPT-5.2 Codex가 대표적이다.

Claude Opus 4.5

IDE 쪽도 빠르게 움직인다. VS Code는 Insiders 빌드로 매일 최신 기능을 배포하고, 구글은 에이전트 중심 IDE인 Antigravity를 내놓았다.

Download Visual Studio Code Insiders

Google Antigravity

8.2 LLM 다음엔 VLM

텍스트를 넘어선 다음 흐름은 VLM(Vision-Language Model)이다. 컴퓨터 비전과 자연어 처리를 결합해, 이미지를 보고 질문에 답하는 VQA(Visual Question Answering) 같은 과제를 푼다.

Visual Question Answering

비전 언어 모델(VLM)이란 무엇인가요? | IBM

국내 모델도 이 흐름에 올라타 있다. SKT의 A.X-K1, LG AI연구원의 K-EXAONE-236B-A23B가 Hugging Face에 공개되어 있고, 모델의 지시 이행 능력을 표준화해 평가하려는 IFEval(Instruction-Following Evaluation) 같은 벤치마크 연구도 함께 봐 둘 만하다.

skt/A.X-K1 · Hugging Face

LGAI-EXAONE/K-EXAONE-236B-A23B · Hugging Face

Instruction-Following Evaluation for Large Language Models

9. 마치며 — 조직 관점의 마지막 퍼즐

개인의 개발 방식이 바뀌면 조직 구조 논의도 따라온다. 기능 중심 부서(Department), 사업·제품 중심 사업부(Division), 전사 표준(Enterprise) 중 어디에 무게를 둘 것인가에 따라 속도·중복·거버넌스의 트레이드오프가 달라진다. 에이전트와 SDD를 도입할 때도 ‘누가 헌법(constitution)을 소유하는가’라는 같은 질문이 반복된다.

구분	Department	Division	Enterprise
기준	기능	사업/제품	전체 조직
책임	부분	End-to-End	정책·표준
의사결정	느림	빠름	느리지만 안정
중복	낮음	높음	관리 대상
기술 구조	공유 레이어	독립 서비스	플랫폼/거버넌스

정리하면 이렇다.

1. 바이브 코딩은 강력하지만, 요구사항과 코드 사이의 공학 계층 없이는 시스템이 되지 못한다.
2. SDD는 명세를 실행 가능한 중심 산출물로 만들어 그 계층을 복원하고, Spec Kit은 이를 Constitution → Specify → Plan → Tasks → Implement의 5단계 파이프라인으로 도구화한다.
3. 실습 결과가 보여주듯, 헌법·명세·TDD가 갖춰지면 에이전트 주도 개발로도 테스트 전부 통과 + 문서가 남는 프로덕션 품질에 도달할 수 있다.
4. 남는 위험은 하네스(실행 통제)와 HITL(사람의 승인), 온톨로지(조직 지식)로 관리한다.
5. 모델과 도구는 계속 바뀐다. 살아남는 것은 방법론이다.

오늘 정리한 내용도 내일이면 낡을 수 있다. 하지만 ‘명세가 먼저, 코드는 그 다음’이라는 원칙만은 당분간 유효할 것이다.