Spec-Driven Development로 개발 효율 2배 높이기

들어가며

이제 단순 CRUD 개발은 AI도 혼자 할 수 있는 시대가 되었습니다. "학생 등록 API 만들어줘"라고 하면, Claude나 GitHub Copilot이 Controller, Service, Repository를 순식간에 생성해줍니다.

하지만 문제는 여기서 시작됩니다.

AI가 생성한 코드는 기술적으로는 완벽할 수 있지만, 비즈니스 요구사항이 명확하지 않으면 다음과 같은 문제가 발생합니다:

조직별 데이터 격리가 필요한데, 일반적인 CRUD 코드만 생성됨
중복 이메일 체크가 필요한데, 조직 내에서만 체크해야 한다는 규칙이 반영되지 않음
소프트 삭제가 필요한데, 물리 삭제 코드가 생성됨

결과적으로 AI가 생성한 코드를 받아서, 비즈니스 요구사항을 하나씩 추가하는 반복 작업이 발생합니다. 이 과정에서 놓치는 요구사항도 생기고, 프론트엔드와 백엔드 간 API 불일치도 발생합니다.

s-class 프로젝트에서는 이런 문제를 해결하기 위해 GitHub Spec-Kit 방법론을 기반으로 한 Spec-Driven Development를 도입했습니다. Spec-Kit은 명세 우선 개발(Spec-First Development)을 위한 4단계 프로세스를 제안하는데, 핵심은 요구사항이 명확해질 때까지 AI와 대화하여 비즈니스 요구사항을 정의한 후, 그 명세에 따라 개발을 시작하는 것입니다.

이번 글에서는 Spec-Kit 방법론을 도입하여 개발 효율과 정확도를 크게 향상시킨 경험을 공유합니다. 특히 "명세 우선 개발"이 어떻게 AI 코딩의 정확도를 높이고, 프론트엔드-백엔드 간 불일치를 줄였는지 구체적인 수치와 함께 설명하겠습니다.

문제 상황: AI 시대의 개발 효율성 문제

기존 방식의 문제점

s-class 프로젝트는 마이크로서비스 아키텍처로 구성되어 있고, 각 서비스는 SpringDoc OpenAPI를 사용하여 API 문서를 자동 생성했습니다. 하지만 다음과 같은 문제가 발생했습니다:

문제점 1: 명세가 코드를 따라감

코드를 먼저 작성하고 나서야 명세가 생성됨 (SpringDoc OpenAPI 자동 생성)
프론트엔드 개발자는 코드가 완성될 때까지 기다려야 함
API 변경 시 명세가 자동으로 바뀌지만, 프론트엔드에 알림이 없음

문제점 2: 비즈니스 요구사항이 명세에 없음

자동 생성된 OpenAPI 스펙에는 기술적인 API 구조만 있고, 비즈니스 규칙(조직별 데이터 격리, 중복 체크 규칙 등)이나 성공 지표가 포함되지 않았습니다.

문제점 3: 서비스 간 계약이 명시적이지 않음

서비스 간 통신 계약이 코드에만 존재하여, 계약 변경 시 다른 서비스에 알림이 없었습니다.

정량적 문제 지표

도입 전 3개월간 데이터를 수집한 결과:

API 불일치로 인한 버그: 월평균 8건
프론트엔드-백엔드 협업 시간: API 하나당 평균 2시간 (명세 확인 + 구현 + 테스트)
리팩토링으로 인한 API 변경: 월평균 5건, 각각 평균 1시간 소요
서비스 간 계약 불일치: 월평균 2건, 각각 평균 3시간 소요

총 월간 손실 시간: 약 40시간 (API 불일치 8건 × 2시간 + 리팩토링 5건 × 1시간 + 계약 불일치 2건 × 3시간 + 기타)

해결책: GitHub Spec-Kit 방법론 도입

Spec-Kit이란?

spec kit

GitHub Spec-Kit은 명세 우선 개발(Spec-First Development)을 위한 방법론으로, 다음과 같은 4단계 프로세스를 제안합니다:

Specify: 무엇(what)과 왜(why)에 집중한 명세 작성
Plan: 기술 스택, 아키텍처, 제약조건 명시
Tasks: 검토 가능한 작은 작업 단위로 분해
Implement: 명세에 따라 코드 작성

핵심 아이디어

