사양 키트: GitHub의 혁신적인 사양 기반 개발 도구 키트 #

소프트웨어 개발은 항상 근본적인 단절로 인해 어려움을 겪어 왔습니다. 우리가 지정하는 것이 우리가 구축하는 것과 거의 일치하지 않습니다. 요구 사항 문서에는 먼지가 쌓이고, PRD는 며칠 내에 구식이 되며, 최종 제품은 원래 비전과 크게 달라지는 경우가 많습니다.

**Spec Kit**를 입력하세요. 이 스크립트를 완전히 뒤집는 GitHub의 획기적인 오픈 소스 툴킷입니다. 114,000명 이상의 GitHub 스타와 빠른 채택을 통해 Spec Kit는 사양이 작업 구현을 직접 생성하는 실행 가능한 아티팩트가 되는 패러다임인 **사양 중심 개발(SDD)**을 도입합니다.

이 포괄적인 가이드에서는 Spec Kit의 작동 방식, 중요한 이유, 시작 방법 및 혁신적인 잠재력을 보여주는 실제 사례를 살펴보겠습니다.

스펙 키트란 무엇인가요? #

Spec Kit는 사양이 단순한 문서가 아니라 코드를 안내하고 생성하는 실행 가능한 아티팩트인 방법론인 사양 중심 개발을 가능하게 하는 GitHub에서 개발한 오픈 소스 툴킷입니다.

전통적인 개발 워크플로는 다음과 같습니다.

요구사항 → 설계 → 구현 → 테스트 → 배포 
(문서) (문서) (코드) (테스트) (프로덕션) 

사양 키트는 다음과 같이 변경합니다.

사양 → 구현 → 테스트 → 배포 
(실행 가능) (코드) (테스트) (프로덕션) 

사양은 살아 숨쉬며 코드베이스에 직접 연결되는 진실의 소스가 됩니다.

핵심 철학 #

실행 가능한 아티팩트로서의 사양 #

기존 요구 사항 문서와 달리 Spec Kit 사양은 다음과 같습니다.

• 코드와 함께 버전 관리
• AI 에이전트 사용을 위한 기계 판독 가능
• 구현에 대해 자동으로 검증됨
• 사양과 코드 간의 드리프트 추적

AI 네이티브 개발 #

Spec Kit는 AI 시대에 맞춰 설계되었습니다.코딩 에이전트. AI 에이전트가 직접 사용할 수 있는 구조화된 프롬프트와 템플릿을 제공하여 다음을 보장합니다.

• 에이전트 전반에 걸쳐 일관된 출력
• 사양에서 코드까지 추적 가능한 결정
• 자동화된 품질 게이트
• 다중 에이전트 협업 지원

Vibe 코딩을 통한 예측 가능한 결과 #

AI에 프롬프트를 던지고 최선의 결과를 기대하는 “바이브 코딩” 대신 Spec Kit는 엄격한 접근 방식을 시행합니다.

1. 정의 원하는 것(사양)
2. 검증 타당함(헌법)
3. 생성 구현(코드)
4. 사양과 일치하는지 확인(테스트)

시작하기 #

전제 조건 #

• uv - Python 패키지 관리자
• AI 코딩 에이전트(Copilot, Claude Code, Codex CLI 등)
• Git이 설치됨

1단계: CLI 지정 설치 #

``배쉬

uv를 사용하여 설치 #

uv 도구 설치 지정-cli \ –git+https://github.com/github/spec-kit.git@latest에서

설치 확인 #

–version 지정

### 2단계: 프로젝트 초기화 

``배쉬 
# spec-kit으로 새 프로젝트 생성 
init my-awesome-app --integration copilot 지정 

# 프로젝트로 이동 
CD 내 멋진 앱 

# 생성된 프로젝트 구조: 
# ├── .spec-kit/ 
# │ ├── Constitution.md 
# │ ├── 사양/ 
# │ └── 템플릿/ 
# ├── SPEC.md 
# └── README.md 

3단계: 프로젝트 원칙 수립 #

프로젝트 디렉터리에서 코딩 에이전트를 실행하고 /speckit.constitution 명령을 사용합니다.

``배쉬

