AI-Native 소프트웨어 개발: GitHub Spec Kit을 활용한 Spec-Driven Development

728x90

0. 들어가며 — AI-Native로 가는 세 단계

앞선 글(바이브 코딩을 넘어 GitHub Spec Kit으로 구현하는 SDD)에서 명세 중심 개발의 큰 그림을 다뤘다면, 이번 글은 한 걸음 더 들어간다. 조직이 AI-Native가 된다는 것이 무엇인지, 그 과정에서 개발자와 리더의 역할이 어떻게 바뀌는지, 그리고 Spec Kit 파이프라인을 실전에서 굴릴 때 부딪히는 문제들 — SC/AC 정의, clarify, 그린필드 vs 브라운필드 — 을 정리한다. (출처: 임정환 교수님)

AI를 받아들이는 조직은 대체로 세 단계를 밟는다.

단계	이름	설명
1단계	AE — AI Engineering	AI를 도구로 활용해 기존 개발 프로세스를 보강하는 단계. 코드 자동완성, 문서 요약 수준.
2단계	AS — Agentic AI System	AI가 에이전트로서 계획을 세우고 여러 단계를 자율 실행하는 단계. 사람은 목표와 경계를 정한다.
3단계	AN — AI Native	개발 프로세스 자체가 AI를 전제로 재설계된 단계. 명세·규칙·테스트가 AI가 읽고 실행하는 일급 산출물이 된다.

이 글에서 다루는 SDD와 Spec Kit은 3단계, 즉 AI Native로 가기 위한 구체적인 방법론이다.

1. 역할의 이동 — 구현은 AI에게, 통제는 리더에게

AI Native 조직에서 가장 크게 바뀌는 것은 사람의 역할이다. 개발자의 구현이 AI로 이동하면서, 팀원은 코드를 한 줄씩 작성하는 사람에서 명세를 쓰고 결과를 검증하는 사람으로 바뀐다. 문제는 팀리더다. 통제되지 않은 에이전트는 그럴듯한 코드를 대량으로 쏟아내며 폭주한다 — 방향이 틀렸다는 것을 알아차렸을 때는 이미 검토할 수 없는 양의 변경이 쌓여 있다.

그래서 리더에게는 새로운 기술이 필요하다. 바로 통제의 기술이다. 그 핵심 원칙이 행위와 평가의 분리다. 코드를 만드는 주체(AI)와 그 결과를 판정하는 기준(테스트·완료 조건)을 분리해서, 만드는 쪽이 아무리 빨라도 기준을 통과하지 못하면 앞으로 나아가지 못하게 만드는 것이다.

설계자는 기준을 만들고, 기준을 통과하게 하는 테스트 시나리오를 만들고, 그 시나리오를 통과하는 코드는 AI가 만든다.

프롬프트 엔지니어링이 개별 요청의 품질을 높이는 기술이라면, Skills·instructions 같은 장치는 에이전트에게 지속되는 규범을 부여하는 기술이다. 통제는 한 번의 좋은 프롬프트가 아니라 반복 가능한 규칙에서 나온다.

2. 바이브 코딩의 리스크 — 문서가 없다

바이브 코딩의 가장 큰 리스크는 코드 품질이 아니라 문서가 남지 않는다는 것이다. 대화 속에서 요구사항이 정의되고 대화가 끝나면 사라진다. 왜 이렇게 만들었는지, 완료 기준이 무엇이었는지 아무도 답할 수 없다. 그래서 MVP까지는 되는데, 서비스까지는 어렵다. 서비스는 유지보수·확장·인수인계가 전제인데, 그 전제가 모두 문서 위에 서 있기 때문이다.

결론은 단순하다. AI 코딩에는 규칙이 필요하다. 이를 문서 체계로 풀어낸 대표적인 접근이 3-File System이다 — 요구사항(PRD, Product Requirements Document), 분석, 구현 계획을 각각 파일로 남기고 AI가 이를 참조하며 작업하게 한다. 여기에 같은 프롬프트를 완료될 때까지 반복 실행하는 Ralph Loop 같은 실행 패턴을 결합하면, 원시적이지만 동작하는 AI 개발 루프가 만들어진다.

Spec Kit은 이 아이디어를 한 단계 밀어붙인다. 명세를 사람이 읽는 문서가 아니라 executable PRD — AI가 읽어서 실행 가능한 요구사항 문서 — 로 만들고, 이를 Tasks로 분해해 구현까지 연결한다.

규칙 → 요구사항 → 설계 → 작업 → 구현.
Spec Kit에서는 이것이 곧 constitution → specify → plan → tasks → implement다.