핵심은 "무엇을 만들지"를 먼저 명확히 정의하고, 그에 따라 "어떻게 만들지"를 결정하는 것입니다.

특히 AI 시대에서는 명확한 명세를 제공할수록 AI가 더 정확한 코드를 생성할 수 있습니다. 단순 CRUD는 AI가 혼자 할 수 있지만, 복잡한 비즈니스 로직이 필요한 경우 요구사항을 명확히 정의하는 것이 필수입니다.

도입 과정

Phase 1: Foundation (1주)

1.1 Constitution 문서 작성

프로젝트 루트에 CONSTITUTION.md를 생성하여 협상 불가능한 핵심 원칙을 정의했습니다.

# S-Class Constitution

## 아키텍처 원칙
1. 헥사고날 아키텍처 준수
2. 도메인 중심 설계
3. 마이크로서비스 독립성 보장

## 기술 스택 제약
- Backend: Kotlin + Spring Boot 3.x
- Database: PostgreSQL
- API Gateway

## 코딩 규칙
- ktlint, detekt 준수
- ULID 사용 (UUID 대신)
- 공통 라이브러리 활용 (common-kotlin-lib)
# S-Class Constitution

## 아키텍처 원칙
1. 헥사고날 아키텍처 준수
2. 도메인 중심 설계
3. 마이크로서비스 독립성 보장

## 기술 스택 제약
- Backend: Kotlin + Spring Boot 3.x
- Database: PostgreSQL
- API Gateway

## 코딩 규칙
- ktlint, detekt 준수
- ULID 사용 (UUID 대신)
- 공통 라이브러리 활용 (common-kotlin-lib)

1.2 Spec 디렉토리 구조 생성

specs/
├── constitution.md              # 프로젝트 원칙
├── GUIDE.md                     # Spec 작성 가이드
├── services/
│   ├── lms-service/
│   │   ├── spec.md              # 서비스 명세서
│   │   └── api-contracts/       # API 계약 정의
│   │       └── student-management.yaml
│   └── ...
└── contracts/
    └── account-to-lms.md        # 서비스 간 계약

Phase 2: API Contract 정의 (2주)

2.1 OpenAPI 스펙을 명세 우선으로 전환

기존에는 코드에서 스펙을 생성했지만, 이제는 스펙을 먼저 작성합니다.

# specs/services/lms-service/api-contracts/student-management.yaml
openapi: 3.1.0
info:
  title: LMS Service - Student Management API
  version: 1.0.0
  description: |
    ## 비즈니스 요구사항
    - 학생 정보는 조직(Organization)별로 격리되어야 함
    - 학생 등록 시 중복 체크 필요 (이메일 기준, 조직 내에서만)
    - 학생 삭제는 소프트 삭제로 처리
    
    ## 성공 지표
    - 학생 등록 성공률: 99% 이상
    - 등록 완료까지 평균 응답 시간: 500ms 이하
    - 중복 등록 시도 감지율: 100%

paths:
  /api/v1/lms/students:
    post:
      summary: 학생 등록
      description: |
        ## 비즈니스 규칙
        - 학생 정보는 현재 사용자의 조직에 자동 할당
        - 동일한 이메일로 중복 등록 불가 (조직 내에서만 체크)
        
        ## 예외 상황
        - 중복 이메일: 400 Bad Request (DUPLICATE_EMAIL)
        - 조직 권한 없음: 403 Forbidden (ORGANIZATION_ACCESS_DENIED)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateStudentRequest'
      responses:
        '201':
          description: 학생 등록 성공
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudentResponse'
# specs/services/lms-service/api-contracts/student-management.yaml
openapi: 3.1.0
info:
  title: LMS Service - Student Management API
  version: 1.0.0
  description: |
    ## 비즈니스 요구사항
    - 학생 정보는 조직(Organization)별로 격리되어야 함
    - 학생 등록 시 중복 체크 필요 (이메일 기준, 조직 내에서만)
    - 학생 삭제는 소프트 삭제로 처리
    
    ## 성공 지표
    - 학생 등록 성공률: 99% 이상
    - 등록 완료까지 평균 응답 시간: 500ms 이하
    - 중복 등록 시도 감지율: 100%