AI 코딩 에이전트에서: #

/speckit.constitution 다음에 초점을 맞춘 원칙을 만듭니다.

• 코드 품질 기준
• 테스트 요구 사항
• 성능 벤치마크
• 보안 지침
• 문서 기대

그러면 모든 후속 개발 결정을 관리하는 `constitution.md` 파일이 생성됩니다. 

### 4단계: 첫 번째 사양 작성 

빌드하려는 항목을 설명하려면 `/speckit.specify` 명령을 사용하세요. 

``배쉬 
/speckit.specify 다음 기능을 사용하여 사진 정리 애플리케이션을 구축하세요. 
- 사용자는 날짜별로 그룹화된 앨범을 생성할 수 있습니다. 
- 앨범은 드래그 앤 드롭으로 재구성 가능 
- 사진메타데이터 편집 지원 
- 콜라보레이션으로 공유하는 앨범 

사양은 AI 에이전트가 사용할 수 있는 구조화된 문서로 저장됩니다.

사양 키트 작동 방식 #

사양 중심 개발 워크플로 #

┌─────────────────────────────────────────────────────────┐ 
│ 사양 키트 워크플로우 │ 
├─────────────────────────────────────────────────────────┤ 
│ │ 
│ 1. 구성 │ 
│ └─ 프로젝트 원칙 및 지침 정의 │ 
│ │ 
│ 2. 지정 │ 
│ └─ 무엇을 구축할지 설명(어떻게/무엇을/왜, 어떻게 구축하지 않음) │ 
│ │ 
│ 3. 계획 │ 
│ └─ 사양을 실행 가능한 작업으로 세분화 │ 
│ │ 
│ 4. 생성 │ 
│ └─ 사양에서 구현 생성 │ 
│ │ 
│ 5. 검증 │ 
│ └─ 구현이 사양과 일치하는지 확인 │ 
│ │ 
│ 6. 배포 │ 
│ └─ 생산으로 배송 │ 
│ │ 
└─────────────────────────────────────────────────────────┘ 

사양 형식 #

사양은 구조화된 형식을 따릅니다.

``마크다운

사양: 사진첩 관리자 #

요약 #

사진을 날짜 기반 앨범으로 정리하기 위한 웹 애플리케이션입니다.

사용자 스토리 #

1. 사용자로서 날짜별로 그룹화된 앨범을 만들고 싶습니다.
2. 사용자로서 앨범 간에 사진을 드래그 앤 드롭하고 싶습니다.
3. 가사용자입니다. 공동작업자와 앨범을 공유하고 싶습니다.

기술 요구사항 #

• 프레임워크: React + TypeScript
• 상태 관리: Zustand
• 저장공간: 클라우드 동기화를 통한 IndexedDB
• 테스팅: Vitest + 극작가

성공 기준 #

• 앨범 생성, 이름 변경, 삭제 가능
• 드래그 앤 드롭은 데스크탑과 모바일에서 작동합니다.
• 공유 앨범은 여러 장치에서 동기화됩니다.
• 성능: 사진 1,000장에 대해 <100ms

### AI 에이전트 통합 

Spec Kit는 여러 AI 코딩 에이전트와 함께 작동합니다. 

| 에이전트 | 통합방식 | 
|-------|------| 
| GitHub 부조종사 | `/speckit.*` 슬래시 명령 | 
| 코덱스 CLI | `$speckit-*` 명령 | 
| 클로드 코드 | 상담원 프롬프트 템플릿 | 
| 제미니 CLI | 사용자 정의 함수 호출 | 
| 오픈코드 | 기술 정의 | 

## 실제 사례 

### 예시 1: REST API 구축 

``배쉬 
# 사양을 정의합니다 
/speckit.specify 다음을 사용하여 블로그 플랫폼용 REST API를 구축합니다. 
- 게시물에 대한 CRUD 작업 
- JWT를 이용한 사용자 인증 
- 중첩된 댓글 시스템 
- 검색 기능 
- 속도 제한 

# 구현 생성 
/speckit.create 

# 사양에 따라 유효성을 검사합니다. 
/speckit.validate 

예 2: 모바일 앱 만들기 #

``배쉬

사양을 정의합니다 #

