GitHub SpecKit: AI 코딩, 이제 대충 시키지 마세요! 100배 똑똑하게 쓰는 4단계 비법

 

 

AI 코딩, 왜 자꾸 에러가 날까요? '바이브 코딩'의 문제점은 무엇일까요?

 

깃허브가 개발자들을 위한 아주 멋진 새 오픈소스 도구를 내놓았어요. 이름은 바로 SpecKit(스펙킷)이죠 . 이 도구는 우리가 흔히 하던 AI 코딩 방식의 문제점을 해결하기 위해 만들어졌어요. 기존에는 AI 에이전트에게 "이거 만들어줘" 하고 프롬프트만 던지는 경우가 많았죠 .

 

이런 방식을 '바이브 코딩(Vive Coding)'이라고 부르기도 해요. 그냥 느낌대로 대충 시키고 코드가 잘 작동하기를 바라는 방식이죠 . 하지만 이렇게 하면 AI가 만든 코드에 오류가 많거나, 엉뚱한 결과(환각)를 내놓는 경우가 많았어요 . 결국 개발자가 다시 처음부터 고쳐야 하는 일이 생기곤 했죠.

 

SpecKit은 이런 비효율적인 코딩을 끝내기 위해 등장했어요 . SpecKit은 '설계도를 중심으로 하는 개발(Spec-driven development)'을 핵심 원칙으로 삼아요 . 즉, 개발의 처음부터 끝까지 '명세(Specification, 설계도)'를 가장 중요한 기준으로 두고 AI를 안내하는 방식이랍니다 . 이 설계도는 프로젝트와 함께 발전하며 모든 것을 일관성 있게 유지해주는 '살아있는 실행 가능한 문서'가 되는 것이죠 .

 

 

 

 

SpecKit이 제시하는 '설계도 중심 개발' 4단계는 무엇인가요?

 

SpecKit은 AI 코딩의 정확도와 신뢰성을 높이기 위해 개발 과정을 체계적인 4단계로 나누었어요 . 이 4단계는 마치 건물을 지을 때 설계도를 만들고, 계획을 세우고, 작은 작업으로 나누어 시공하는 과정과 비슷해요. 각 단계마다 명확한 목표와 점검 지점(체크포인트)이 있답니다 .

 

첫 번째 단계는 사양(Specification)이에요. 이 단계에서는 우리가 무엇을 만들고 싶은지, 그리고 이 앱이 사용자에게 어떤 결과를 가져다줄지 목표를 정의해요 .

 

두 번째 단계는 계획(Planning)이죠. 여기서는 어떤 기술 스택(Tech Stack)을 쓸지, 앱의 전체적인 구조(아키텍처)는 어떻게 할지, 그리고 지켜야 할 제약 조건들을 상세하게 매핑해요 . 예를 들어, "최소한의 라이브러리만 사용해라" 같은 제약 조건을 넣을 수 있어요 .

 

세 번째 단계는 태스크(Task) 단계예요. 앞서 세운 계획을 작고 테스트 가능한 단위로 쪼개는 작업이죠 .

 

마지막 네 번째 단계는 구현(Implementation)이에요. 이제 AI가 앞선 세 단계의 설계와 계획을 철저히 따르면서 단계별로 코드를 작성하고 검토를 받는 과정이랍니다 . 이 모든 과정을 거치면, 명세는 단순한 문서가 아니라 더 나은 정렬과 신뢰성을 보장하는 살아있는 결과물이 되는 것이죠 .

 

 

 

---

사전 준비 사항

프로젝트를 시작하기 전에 아래의 필수 도구들을 설치해야 합니다.

• Linux/macOS 또는 Windows의 경우 WSL2
• AI 코딩 에이전트: Claude Code, GitHub Copilot, 또는 Gemini CLI 중 하나
• 패키지 관리 도구 uv (uv는 Python 패키지 관리 도구입니다.)
• Python 3.11+
• Git

---

STEP 1: 프로젝트 초기화

가장 먼저 specify CLI 도구를 사용하여 프로젝트를 초기화합니다. 이 명령어를 통해 spec-kit 템플릿 파일과 필요한 스크립트가 포함된 프로젝트 구조가 생성됩니다.

 

uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

 

 

• <PROJECT_NAME> 부분에 원하는 프로젝트 이름을 입력합니다.
• 현재 디렉터리에 초기화하려면 specify init --here 명령어를 사용합니다.

 

---

STEP 2: 프로젝트 명세(Spec) 작성

 

AI 에이전트를 실행한 후, /specify 명령어를 사용하여 만들고자 하는 애플리케이션의 **"무엇(what)"**과 **"왜(why)"**에 초점을 맞춰 프로젝트의 명세를 상세하게 설명합니다. 이 단계에서는 기술 스택에 대해 언급하지 않는 것이 중요합니다.

 

예시 프롬프트:

 

gemini cli 를 통해 실행해 봅니다.

"/specify 사진을 앨범으로 정리하는 애플리케이션을 만들어줘. 앨범은 날짜별로 그룹화되고, 메인 페이지에서 드래그 앤 드롭으로 재정렬할 수 있어야 해..."

 

 

 