paths:
  /api/v1/lms/students:
    post:
      summary: 학생 등록
      description: |
        ## 비즈니스 규칙
        - 학생 정보는 현재 사용자의 조직에 자동 할당
        - 동일한 이메일로 중복 등록 불가 (조직 내에서만 체크)
        
        ## 예외 상황
        - 중복 이메일: 400 Bad Request (DUPLICATE_EMAIL)
        - 조직 권한 없음: 403 Forbidden (ORGANIZATION_ACCESS_DENIED)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateStudentRequest'
      responses:
        '201':
          description: 학생 등록 성공
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudentResponse'

2.2 Contract Testing 도입

Spring Cloud Contract를 사용하여 서비스 간 계약을 검증합니다.

// specs/contracts/account-to-lms/src/test/kotlin/AccountToLmsContractTest.kt
@SpringBootTest
@AutoConfigureMockMvc
class AccountToLmsContractTest {
    
    @Test
    fun `should return user info when valid userId provided`() {
        // Contract 정의에 따른 테스트
        // Pact 또는 Spring Cloud Contract 사용
    }
}
// specs/contracts/account-to-lms/src/test/kotlin/AccountToLmsContractTest.kt
@SpringBootTest
@AutoConfigureMockMvc
class AccountToLmsContractTest {
    
    @Test
    fun `should return user info when valid userId provided`() {
        // Contract 정의에 따른 테스트
        // Pact 또는 Spring Cloud Contract 사용
    }
}

Phase 3: CI/CD 통합 (1주)

3.1 Spec 검증 파이프라인

GitHub Actions에 Spec 검증 단계를 추가했습니다.

# .github/workflows/spec-validation.yml
name: Spec Validation

on:
  pull_request:
    paths:
      - 'specs/**'

jobs:
  validate-spec:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Validate OpenAPI Specs
        run: |
          npx @stoplight/spectral-cli lint specs/**/*.yaml
      
      - name: Check Spec Completeness
        run: |
          ./scripts/validate-specs.sh
# .github/workflows/spec-validation.yml
name: Spec Validation

on:
  pull_request:
    paths:
      - 'specs/**'

jobs:
  validate-spec:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Validate OpenAPI Specs
        run: |
          npx @stoplight/spectral-cli lint specs/**/*.yaml
      
      - name: Check Spec Completeness
        run: |
          ./scripts/validate-specs.sh

3.2 Contract Testing 자동화

# .github/workflows/contract-test.yml
name: Contract Testing

on:
  pull_request:
    paths:
      - 'specs/contracts/**'

jobs:
  contract-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run Contract Tests
        run: |
          ./gradlew :specs:contracts:test
# .github/workflows/contract-test.yml
name: Contract Testing

on:
  pull_request:
    paths:
      - 'specs/contracts/**'

jobs:
  contract-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run Contract Tests
        run: |
          ./gradlew :specs:contracts:test

도입 후 개선 효과

정량적 개선 지표

도입 후 3개월간 데이터를 수집한 결과:

1. API 불일치 버그 감소

도입 전: 월평균 8건
도입 후: 월평균 1건
개선율: 87.5% 감소 🎉

이유:

명세 우선 개발로 프론트엔드와 백엔드가 동일한 명세를 공유
Contract Testing으로 서비스 간 계약 불일치 조기 발견
CI/CD 파이프라인에서 자동 검증

2. 협업 시간 단축

도입 전: API 하나당 평균 2시간
도입 후: API 하나당 평균 0.8시간
개선율: 60% 단축 ⚡

세부 내역:

명세 확인: 0.5시간 → 0.1시간 (명세가 명확해서)
구현: 1시간 → 0.5시간 (명세가 가이드라인 역할)
테스트: 0.5시간 → 0.2시간 (Contract Test로 자동화)

3. 리팩토링 안정성 향상

도입 전: API 변경 시 평균 1시간 소요 (수동 확인)
도입 후: API 변경 시 평균 0.2시간 소요 (자동 검증)
개선율: 80% 단축 🚀

4. 서비스 간 계약 불일치 제거

도입 전: 월평균 2건, 각각 평균 3시간 소요
도입 후: 월평균 0건
개선율: 100% 제거 ✅

총 월간 시간 절약: 약 32시간 (40시간 → 8시간)

정성적 개선 효과

1. AI 코딩 정확도 향상

명확한 명세를 제공하니 AI 에이전트(Claude, GitHub Copilot)의 코드 생성 정확도가 크게 향상되었습니다.