3. Spec Kit 파이프라인 심화

전체 흐름은 다음과 같다. 괄호 안은 선택 단계다.

constitution → specify (사용자 문제 정의, SC·AC) → ( clarify ) → plan → tasks → ( analyze ) → implement (phase 1~N)

3.1 Constitution — 직접 수정은 금지

.specify/memory/constitution.md는 프로젝트의 공적 규칙(public rule)이다. TDD 강제 같은 AI 폭주 방지 장치가 여기에 들어간다. 중요한 것은 이 파일을 손으로 직접 수정하지 않는 것이다. 반드시 /speckit.constitution 명령을 통해 갱신해야 버전 관리와 템플릿 정합성이 유지된다.

3.2 Specify — SC와 AC가 명세의 심장

specify 단계에서 정의하는 것은 기능 목록이 아니라 사용자의 문제다. 그리고 그 문제가 해결되었음을 판정할 수 있는 두 가지 기준을 명시한다.

• SC (Success Criteria) — 이 기능이 성공했다고 말할 수 있는 측정 가능한 조건
• AC (Acceptance Criteria) — 개별 시나리오가 수용되기 위한 구체적 완료 조건

스펙에는 명확한 경계가 필요하다. 경계가 있어야 구현이 가능하고, AI가 폭주할 공간이 사라진다. 목표·SC·AC 세 가지가 AI 폭주를 막는 1차 방어선이다.

3.3 Clarify — 모호함은 명세 단계에서 죽인다

plan이 불분명하면 task도 불분명해진다. 모호함은 파이프라인을 타고 내려가며 증폭되므로, 가장 싼 단계인 명세에서 제거해야 한다. Spec Kit은 모호한 지점에 NEEDS CLARIFICATION 마커를 남기는데, PowerShell에서 다음처럼 한 번에 찾을 수 있다.

Select-String -Path specs/001-todo-cli/spec.md -Pattern "NEEDS CLARIFICATION"

마커가 남아 있다면 /speckit.clarify를 돌려 구조화된 질문으로 해소한다. clarify는 새 문서를 만드는 것이 아니라 spec.md 자체를 수정한다.

3.4 Plan · Tasks · Analyze · Implement

• plan.md — 기술 스택, 구현 버전 정보, 클린 아키텍처(Clean Architecture) 기준의 물리적 구조를 담는다.
• tasks.md — 작업은 너무 크지도, 너무 작지도 않게 분리한다. 대부분의 버그는 이 분해 품질에서 갈린다.
• analyze — spec·plan·tasks 간 정합성을 교차 검증한다. 한 번으로 끝내지 말고 재귀적으로(불일치 수정 → 재분석) 돌리는 것이 요령이다.
• implement — phase 1~N으로 나눠 단계별로 구현한다. 여러 단계를 한꺼번에 밀어붙이는 Cascade 진행은 비권장이다. phase마다 테스트가 통과하는 것을 확인하고 다음으로 넘어간다.

구현 검증은 익숙한 도구 그대로다.

uv run pytest -v

4. AI 폭주를 막는 테스트 전략 — Test First

행위와 평가를 분리하는 가장 구체적인 도구가 Test First, 즉 TDD(Test-Driven Development)다. 순서가 핵심이다: 테스트(기준)를 먼저 작성하고 AI가 그 기준을 통과하는 코드를 만들게 한다. 반대로 코드를 먼저 만들고 테스트를 붙이면, AI는 자신이 만든 코드에 맞는 테스트를 만들어 버린다 — 평가가 행위에 종속되는 순간 통제는 사라진다.

테스트는 층위별로 역할이 다르다.

테스트	역할	시점
Unit (TDD)	개별 로직이 AC를 만족하는지 검증	구현과 동시 (Test First)
Smoke test	빌드·기동·핵심 경로가 살아 있는지 최소 확인	phase 완료 시마다
E2E test	사용자 시나리오 전체가 SC를 만족하는지 검증	구현 완료 후, 배포 전

여기에 한 가지 축이 더 있다. 에이전트 세션의 생애주기(lifecycle)에 콜백(callback)처럼 걸어 두는 훅(hook)이다. VS Code의 Agent Hooks(Preview)를 쓰면 에이전트가 도구를 실행하기 전후 등 주요 시점에 커스텀 셸 명령을 실행해 자동 검증·정책 강제를 걸 수 있다. 사람이 지켜보지 않아도 규칙이 집행되는, 하네스 엔지니어링의 실체다.

Agent hooks in Visual Studio Code (Preview)

5. 프로젝트 구조 — 세 개의 디렉토리가 하는 일