/speckit.specify 다음을 사용하여 피트니스 추적 모바일 앱을 구축하세요.

• 운동 라이브러리를 통한 운동 기록
• 진행 차트 및 통계
• 소셜 기능(운동 공유)
• 오프라인 지원
• HealthKit/Google Fit 통합

구현 생성 #

/speckit.create –프레임워크 플러터

### 예시 3: 마이크로서비스 아키텍처 

``배쉬 
# 사양을 정의합니다 
/speckit.specify 다음을 위한 마이크로서비스 아키텍처 설계: 
- 사용자 서비스(인증, 프로필) 
- 주문 서비스(주문, 결제) 
- 재고 서비스(재고, 창고) 
- 알림 서비스(이메일, SMS, 푸시) 
- 라우팅을 위한 API 게이트웨이 

# 구현 생성 
/speckit.plan --아키텍처 마이크로서비스 
/speckit.create --프레임워크 쿠버네티스 

번들: 역할 기반 설정 #

Spec Kit에는 다양한 팀 역할에 맞게 사전 구성된 번들이 포함되어 있습니다.

개발자번들 #

개별 개발자를 위해 최적화됨:

``배쉬 init –bundle 개발자 지정

포함: 
- 단순화된 작업 흐름 
- 빠른 피드백 루프 
- 로컬 우선 개발 

### 팀 번들 

공동 개발을 위해 설계됨: 

``배쉬 
init --bundle 팀 지정 

포함:

• 코드 리뷰 게이트
• 지점 보호 규칙
• 공유 헌법 템플릿

엔터프라이즈 번들 #

대규모 조직의 경우:

``배쉬 init –bundle enterprise 지정

포함: 
- 규정 준수 템플릿 
- 감사 추적 
- 다중 환경 지원 
- 맞춤형 통합 

## 고급 기능 

### 확장 시스템 

Spec Kit는 맞춤형 워크플로를 위한 확장을 지원합니다. 

``배쉬 
# 확장 프로그램 설치 
확장 설치 지정 github/spec-kit-extension-ci 

# 사용자 정의 템플릿 만들기 
템플릿을 지정하고 my-custom-spec을 생성하세요. 

사용자 정의 사전 설정 #

자신만의 사양 사전 설정을 정의하세요.

``yaml

.spec-kit/presets.yaml #

사전 설정: 웹앱: 프레임워크: 반응 상태: 주스탠드 테스트: 비테스트 API 서비스: 프레임워크: fastapi 데이터베이스: postgresql 캐시: 레디스 모바일 앱: 프레임워크: 플러터 상태: 리버포드 테스트: 통합_테스트

### 드리프트 감지 

Spec Kit는 구현이 사양에서 벗어나는 경우를 자동으로 감지합니다. 

``배쉬 
# 스펙 드리프트 확인 
드리프트 체크 지정 

# 드리프트 보고서 보기 
드리프트 보고서 지정 --output html 

보고서에는 다음이 포함됩니다.

• 사양에서 누락된 기능
• 사양에 포함되지 않은 더 이상 사용되지 않는 기능
• 테스트 범위 격차
• 문서 불일치

기존 방식과의 비교 #

사양 키트와 기존 PRD 비교 #

사양 키트와 Agile 사용자 사례 #

모범 사례 #

효과적인 사양 작성 #

1. 어떻게가 아니라 무엇에 집중 - 구현이 아닌 원하는 결과를 설명하세요.
2. 제약사항을 구체적으로 명시하세요 - 성능, 보안, 호환성 요구사항
3. 허용 기준 포함 - 명확한 통과/실패 조건
4. 사양 버전 관리 - 시간 경과에 따른 변경 사항 추적
5. 사양 유지 - 요구 사항이 발전함에 따라 사양 업데이트

CI/CD와 통합 #

``yaml

.github/workflows/spec-validate.yml #

이름: 사양 검증 켜짐: [pull_request]

직업: 검증: 실행: 우분투 최신 단계:

• 용도: actions/checkout@v4
• 이름: 설치 CLI 지정 실행: uv 도구 설치 지정-cli
• 이름: 사양 드리프트 검증 실행: 드리프트 검사 지정
• 이름: 사양 기반 테스트 실행 실행: test –from-spec 지정