Before (명세 없이):

개발자가 "학생 등록 API 만들어줘"라고 요청
AI가 일반적인 CRUD 코드 생성
개발자가 코드를 확인하고 비즈니스 요구사항을 하나씩 추가
조직별 격리, 중복 체크, 소프트 삭제 등 반복 수정

After (명세 우선):

요구사항이 명확해질 때까지 AI와 대화하여 비즈니스 요구사항 정의
OpenAPI 스펙 파일로 명세 작성 (비즈니스 규칙, 예외 상황, 성공 지표 포함)
AI에게 명세 파일 제공 → 명세에 맞는 정확한 코드 생성
추가 수정 없이 바로 사용 가능

측정 결과:

AI 코드 생성 후 수정 필요 횟수: 평균 3회 → 0.5회
AI 코드 생성 시간: 평균 10분 → 3분
비즈니스 요구사항 누락: 평균 2건 → 0건

2. 프론트엔드-백엔드 협업 개선

Before:

백엔드가 코드를 먼저 작성하고 나서야 API 스펙이 생성됨
프론트엔드는 백엔드 구현 완료까지 대기해야 함
API 변경 시 프론트엔드에 알림이 없어서 불일치 발생

After:

명세를 먼저 작성하여 프론트엔드와 백엔드가 동일한 명세를 공유
프론트엔드는 명세만 보고 Mock API를 만들어서 먼저 작업 시작 가능
백엔드 구현 완료 후 실제 API로 교체만 하면 됨
병렬 개발로 전체 개발 시간 30% 단축

실제 사례:

학생 관리 API 개발 시, 명세 작성 후 프론트엔드는 Mock API로 작업 시작
백엔드는 명세에 따라 구현하고, Contract Test로 검증
프론트엔드와 백엔드가 동시에 작업하여 전체 개발 시간 단축

3. 문서와 코드 동기화

Before:

코드 변경 → 문서 자동 업데이트 (하지만 프론트엔드는 모름)
문서를 봐도 비즈니스 규칙이 없음
서비스 간 계약이 코드에만 존재

After:

명세 변경 → PR 생성 → 팀 리뷰 → 코드 구현
명세에 비즈니스 규칙, 성공 지표, 예외 상황 모두 포함
서비스 간 계약이 명시적으로 정의되고 검증됨

도입 시 주의사항 및 교훈

1. 초기 투자 시간 필요

Spec-Kit 방법론을 도입하는 데 초기 투자 시간이 필요합니다.

Spec 작성 시간: API 하나당 평균 30분 추가 소요
도구 설정 시간: 초기 1주 소요 (Spectral, Contract Testing 등)
팀 교육 시간: 1주 소요

하지만 장기적으로는 시간을 절약합니다:

월간 시간 절약: 32시간
ROI: 약 2개월 후부터 수익 발생

2. 명세 작성 품질이 중요

명세를 대충 작성하면 오히려 혼란만 가중됩니다.

나쁜 명세 예시:

paths:
  /api/v1/lms/students:
    post:
      summary: 학생 등록
      # 비즈니스 규칙 없음
      # 예외 상황 없음
      # 성공 지표 없음
paths:
  /api/v1/lms/students:
    post:
      summary: 학생 등록
      # 비즈니스 규칙 없음
      # 예외 상황 없음
      # 성공 지표 없음

좋은 명세 예시:

paths:
  /api/v1/lms/students:
    post:
      summary: 학생 등록
      description: |
        ## 비즈니스 규칙
        - 학생 정보는 현재 사용자의 조직에 자동 할당
        - 동일한 이메일로 중복 등록 불가 (조직 내에서만 체크)
        
        ## 성공 지표
        - 등록 성공률: 99% 이상
        - 응답 시간: 500ms 이하
        
        ## 예외 상황
        - 중복 이메일: 400 Bad Request (DUPLICATE_EMAIL)
        - 조직 권한 없음: 403 Forbidden (ORGANIZATION_ACCESS_DENIED)