GitHub Copilot 기준으로 Spec Kit 프로젝트(specify init 실행 후)는 세 영역으로 나뉜다. AI coding Agent와 LLM 사이의 계약이 이 파일들에 담긴다.

디렉토리	내용물	역할
.github/	prompts(슬래시 명령), agents, copilot-instructions.md	에이전트의 행동 규칙(rule)과 명령 정의
.specify/	memory/constitution.md, templates/, scripts/	공적 규칙(public rule) — TDD 강제 등 AI 폭주 방지 장치
specs/	기능 브랜치별 spec.md, plan.md, tasks.md	기능 단위의 살아 있는 명세

specs/ 아래 각 파일의 책임을 다시 정리하면 이렇다.

• spec.md — 사용자 시나리오, 비즈니스 로직, 그리고 AC·SC의 명확한 완료 기준. clarify의 수정 대상.
• plan.md — 기술 스택, 구현 버전 정보, 클린 아키텍처 기반 물리적 구조.
• tasks.md — 적정 크기로 분해된 작업 목록. 재귀적 analyze를 거쳐 implement로.

6. 그린필드 vs 브라운필드 — 같은 SDD, 다른 전략

그린필드(Greenfield) 개발은 기존 시스템·프레임워크·제약에 의존하지 않고 프로젝트를 처음부터 시작하는 것이고, 브라운필드(Brownfield) 개발은 기존(legacy) 시스템을 개선·업그레이드·확장하는 것이다. SDD는 양쪽 모두에 적용되지만 무게중심이 다르다.

구분	Greenfield (신규)	Brownfield (legacy)
출발점	specify로 시작 (기능 브랜치 생성)	기존 코드 분석 + 기능 명세 역추출
핵심 리스크	방향 상실 (스펙 경계 불명확)	회귀(regression) 문제
테스트 전략	Test First로 처음부터 기준 내장	기존 동작을 고정하는 테스트 먼저, 그 위에 TDD
코드 수정	코드 직접 수정 X — 명세를 고치고 재생성	기존 코드와 명세의 점진적 동기화

그린필드에서 특히 강조되는 원칙이 ‘코드를 직접 수정하지 않는다’이다. 요구사항이 바뀌면 spec을 고치고 파이프라인을 다시 태운다. 또한 AC나 SC가 바뀌면 spec.md는 새 브랜치로 가져간다 — 완료 기준이 달라졌다는 것은 사실상 다른 기능이기 때문이다.

7. 큰 그림 — Transformer에서 VLA까지

마지막으로 이 모든 변화의 기술적 배경을 한 줄로 요약하면 이렇다.

Transformer (2017) → GPT (2022) → VLM (2024) → VLA (2026)

• Transformer(2017) — 모든 것의 출발점. 이후 ViT(Vision Transformer)가 이 구조를 이미지에 이식했다.
• GPT(2022) — text → text. 언어를 다루는 능력이 코딩 에이전트의 기반이 됐다.
• VLM(2024) — text + image → text. 비전-언어 모델이 화면·문서·다이어그램을 이해하기 시작했다.
• VLA(2026) — text + image → action. Vision-Language-Action 모델은 출력이 텍스트가 아니라 행동이다. DeepMind Robotics, NVIDIA GR00T, Physical Intelligence(π)가 이 영역을 이끌고 있다.

소프트웨어 개발자에게 이 계보가 의미하는 바는 분명하다. 에이전트의 행동 반경은 텍스트에서 화면으로, 화면에서 물리 세계로 계속 넓어진다. 행동하는 AI를 통제하는 기술 — 이 글에서 다룬 명세·테스트·하네스 — 의 가치는 그만큼 더 커진다.

8. 마치며

1. AI Native(AE → AS → AN)로 갈수록 사람의 일은 구현에서 기준 설계와 통제로 이동한다.
2. 통제의 핵심은 행위와 평가의 분리 — 목표·SC·AC를 명시하고, Test First로 평가를 행위보다 먼저 세운다.
3. 바이브 코딩이 서비스로 이어지지 못하는 이유는 문서의 부재다. Spec Kit은 명세를 executable PRD로 만들어 이를 해결한다.
4. 파이프라인 운영의 요령: constitution 직접 수정 금지, clarify로 모호함 조기 제거, tasks는 적정 크기, analyze는 재귀적으로, implement는 phase 단위로(Cascade 비권장).
5. 그린필드는 ‘코드 직접 수정 금지’, 브라운필드는 ‘회귀 방지’가 제1원칙이다.

구현은 이미 AI의 것이다. 남은 질문은 하나 — 당신의 팀에는 AI가 통과해야 할 기준이 문서로 존재하는가?