### 팀 협업 

- 프로젝트 전반에 걸쳐 구성 템플릿 공유 
- 공통 패턴에 대한 사양 라이브러리 사용 
- 구현 전 사양 검토 
- 사양-코드 추적성 추적 

## 자주 묻는 질문 

### Q: Spec Kit는 무료로 사용할 수 있나요? 

예! Spec Kit는 **MIT 라이선스에 따른 오픈 소스**입니다. 개인 및 상업적 용도로 완전 무료입니다. 

### Q: 어떤 AI 에이전트가 지원되나요? 

사양 키트는 공식적으로 다음을 지원합니다. 
- **GitHub Copilot**(네이티브 통합) 
- **Claude Code**(템플릿을 통해) 
- **Codex CLI**(명령을 통해) 
- **Gemini CLI**(함수 호출을 통해) 
- **OpenCode**(스킬을 통해) 
- 구조화된 사양을 사용할 수 있는 **모든 에이전트** 

### Q: AI 에이전트와 함께 Spec Kit를 사용해야 하나요? 

아니요. Spec Kit는 AI 에이전트를 염두에 두고 설계되었지만 기존의 인간 주도 개발에도 사용할 수 있습니다. 구조화된 사양 형식은 누가 구현하는지에 관계없이 명확성을 향상시킵니다. 

### Q: Spec Kit는 복잡한 프로젝트를 어떻게 처리합니까? 

사양 키트다음을 통해 확장됩니다. 
- **모듈형 사양** - 큰 사양을 관리하기 쉬운 작은 조각으로 나눕니다. 
- **구성** - 복잡한 시스템을 위해 여러 사양을 결합합니다. 
- **계층적 조직** - 상위-하위 사양 관계 
- **종속성 관리** - 사양 상호의존성 추적 

### Q: 기존 문서에서 마이그레이션할 수 있나요? 

예! Spec Kit는 마이그레이션 도구를 제공합니다. 
- Markdown 문서를 사양으로 변환 
- Jira/Linear에서 요구사항 추출 
- PRD를 구조화된 사양으로 변환 
- 사용자 스토리를 사양 형식으로 가져오기 

### Q: 애자일 행사는 어떻습니까? 

Spec Kit는 민첩한 워크플로우와 통합됩니다. 
- 사양은 살아있는 사용자 스토리가 됩니다. 
- 헌법은 팀 작업 계약을 대체합니다. 
- 드리프트 감지는 스프린트 검토를 지원합니다. 
- 사양 검증은 완료 정의를 지원합니다. 

## 결론 

Spec Kit는 소프트웨어 개발에 접근하는 방식의 근본적인 변화를 나타냅니다. 사양을 실행 가능하고 버전 제어 가능하며 AI 소비 가능하게 만들어 우리가 구축하려는 것과 실제로 구축되는 것 사이의 격차를 해소합니다. 

보다 예측 가능한 결과를 원하는 개인 개발자이든, 개발 프로세스를 표준화하려는 팀이든 Spec Kit는 필요한 구조, 유연성 및 AI 기본 기능을 제공합니다. 

GitHub의 지원과 개발자 커뮤니티의 신속한 채택을 통해 Spec Kit는 현대 개발자 툴킷의 필수 도구가 될 준비가 되어 있습니다. 

## 리소스 

- [GitHub 저장소](https://github.com/github/spec-kit) 
- [문서](https://github.github.io/spec-kit/) 
- [시작 가이드](https://github.com/github/spec-kit#getting-started) 
- [확장 마켓플레이스](https://github.com/github/spec-kit/extensions) 
- [커뮤니티 디스코드](https://discord.gg/speckit) 

**출처:** 
- [스펙 키트 GitHub 리포지토리](https://github.com/github/spec-kit) 
- [Spec Kit 공식 문서](https://github.github.io/spec-kit/) 
- [사양 중심 개발 선언문](https://github.com/github/spec-kit/blob/main/docs/manifesto.md) 

--- 

💬 텔레그램에 가입하세요토론 그룹: [t.me/DIBI8_Group](https://t.me/DIBI8_Group)