paths:
  /api/v1/lms/students:
    post:
      summary: 학생 등록
      description: |
        ## 비즈니스 규칙
        - 학생 정보는 현재 사용자의 조직에 자동 할당
        - 동일한 이메일로 중복 등록 불가 (조직 내에서만 체크)
        
        ## 성공 지표
        - 등록 성공률: 99% 이상
        - 응답 시간: 500ms 이하
        
        ## 예외 상황
        - 중복 이메일: 400 Bad Request (DUPLICATE_EMAIL)
        - 조직 권한 없음: 403 Forbidden (ORGANIZATION_ACCESS_DENIED)

3. 점진적 도입 권장

모든 서비스를 한 번에 전환하기보다는, 핵심 서비스부터 시작하는 것을 권장합니다. Spec-Kit 방법론도 점진적 도입을 권장합니다.

우리의 도입 순서:

lms-service (가장 복잡한 서비스) - Pilot
account-service (다른 서비스와 많이 통신)
나머지 서비스 (점진적 확장)

4. 팀 문화 변화 필요

Spec-Kit 방법론은 단순히 도구를 도입하는 것이 아니라, 팀의 개발 문화를 바꾸는 것입니다.

필요한 변화:

명세 작성에 시간 투자하는 것에 대한 인식 전환
명세 리뷰를 코드 리뷰만큼 중요하게 생각
명세 변경 시 팀 전체에 알림

GitHub Spec-Kit 실제 도입 및 사용 방법

s-class 프로젝트에서는 GitHub Spec-Kit의 방법론을 참고하여 실제로 도입했습니다. Spec-Kit CLI를 직접 사용하지 않고, 방법론을 적용하여 자체 스크립트와 템플릿을 만들었습니다.

실제 도입 과정

1. Spec-Kit 디렉토리 구조 생성

# Spec-Kit 구조 생성
mkdir -p memory templates/spec-kit scripts/spec-kit
# Spec-Kit 구조 생성
mkdir -p memory templates/spec-kit scripts/spec-kit

2. Constitution 문서 준비

프로젝트 루트에 이미 CONSTITUTION.md가 있었으므로, Spec-Kit 구조에 맞춰 memory/constitution.md로 복사했습니다:

# Constitution을 memory 디렉토리로 복사
cp CONSTITUTION.md memory/constitution.md
# Constitution을 memory 디렉토리로 복사
cp CONSTITUTION.md memory/constitution.md

3. 템플릿 파일 생성

Spec-Kit의 4단계 프로세스에 맞춰 템플릿을 생성했습니다:

templates/spec-kit/spec-template.md: 기능 명세서 템플릿
templates/spec-kit/plan-template.md: 구현 계획 템플릿
templates/spec-kit/tasks-template.md: 작업 목록 템플릿

4. 기능 생성 스크립트 작성

새로운 기능을 추가할 때마다 Spec-Kit 구조를 자동으로 생성하는 스크립트를 만들었습니다:

#!/bin/bash
# scripts/spec-kit/create-feature.sh

FEATURE_NUMBER=$1
FEATURE_NAME=$2
SPEC_DIR="specs/${FEATURE_NUMBER}-${FEATURE_NAME}"

# 디렉토리 생성
mkdir -p "${SPEC_DIR}/api-contracts"

# 템플릿 파일 복사
cp templates/spec-kit/spec-template.md "${SPEC_DIR}/spec.md"
cp templates/spec-kit/plan-template.md "${SPEC_DIR}/plan.md"
cp templates/spec-kit/tasks-template.md "${SPEC_DIR}/tasks.md"

# README 생성
cat > "${SPEC_DIR}/README.md" << EOF
# ${FEATURE_NUMBER}-${FEATURE_NAME}

이 디렉토리는 ${FEATURE_NAME} 기능의 Spec-Kit 명세서를 포함합니다.

## Spec-Kit 프로세스

1. **Specify**: spec.md 작성
2. **Plan**: plan.md 작성
3. **Tasks**: tasks.md 작성
4. **Implement**: 명세에 따라 코드 작성
EOF
#!/bin/bash
# scripts/spec-kit/create-feature.sh

FEATURE_NUMBER=$1
FEATURE_NAME=$2
SPEC_DIR="specs/${FEATURE_NUMBER}-${FEATURE_NAME}"

# 디렉토리 생성
mkdir -p "${SPEC_DIR}/api-contracts"

# 템플릿 파일 복사
cp templates/spec-kit/spec-template.md "${SPEC_DIR}/spec.md"
cp templates/spec-kit/plan-template.md "${SPEC_DIR}/plan.md"
cp templates/spec-kit/tasks-template.md "${SPEC_DIR}/tasks.md"

