spec-kit.git : Toolkit Spec-Driven Development

 

 

**spec-kit**은 코드를 직접 작성해 주는 라이브러리가 아니라, AI 에이전트를 활용하여 개발 프로세스를 자동화하는 방법론에 가깝습니다. 따라서 spec-kit을 활용한다는 것은 AI 에이전트에게 명확한 지침을 제공하고, 그 결과물을 활용하는 과정을 의미합니다.

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

 

사용자께서 제공하신 가이드 문서는 AI 코딩 에이전트를 활용하여 Spec-Driven Development를 진행하는 방법을 상세하게 설명하고 있습니다. 다음은 해당 문서의 내용을 바탕으로 재구성한 단계별 사용 방법입니다.

---

사전 준비 사항

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

• 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 에이전트에게 애플리케이션을 실행하고 발생한 빌드 또는 런타임 오류를 해결하도록 요청하여 최종적으로 동작하는 애플리케이션을 완성합니다.

 

**spec-kit**은 코드를 직접 작성해 주는 라이브러리가 아니라, AI 에이전트를 활용하여 개발 프로세스를 자동화하는 방법론에 가깝습니다. 따라서 spec-kit을 활용한다는 것은 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