이 프롬프트를 입력하면, AI 에이전트가 요구사항을 분석하여 specs/<feature-name>/spec.md 파일에 사용자 스토리와 기능 요구사항이 포함된 명세 문서를 생성합니다.

---

STEP 3: 기술 구현 계획(Plan) 생성

명세가 완성되면, /plan 명령어를 사용하여 구체적인 기술 스택과 아키텍처를 설명합니다. 이 단계에서는 .NET, Postgres, Blazor, REST API 등과 같은 기술을 명시할 수 있습니다.

 

 

예시 프롬프트:

 

 

"/plan 이 애플리케이션은 .NET Aspire와 Postgres 데이터베이스를 사용해. 프론트엔드는 Blazor Server를 활용하고, REST API를 만들어줘..."

 

 

이 명령어를 실행하면 AI 에이전트가 기술 스택에 맞춰 API 명세, 데이터 모델, 구현 계획 등을 담은 세부 문서를 생성합니다. 이 계획 문서를 통해 불필요한 재작업을 줄일 수 있습니다.

---

STEP 4: 구현 및 검증

마지막으로, /tasks 명령어를 사용하여 AI 에이전트에게 세분화된 작업 목록을 생성하도록 요청하고, 이 목록을 기반으로 실제 코드를 작성하게 합니다.

 

명령어 예시:

 

> /tasks

 

 

 

구현이 완료되면, AI 에이전트에게 애플리케이션을 실행하고 발생한 빌드 또는 런타임 오류를 해결하도록 요청하여 최종적으로 동작하는 애플리케이션을 완성합니다.

 

 

다시 정리하자면,

 

프로젝트를 시작하려면 specify init 같은 명령어를 사용해요. 이때 내가 사용할 AI 코딩 에이전트를 선택해야 하죠 . 깃허브 코파일럿 코드(GitHub Copilot Code)나 제미니 CLI(Gemini CLI) 같은 옵션들이 있어요 . 깃허브 코파일럿이나 클라우드 코드가 specify와 아주 잘 작동한다고 추천하고 있어요 .

 

초기화가 끝나면, VS Code 같은 IDE(통합 개발 환경)에서 프로젝트 폴더를 열고 작업을 시작해요 . SpecKit은 슬래시 명령어(/)를 사용해서 AI에게 명령을 내리도록 설계되었어요 . 예를 들어, 사양을 만들 때는 /sp (specify) 명령어를, 구현 계획을 만들 때는 /pl (plan) 명령어를, 그리고 실제 작업 목록을 만들 때는 /task 명령어를 사용하죠 . 이 명령어들을 사용할 때마다 프로젝트의 핵심 원칙이 담긴 constitution.md 파일이 자동으로 업데이트된답니다 .

 

SpecKit 워크플로우의 첫걸음은 바로 사양(Specification)을 만드는 거예요 . IDE 터미널에서 /sp 명령어를 입력하고, 만들고 싶은 것에 대한 설명을 프롬프트로 넣어주면 되죠 . 여기서 중요한 점이 있어요. 단순히 "이런 기술을 써서 만들어줘"라고 말하는 것이 아니에요.

 

우리는 무엇을(what) 만들 것인지, 그리고 왜(why) 만들 것인지에 초점을 맞춰서 설명해야 해요 . 예를 들어, "사진을 별도의 사진 앨범으로 구성하고 정리할 수 있는 애플리케이션을 만들고 싶다"와 같은 구체적인 목표를 제시하는 것이죠 . AI는 이 설명을 바탕으로 개발자가 따라야 할 구체적인 사양 문서를 생성해 준답니다 .

 

AI가 사양 생성을 완료하면, 우리는 이 문서를 확인해서 AI 에이전트가 어떤 지침을 따를지 정확히 파악할 수 있어요 . 이 사양 파일은 AI가 앞으로의 계획과 구현 작업을 진행하는 데 있어 가장 중요한 기준이 된답니다 . 이처럼 첫 단계부터 명확한 설계도를 만들면, 나중에 코딩 에이전트가 엉뚱한 방향으로 가는 것을 막을 수 있어요.

 

사양 생성이 끝나면 이제 /pl 명령어를 사용해서 2단계인 계획(Planning) 단계로 넘어가요 . 이 단계의 목표는 1단계에서 정한 사양을 실제로 구현하기 위한 상세한 로드맵을 만드는 것이죠 . AI는 이 로드맵에 기술 스택과 아키텍처 같은 기술적인 내용을 포함시켜요 .

 

계획 단계는 AI 코딩의 오류(환각)를 줄이는 데 결정적인 역할을 해요. 이 단계에서 개발자는 제약 조건(Constraints)을 명확히 설정할 수 있어요 . 예를 들어, "바닐라 HTML/CSS만 사용하고 최소한의 라이브러리만 써라"와 같은 규칙을 정하는 것이죠. 이렇게 하면 AI가 따를 규칙이 명확해져서 환각이 발생할 가능성이 훨씬 낮아진답니다 . 또한, 이 계획 단계를 통해 프로젝트 아이디어를 반복적으로 다듬을 수 있어서 토큰 사용량도 줄어드는 이점이 있어요 .

 