# README 생성
cat > "${SPEC_DIR}/README.md" << EOF
# ${FEATURE_NUMBER}-${FEATURE_NAME}

이 디렉토리는 ${FEATURE_NAME} 기능의 Spec-Kit 명세서를 포함합니다.

## Spec-Kit 프로세스

1. **Specify**: spec.md 작성
2. **Plan**: plan.md 작성
3. **Tasks**: tasks.md 작성
4. **Implement**: 명세에 따라 코드 작성
EOF

사용 방법:

./scripts/spec-kit/create-feature.sh {feature-number} {feature-name}

# 예시
./scripts/spec-kit/create-feature.sh 001 create-student-management
./scripts/spec-kit/create-feature.sh {feature-number} {feature-name}

# 예시
./scripts/spec-kit/create-feature.sh 001 create-student-management

이 명령어는 다음 구조를 자동으로 생성합니다:

specs/
└── 001-create-student-management/
    ├── README.md
    ├── spec.md              # 기능 명세서 (템플릿에서 생성)
    ├── plan.md              # 구현 계획 (템플릿에서 생성)
    ├── tasks.md             # 작업 목록 (템플릿에서 생성)
    └── api-contracts/       # API 계약 정의 (OpenAPI)

Spec-Kit 4단계 프로세스 실제 사용

s-class 프로젝트에서는 Spec-Kit의 4단계 프로세스를 수동으로 적용했습니다:

STEP 1: Specify - 명세 작성

spec.md 파일을 열어서 AI 에이전트와 함께 요구사항을 명확히 정의합니다. AI와 대화를 통해 비즈니스 요구사항(조직별 격리, 중복 체크 규칙, 성능 지표 등)을 명확히 한 후 명세서를 작성합니다.

STEP 2: Plan - 계획 수립

plan.md 파일에 기술 스택(Kotlin + Spring Boot 3.x), 아키텍처(헥사고날 아키텍처), 제약조건을 명시합니다.

STEP 3: Tasks - 작업 분해

tasks.md 파일에 도메인 모델 생성 → Repository 인터페이스 정의 → UseCase 구현 → Adapter 구현 → 테스트 작성 순서로 작업을 분해합니다.

STEP 4: Implement - 구현

작업 목록에 따라 AI 에이전트와 함께 명세에 맞는 코드를 작성합니다. 명세 파일을 AI에게 제공하면 비즈니스 규칙이 모두 반영된 정확한 코드를 생성할 수 있습니다.

실제 도입 결과

생성된 구조:

s-class/
├── memory/
│   └── constitution.md          # 프로젝트 핵심 원칙
├── specs/
│   ├── 001-example-feature/     # 예시 기능
│   │   ├── README.md
│   │   ├── spec.md
│   │   ├── plan.md
│   │   ├── tasks.md
│   │   └── api-contracts/
│   └── services/                # 기존 서비스별 명세서
├── templates/
│   └── spec-kit/
│       ├── spec-template.md
│       ├── plan-template.md
│       └── tasks-template.md
├── scripts/
│   └── spec-kit/
│       └── create-feature.sh    # 기능 생성 스크립트
└── SPEC_KIT_USAGE.md            # 사용 가이드

사용 예시:

# 새 기능 생성
$ ./scripts/spec-kit/create-feature.sh 001 create-student-management

Spec-Kit 기능 생성 중...
기능 번호: 001
기능 이름: create-student-management

1. 디렉토리 구조 생성...
✓ 디렉토리 생성 완료: specs/001-create-student-management

2. 템플릿 파일 복사...
✓ spec.md 생성
✓ plan.md 생성
✓ tasks.md 생성
✓ README.md 생성

✅ 기능 생성 완료!
# 새 기능 생성
$ ./scripts/spec-kit/create-feature.sh 001 create-student-management

Spec-Kit 기능 생성 중...
기능 번호: 001
기능 이름: create-student-management

1. 디렉토리 구조 생성...
✓ 디렉토리 생성 완료: specs/001-create-student-management

2. 템플릿 파일 복사...
✓ spec.md 생성
✓ plan.md 생성
✓ tasks.md 생성
✓ README.md 생성

✅ 기능 생성 완료!

이제 specs/001-create-student-management/ 디렉토리에서 Spec-Kit 프로세스를 시작할 수 있습니다.

실제 도입 효과

도입 전:

새 기능 추가 시마다 명세 구조를 수동으로 생성
명세 형식이 일관되지 않음
명세 작성 시간이 오래 걸림

도입 후:

스크립트 한 번 실행으로 명세 구조 자동 생성
템플릿을 통한 일관된 명세 형식
명세 작성 시간 50% 단축 (구조 생성 시간 절약)

측정 결과:

기능 생성 시간: 30분 → 5분 (스크립트 사용)
명세 작성 시간: 2시간 → 1시간 (템플릿 사용)
명세 형식 일관성: 60% → 95%

더 자세한 내용은 GitHub Spec-Kit 공식 문서을 참고하세요.

향후 계획

1. OpenAPI 기반 코드 자동 생성

현재는 명세를 작성하고 수동으로 코드를 작성하지만, 향후 OpenAPI Generator를 사용하여 DTO와 클라이언트 코드를 자동 생성할 계획입니다.

// build.gradle.kts
tasks.register("generateApiFromSpec") {
    doLast {
        exec {
            commandLine(
                "npx", "@openapitools/openapi-generator-cli", "generate",
                "-i", "specs/services/lms-service/api-contracts/student-management.yaml",
                "-g", "kotlin-spring",
                "-o", "lms-service/src/generated/api"
            )
        }
    }
}
// build.gradle.kts
tasks.register("generateApiFromSpec") {
    doLast {
        exec {
            commandLine(
                "npx", "@openapitools/openapi-generator-cli", "generate",
                "-i", "specs/services/lms-service/api-contracts/student-management.yaml",
                "-g", "kotlin-spring",
                "-o", "lms-service/src/generated/api"
            )
        }
    }
}

2. Spec 문서 시각화

Redoc 또는 Swagger UI를 사용하여 Spec 문서를 시각화하고, 팀 전체가 쉽게 접근할 수 있도록 할 계획입니다.

3. Spec 변경 추적

OpenAPI Diff를 사용하여 Spec 변경 사항을 추적하고, Breaking Change를 자동으로 감지할 계획입니다.

결론

GitHub Spec-Kit 방법론을 도입한 결과, s-class 프로젝트에서 다음과 같은 개선을 달성했습니다:

정량적 개선

API 불일치 버그: 87.5% 감소 (월평균 8건 → 1건)
협업 시간: 60% 단축 (API 하나당 2시간 → 0.8시간)
리팩토링 시간: 80% 단축 (1시간 → 0.2시간)
서비스 간 계약 불일치: 100% 제거 (월평균 2건 → 0건)
월간 시간 절약: 약 32시간

정성적 개선

AI 코딩 정확도 향상: 수정 필요 횟수 3회 → 0.5회
프론트엔드-백엔드 협업 개선: 병렬 개발로 전체 개발 시간 30% 단축
문서와 코드 동기화: 명세가 단일 진실의 원천(Single Source of Truth)

핵심 교훈

요구사항이 명확해질 때까지 AI와 대화하여 비즈니스 요구사항을 정의해야 한다 - 명확한 명세가 있을수록 AI가 더 정확한 코드를 생성함
명세는 코드를 따라가는 것이 아니라, 코드가 명세를 따라가야 한다
초기 투자 시간이 필요하지만, 장기적으로는 시간을 절약한다
명세 작성 품질이 중요하다 - 비즈니스 규칙, 성공 지표, 예외 상황을 명시해야 함
점진적 도입이 효과적이다 - 핵심 서비스부터 시작하여 점진적으로 확장
팀 문화 변화가 필요하다 - 명세 작성과 리뷰를 중요하게 생각해야 함

GitHub Spec-Kit 방법론은 단순히 도구를 도입하는 것이 아니라, "무엇을 만들지"를 먼저 명확히 정의하고, 그에 따라 "어떻게 만들지"를 결정하는 사고 방식의 전환입니다. 이런 사고 방식의 전환이 개발 효율과 정확도를 크게 향상시켰고, 앞으로도 계속해서 개선해나갈 계획입니다.

개발자로서의 성찰

이번 Spec-Kit 도입 과정을 통해 깊이 생각해본 것은, 개발자로서 비즈니스를 정확하게 이해하고 명령하기 위해서는 다양한 기술들에 대해 정확히 이해하고, 요구사항을 명확히 구현할 수 있도록 아키텍처를 설계하는 능력이 필요하다는 점입니다.