계획이 완성되면 /task 명령어를 실행해서 3단계인 태스크(Task) 생성으로 넘어가요 . AI는 앞선 계획에 따라 실행 가능한 작업 목록을 만들고, 이 목록을 작은 단위로 쪼개서 구현을 준비하죠 .

 

이제 4단계 구현(Implementation)에서는 AI가 사양과 계획을 철저히 따르면서 코드를 작성하게 된답니다 . 이 체계적인 워크플로우 덕분에, 단순히 프롬프트만 던져서 전체 앱을 개발하는 방식보다 훨씬 오류가 적고 신뢰성 높은 코드를 얻을 수 있어요 .

 

 

 

 

 

---

 

 

 

다음은 실습으로 spec-kit의 핵심 단계에 맞춰 ASP.NET Core 8 기반의 BOARD 웹사이트를 구현하는 실무적인 가이드입니다.

 

STEP 1: 프로젝트 명세(Spec) 작성 📝

이 단계는 **"무엇(What)"**을 만들 것인지 정의하는 과정입니다. AI 에이전트에게 /specify 명령어를 사용하여 요구사항을 상세하게 설명합니다. 이 단계에서는 기술 스택에 대한 언급을 피하는 것이 중요합니다.

 

실행 가능한 프롬프트 예시:

/specify
사용자가 칸반 보드를 생성하고, 보드 내에 여러 개의 칼럼을 추가할 수 있는 웹 애플리케이션을 개발해줘.
각 칼럼에는 카드를 추가할 수 있어야 하고, 카드는 제목과 상세 설명을 포함해야 해.
사용자는 카드를 한 칼럼에서 다른 칼럼으로 드래그 앤 드롭하여 옮길 수 있어야 하고,
카드의 순서를 변경하는 것도 가능해야 해.
모든 데이터는 영구적으로 저장되어야 하고, 페이지를 새로고침해도 데이터가 유지되어야 해.

 

 

이 프롬프트를 입력하면, AI 에이전트가 이를 바탕으로 spec.md와 같은 명세 문서를 자동으로 생성합니다.

 

---

STEP 2: 기술 계획(Plan) 생성 🛠️

 

명세가 확정된 후, "어떻게(How)" 구현할 것인지 구체적인 기술 계획을 /plan 명령어를 통해 AI 에이전트에게 전달합니다. 이 단계에서 사용자께서 선호하는 ASP.NET Core, Vue.js, CQRS, MSSQL 등 구체적인 기술을 명시합니다.

 

 

실행 가능한 프롬프트 예시:

/plan
이 애플리케이션은 ASP.NET Core 8 Web API를 백엔드로 사용하며,
CQRS 패턴을 적용하여 데이터 조회와 변경 로직을 분리해줘.
데이터베이스는 MSSQL을 사용하고 Entity Framework Core를 ORM으로 활용해줘.
프론트엔드는 Vue.js 3와 Axios를 사용해서 REST API를 호출하도록 구현해줘.
카드의 드래그 앤 드롭 기능은 Vue.js용 라이브러리를 활용하고,
실시간 업데이트를 위해 ASP.NET Core SignalR을 사용한 구현 계획을 포함해줘.

 

 

AI 에이전트는 이 계획을 바탕으로 plan.md, API 명세(예: api-spec.json), 데이터 모델, 아키텍처 다이어그램 등 세부 문서를 생성합니다.

---

STEP 3: 코드 구현 및 검증 🚀

마지막으로, AI 에이전트에게 구체적인 구현 작업을 요청합니다. 이 단계에서는 /tasks 명령어를 통해 계획에 따라 코드를 작성하도록 지시합니다.

실행 가능한 프롬프트 예시:

/tasks
계획 문서에 따라 ASP.NET Core 백엔드와 Vue.js 프론트엔드 코드를 모두 구현해줘.
특히, CQRS 패턴을 적용한 Command와 Query 핸들러를 먼저 작성하고,
이를 사용하는 BoardsController와 CardsController의 API 엔드포인트를 구현해줘.
또한, Vue.js 프로젝트에 API 호출 로직과 UI 컴포넌트(보드, 칼럼, 카드)를 구현해줘.

 

 

이 단계가 완료되면, AI 에이전트가 실제 코드를 생성합니다. 하지만 AI가 생성한 코드는 완벽하지 않을 수 있으므로, 개발자의 역할은 생성된 코드를 검토하고, 빌드 에러나 논리적 오류를 수정하며, 테스트를 통해 안정성을 확보하는 것입니다.

 

이러한 spec-kit 워크플로우를 따르면, 단순 반복적인 코드 작성 시간을 줄이고, 시스템의 전체 아키텍처와 핵심 비즈니스 로직에 더 집중할 수 있습니다.

 

 

 

 

001-kanban-board.zip

0.01MB

 

 

추천 유투브

 

https://www.youtube.com/watch?v=_PeYeRWeQWw