기술적 이해의 중요성

AI가 코드를 생성해주는 시대가 되었지만, 여전히 개발자가 해야 할 일은 많습니다:

비즈니스 요구사항을 기술적 솔루션으로 변환: "조직별 데이터 격리"라는 요구사항을 헥사고날 아키텍처와 멀티테넌시 패턴으로 구현
아키텍처 설계: 요구사항을 만족하면서도 확장 가능하고 유지보수하기 쉬운 구조 설계
기술 스택 선택: 프로젝트의 제약조건과 요구사항에 맞는 최적의 기술 스택 선택
트레이드오프 이해: 성능 vs 확장성, 일관성 vs 가용성 등 다양한 트레이드오프를 이해하고 결정

아키텍처 설계 능력의 필요성

Spec-Kit을 사용하면서 느낀 점은, 명세를 작성할 때도 아키텍처에 대한 깊은 이해가 필요하다는 것입니다. 헥사고날 아키텍처, 마이크로서비스 아키텍처, 도메인 중심 설계 등을 이해해야 비즈니스 요구사항을 올바른 기술적 솔루션으로 변환할 수 있습니다.

앞으로의 학습 방향

이번 경험을 통해 앞으로 다음과 같은 능력을 더욱 기르고 싶습니다:

비즈니스 도메인 이해: 단순히 기능을 구현하는 것을 넘어, 비즈니스의 본질을 이해하고 기술로 해석하는 능력
아키텍처 패턴 숙지: 다양한 아키텍처 패턴을 이해하고, 상황에 맞게 선택하고 조합하는 능력
기술 스택 깊이 이해: 사용하는 기술의 내부 동작 원리를 이해하여 최적의 설계를 할 수 있는 능력
트레이드오프 판단: 다양한 제약조건과 요구사항 사이에서 최적의 균형을 찾는 능력

AI가 코드를 생성해주는 시대에서도, "무엇을 만들지"를 정의하고 "어떻게 만들지"를 설계하는 것은 여전히 개발자의 역할입니다. 그리고 그 역할을 제대로 수행하기 위해서는 기술에 대한 깊은 이해와 아키텍처 설계 능력이 필수적입니다.

Spec-Kit을 도입하면서 단순히 개발 효율을 높이는 것을 넘어, 비즈니스를 정확하게 이해하고 기술로 구현하는 개발자가 되기 위한 첫걸음을 내딛었다고 생각합니다.

참고 자료:

Spec-Driven Development로 개발 효율 2배 높이기

Spec-Driven Development로 개발 효율 2배 높이기

들어가며

문제 상황: AI 시대의 개발 효율성 문제

기존 방식의 문제점

정량적 문제 지표

해결책: GitHub Spec-Kit 방법론 도입

Spec-Kit이란?

핵심 아이디어

도입 과정

Phase 1: Foundation (1주)

Phase 2: API Contract 정의 (2주)

Phase 3: CI/CD 통합 (1주)

도입 후 개선 효과

정량적 개선 지표

1. API 불일치 버그 감소

2. 협업 시간 단축

3. 리팩토링 안정성 향상

4. 서비스 간 계약 불일치 제거

정성적 개선 효과

1. AI 코딩 정확도 향상

2. 프론트엔드-백엔드 협업 개선

3. 문서와 코드 동기화

도입 시 주의사항 및 교훈

1. 초기 투자 시간 필요

2. 명세 작성 품질이 중요

3. 점진적 도입 권장

4. 팀 문화 변화 필요

GitHub Spec-Kit 실제 도입 및 사용 방법

실제 도입 과정

Spec-Kit 4단계 프로세스 실제 사용

STEP 1: Specify - 명세 작성

STEP 2: Plan - 계획 수립

STEP 3: Tasks - 작업 분해

STEP 4: Implement - 구현

실제 도입 결과

실제 도입 효과

향후 계획

1. OpenAPI 기반 코드 자동 생성

2. Spec 문서 시각화

3. Spec 변경 추적

결론

정량적 개선

정성적 개선

핵심 교훈

개발자로서의 성찰

기술적 이해의 중요성

아키텍처 설계 능력의 필요성

앞으로의 학습 방향

댓글