요구사항에서 코드로: 스펙 기반 개발 워크플로우

의도에서 검증된 코드로 이어지는 다섯 가지 단계

Page content

규격 기반 개발(Spec-Driven Development)은 규격이 문서가 아닌 워크플로우일 때 작동합니다. 시작 후 문서로 보관해두는 것이 목적이 아닙니다.

핵심은 인간이나 AI 에이전트가 프로덕션 코드를 변경하기 전에 모호성을 줄이는 각 단계의 검토 가능한 산출물을 순차적으로 진행하는 것입니다.

SDD의 개념적 정의, TDD 및 BDD와의 비교, 그리고 규격을 진실의 원천(source of truth)으로 취급해야 하는 이유에 대해서는 규격 기반 개발이란 무엇인가?를 참조하십시오. 이 앱 아키텍처 문서 클러스터의 기사는 운영 매뉴이드입니다. 여기서는 5가지 단계를 안내하고, 각 산출물에 포함되어야 할 내용을 보여주며, AI 에이전트가 어디에 적합한지 설명하고, 오늘 바로 저장소에 복사하여 사용할 수 있는 재사용 가능한 템플릿을 제공합니다.

규격 기반 개발 워크플로우 – 요구사항, 설계, 작업, 구현, 검증

SDD는 문서가 아니라 워크플로우입니다

규격 기반 개발에서 가장 흔한 실패 유형은 규격을 서류 작업으로 취급하는 것입니다. 팀이 긴 요구사항 문서를 작성하고 위키에 저장한 후, 기억과 채팅 스레드를 기반으로 코딩합니다. 규격은 존재하지만 아무것도 주도하지 않습니다. 이는 문서극(documentation theater)이며, 잘못된 자신감을 심어주기 때문에 규격이 없는 것보다 더 나쁩니다.

작동하는 SDD 워크플로우에서는 다음 단계가 시작되기 전에 각 단계가 검토되는 산출물의 연쇄를 생성합니다. 요구사항은 제품적 모호성을 줄입니다. 설계는 기술적 모호성을 줄입니다. 작업은 실행적 모호성을 줄입니다. 구현은 알려진 타겟에 대해 코드를 생성합니다. 검증은 이 연쇄가 유지되었음을 입증합니다. 어떤 단계에서 실수가 드러나면, 해당 지점에서 산출물을 수정하고 다시 실행합니다. 메인 브랜치에 3,000줄의 드리프트(drift)가 적용된 후에 수정하는 것이 아닙니다.

flowchart LR A[규격 정의] --> B[계획] B --> C[작업] C --> D[구현] D --> E[검증] E -->|드리프트 발견| A E -->|배포| F[완료]

이 워크플로우는 도구 중립적입니다. Git의 마크다운 파일로, GitHub Spec Kit, Cursor 플랜, 또는 일반 텍스트 편집자와 철저한 검토자로 실행할 수 있습니다. 중요한 것은 도구의 브랜드가 아니라 시퀀스와 검토 게이트입니다.

1단계 – 요구사항 규격 정의

규격 정의 단계는 해결해야 할 문제와 완성이 된 상태가 무엇인지를 답합니다. 이를 어떻게 구축할지는 고의로 피합니다. 요구사항 규격에서 “Redis 정렬된 집합을 사용하라"고 말하는 순간, 당신은 규격 정의를 멈추고 잘못된 문서에서 설계를 시작하는 것입니다. 구현 내용은 요구사항에서 제외하십시오. 계획에 넣으십시오.

문제 진술 및 사용자

평문으로 문제를 진술하는 단락 하나로 시작하십시오. 영향받는 사용자와 문제의 고통스러운 상황을 명시하십시오. 좋은 문제 진술은 기획 회의에 참여하지 않은 검토자가 제안된 솔루션이 실제로 고통을 해결하는지 결정할 수 있게 해줍니다.

API 속도 제한 기능에 대한 예시:

무료 티어의 API 소비자는 무제한 요청을 보낼 수 있어 비용 급증과 유료 테넌트에 대한 노이시 니버(noisy-neighbor) 영향을 초래합니다. 플랫폼 운영자는 수동 개입 없이도 키별 제한을 강제할 수 있어야 합니다.

목표, 비목표, 수용 기준

목표는 전달할 결과를 설명합니다. 비목표(non-goals)는 명시적으로 수행하지 않을 유혹적인 부수 작업을 설명합니다. 함께 사용하면 AI 도구가 그렇지 않으면 “도움이 되려” 범위 확장하는 경우, 에이전트의 창의성을 제한하는 데 필수적입니다.

섹션	좋은 예시	약한 예시
목표	키별 제한을 초과하는 요청을 HTTP 429로 거부	API를 더 빠르게 만들기
비목표	테넌트별 빌링 대시보드	모든 API 성능 개선
수용 기준	인증되지 않은 요청은 속도 확인 전에 401을 받음	엔드포인트가 보안됨

수용 기준은 각각 적어도 하나의 테스트에 매핑될 만큼 정확해야 합니다. “엔드포인트가 보안됨"은 수용 기준이 아닙니다. “인증되지 않은 요청이 HTTP 401을 받음"은 수용 기준입니다. 구체적인 기준을 작성할 수 없다면, 그 요구사항은 구현하기에는 여전히 너무 모호합니다.

미결정 사항

아직 해결되지 않은 모든 결정을 나열하십시오. 명확하지 않은 질문은 실패의 징후가 아닙니다. 이는 규격 정의 단계가 그 역할을 하고 있다는 증거입니다. 설계 계획을 작성하기 전에 이를 해결하지 않으면, 구현 재작업 과정에서 모호성에 대한 대가를 치르게 됩니다.

최소한의 요구사항 템플릿:

## 문제
[단락 하나: 누가 고통받고, 왜 고통받으며, 어떤 것이 고통을 유발하는지.]

## 사용자
- [주요 사용자 역할]
- [차수 사용자 역할]

## 목표
1. [측정 가능한 결과]
2. [측정 가능한 결과]

## 비목표
- [명시적으로 범위 밖]
- [명시적으로 범위 밖]

## 수용 기준
- [ ] [검증 가능한 동작]
- [ ] [검증 가능한 동작]

## 미결정 사항
- [ ] [기획을 차단하는 질문]

2단계 – 설계 계획

계획 단계는 의도를 기술적 결정으로 번역합니다. Redis 정렬된 집합이 여기에 속하며, 모듈 경계, 스키마 변경, API 계약, 마이그레이션 단계, 보안 제약 조건, 테스트 전략도 포함됩니다. 계획은 요구사항 규격과 프로젝트의 기존 제약 조건(스택 선택, 결정 기록, AGENTS.md 또는 프로젝트 헌장에 저장된 관행)에서 파생됩니다.

아키텍처 및 영향받는 모듈

변경될 모듈, 서비스, 패키지를 명시하고 통합 패턴을 요약하십시오. 기능이 서비스 경계를 가로지르는 경우, 양측의 계약을 문서화하십시오. 에이전트는 계약이 암묵적일 때 API를 환각(hallucinate)합니다. 계획에서 이를 명시적으로 만들면 발명된 엔드포인트와 잘못된 응답 형태를 방지할 수 있습니다.

데이터 모델, API 계약, 마이그레이션

스키마 변경, 새 테이블 또는 필드, 인덱스 요구사항, 후방 호환성 규칙을 문서화하십시오. HTTP API의 경우, 메서드, 경로, 요청 형태, 응답 형태, 오류 코드를 작성하십시오. 이벤트의 경우, 토픽 이름, 페이로드 스키마, 전달 시맨틱스를 작성하십시오. 데이터 모델이 변경될 때 마이그레이션 단계와 롤백 주석을 포함하십시오.

보안, 관찰성, 테스트 전략

보안 제약 조건은 코드 리뷰의 사후thought가 아니라 계획에 속합니다. 인증 요구사항, 권한 부여 규칙, 입력 검증 경계, 로그에 나타나서는 안 되는 데이터를 기록하십시오. 관찰성은 프로덕션에서 기능이 작동하는지 확인하는 데 필요한 메트릭, 로그, 트레이스를 포괄해야 합니다.

테스트 전략은 수용 기준으로 연결됩니다. 어떤 기준이 단위 테스트가 필요하고, 어떤 것이 통합 테스트가 필요하며, 어떤 것이 수동 검증이 필요한지 식별하십시오. Go 단위 테스트 또는 Python 단위 테스트를 사용하는 경우, 추가할 패키지와 테스트 파일을 명시하십시오. 테스트 전략이 없는 계획은 프로덕션에서 발견할 결함이 있는 상태로 배포될 계획입니다.

flowchart TB subgraph plan [설계 계획 내용] R[요구사항 규격] C[프로젝트 헌장 / ADR] R --> D[아키텍처 결정] C --> D D --> M[데이터 모델 및 마이그레이션] D --> A[API 계약] D --> S[보안 제약 조건] D --> T[테스트 전략] end

3단계 – 구현 작업 분해

작업 단계는 계획을 독립적으로 구현, 검토, 검증할 수 있을 만큼 작은 조각으로 분해합니다. 이것이 에이전트 지원 개발을 검토 가능하게 만드는 것입니다. 거대한 diff 하나 대신, 명명된 요구사항으로 되돌아가는 초점 있는 변경의 시퀀스를 얻게 됩니다.

작업 크기 및 의존성

좋은 작업은 제한된 파일 집합을 처리하고, 하나의 에이전트 세션에서 완료되며, 검증 단계로 끝납니다. 작업은 의존성을 명시적으로 선언해야 합니다. 마이그레이션 작업은 새 스키마를 읽는 코드 전에 실행됩니다. 공유 라이브러리 변경은 소비자 전에 실행됩니다. 인증 미들웨어 변경은 새 동작에 의존하는 엔드포인트 전에 실행됩니다.

flowchart TD T1[작업 1 -- 스키마 마이그레이션] --> T2[작업 2 -- 리포지토리 레이어] T2 --> T3[작업 3 -- HTTP 핸들러] T2 --> T4[작업 4 -- 메트릭 계측] T3 --> T5[작업 5 -- 통합 테스트] T4 --> T5

파일, 검증, 검토 체크포인트

각 작업은 변경될 가능성이 있는 파일, 만족하는 수용 기준, 완료 검증 방법을 나열해야 합니다. 검증은 테스트 명령, curl 예시, 또는 복사-붙여넣기 가능한 단계로 설명된 수동 확인일 수 있습니다. 모든 작업은 인간 검토 체크포인트에서 끝납니다. 검토자는 다음 작업이 시작되기 전에 diff가 작업 설명과 일치하는지 확인합니다.

최소한의 작업 항목:

### 작업 3 -- 속도 제한 미들웨어 추가

**의존성:** 작업 1 (스키마), 작업 2 (리포지토리)
**파일:** middleware/ratelimit.go, middleware/ratelimit_test.go, server.go
**만족:** AC-2 (제한 초과 시 429), AC-3 (응답에 제한 헤더 포함)
**검증:** `go test ./middleware/...` 통과; curl로 제한 초과 시 Retry-After와 함께 429 반환
**검토 체크포인트:** 미들웨어가 인증 이후, 핸들러 이전에 실행되는지 확인

생성된 작업의 폭발에 주의하십시오. AI 에이전트는 몇 초 만에 50개 작업 계획을 생성할 수 있습니다. 이러한 작업의 대부분은 중복되거나 효율적으로 검토하기에 너무 세분화되어 있습니다. 중간 크기 기능에 유용한 작업 목록은 50개가 아니라 5개에서 15개 항목을 가집니다.

4단계 – 한 번에 하나의 작업 구현

구현은 의도적으로 좁습니다. 하나의 작업을 선택하고, 에이전트에게 그 작업에 필요한 컨텍스트만 제공하며, 검증이 통과하면 멈춥니다. 작업 간 컨텍스트 리셋은 버그가 아니라 기능입니다. 이는 이전 가정들이 이후 작업을 오염시키는 것을 방지하고 diff를 검토 가능하게 유지합니다.

규격 스택에서 제약 조건 적용

구현 에이전트는 요구사항 규격, 설계 계획, 현재 작업 설명, 프로젝트 수준 제약 조건을 읽어야 합니다. 제약 조건은 대부분의 팀이 건너뛰는 가장 높은 ROI 섹션입니다. 이는 에이전트에게 무엇을 해서는 안 되는지 알려줍니다 – 관련 없는 모듈을 리팩토링하지 마십시오, 이 기능 외부에서 공개 API 시그니처를 변경하지 마십시오, 계획 업데이트 없이 새 의존성을 도입하지 마십시오.

현실이 다를 때 계획 업데이트

구현은 놀라움을 표면화할 것입니다. 라이브러리가 가정된 동작을 지원하지 않습니다. 마이그레이션이 예상보다 오래 걸립니다. 수용 기준에서 누락된 엣지 케이스가 있습니다. 그러한 일이 발생하면 계속하기 전에 규격을 업데이트하십시오. 요구사항이나 계획을 수정하고, 빠른 검토를 받은 후, 수정된 산출물에 대해 구현을 재개하십시오. 규격과 침묵하게 벗어나는 코드는 드리프트가 영구적이 되는 방법입니다.

sequenceDiagram participant H as 인간 검토자 participant A as AI 에이전트 participant S as 규격 산출물 H->>S: 작업 N 승인 A->>S: 작업 + 계획 + 제약 조건 읽기 A->>A: 작업 N 구현 A->>A: 작업 검증 실행 A->>H: 검토를 위해 diff 제출 H->>H: 작업에 대해 diff 검토 alt 드리프트 또는 놀라움 H->>S: 규격/계획 업데이트 H->>A: 수정된 컨텍스트로 재실행 else 승인 H->>S: 작업 N 완료로 표시 H->>A: 작업 N+1으로 진행 end

5단계 – 규격에 대해 검증

검증은 SDD가 그 대가를 갚는 곳입니다. 검증이 없으면 규격은 단지 기획 연습일 뿐입니다. 검증이 있으면 규격은 배포된 코드에 대해 확인할 수 있는 계약이 됩니다.

자동화된 확인

CI에서 전체 테스트 스위트, 린트, 타입 확인을 실행하십시오. 실용적인 시작점이 필요하다면 GitHub Actions 치트시트의 패턴을 사용하여 파이프라인에 연결하십시오. 자동화된 확인은 회귀를 잡습니다. 그러나 올바르게 구축된 잘못된 기능은 잡지 못하므로, 수용 기준 검토는 여전히 중요합니다.

수용 기준 및 수동 검토

요구사항 규격의 각 수용 기준을 walkthrough하십시오. 각 기준을 만족, 실패, 또는 정당화과 함께 유보로 표시하십시오. 수동 검토는 테스트가 결함이 있는 규격에 맞춰 작성되어 놓친 UX 문제, 보안 간격, 잘못된 동작을 잡습니다.

규격-코드 diff

최종 검증 단계는 구현을 설계 계획과 비교합니다. 변경된 파일이 계획이 예측한 파일과 일치했습니까? 코드의 아키텍처 결정이 기록된 결정과 일치했습니까? diff의 예상치 못한 파일은 신호입니다 – 계획이 불완전했거나 에이전트가 방황했다는 의미입니다. 둘 다 병합 전에 주의가 필요합니다.

검증 레이어	잡는 것
단위 및 통합 테스트	범위 내의 회귀 및 논리적 오류
린트 및 타입 확인	스타일 문제 및 타입 오류
수용 기준 walkthrough	규격에 맞게 구축된 잘못된 동작
규격-코드 diff	아키텍처 드리프트 및 범위 크리프

워크플로우에서 AI 에이전트의 역할

AI 에이전트는 각 단계의 가속기이지만, 검토를 대체하지는 않습니다. 생산적인 패턴은 초안 작성, 검토, 다듬기, 그리고 진행입니다. 에이전트에게 문제 설명에서 요구사항 규격을 초안 작성하도록 요청한 후, 목표, 비목표, 수용 기준이 맞을 때까지 의도를 편집하십시오. 승인된 요구사항에서 설계 계획을 초안 작성하도록 에이전트에게 요청한 후, 코드가 존재하기 전에 아키텍처 결정을 검토하십시오. 에이전트에게 한 번에 하나의 작업 조각을 구현하도록 요청하고, 다음 작업이 시작되기 전에 각 diff를 승인하십시오.

flowchart LR subgraph human [인간 소유] H1[의도 및 우선순위] H2[아키텍처 승인] H3[체크포인트에서의 diff 검토] H4[최종 승인] end subgraph agent [에이전트 가속] A1[요구사항 초안] A2[설계 계획 초안] A3[작업 목록 생성] A4[작업 조각 구현] A5[테스트 초안] end H1 --> A1 --> H1 A1 --> A2 --> H2 H2 --> A3 --> A4 --> H3 H3 --> A4 A4 --> A5 --> H4

에이전트는 초안 및 템플릿 테스트 생성에 특히 유용합니다. 인간은 잘못된 목표, 안전하지 않은 아키텍처, 미묘한 범위 크리프를 잡는 데 특히 유용합니다. 워크플로우는 한쪽이 건너뛰면 실패합니다 – 규격 없이 에이전트가 구현하거나, 인간이 코드의 검증 없이 규격을 작성할 때.

이 워크플로우 기사는 의도적으로 도구 중립을 유지합니다. 도구 특정 실행 가이드(에디터 설정, 슬래시 명령, 에이전트 설정)는 AI 개발 도구 클러스터 아래에 속합니다. 프로세스 기둥은 산출물이 벤더보다 중요하므로 문서화 관행 아래에 여기에서 살아갑니다.

규격 기반 개발을 죽이는 흔한 실수

검증 전의 거대한 규격. 프로토타입 또는 스파이크 전에 작성된 30페이지 요구사항 문서는 SDD가 아니라 워터폴 서류 작업입니다. 다음 단계의 모호성을 제거하는 최소 규격을 작성한 후, 가정을 조기에 검증하십시오. 모든 기능이 5단계 루프 전체를 필요로 하는 것은 아닙니다 – 규격 기반 개발 vs 바이브 코딩에서 가벼운 구조가 충분한 시기를 설명합니다.

모호한 수용 기준. “빠른”, “깨끗한”, “사용자 친화적인"과 같은 형용사는 수용 기준이 아닙니다. 이를 측정 가능한 동작으로 대체하십시오. 테스트할 수 없다면, 신뢰할 수 있게 구현할 수 없습니다 – 특히 AI 에이전트와 함께라면.

비목표 누락. 비목표가 없으면, 에이전트는 기본적으로 범위를 확장합니다. 캐싱 레이어를 추가하고, 이웃 모듈을 리팩토링하며, 요청하지 않은 의존성을 도입합니다. 비목표는 사전에 “아니오"라고 말하는 방법입니다.

설계 단계의 테스트 계획 누락. 구현 후에만 작성된 테스트는 의도된 것을 확인하지 않고 구축된 것을 확인하는 경향이 있습니다. 계획은 첫 번째 프로덕션 파일 변경 전에 어떤 수용 기준이 어떤 테스트 타입에 매핑되는지 명시해야 합니다.

단계 경계에서의 검토 건너뛰기. 계획 전에 규격 검토. 작업 전에 계획 검토. 구현 전에 작업 검토. 각 게이트는 저렴합니다. 대형 병합 후 드리프트 수정은 비쌉니다.

생성된 작업의 폭발 허용. 50개 AI 생성 작업 목록을 일정이 아니라 초안으로 취급하십시오. 중복 항목을 병합하고, 과도하게 큰 항목을 분할하며, 요구사항에 매핑되지 않는 작업을 삭제하십시오.

SDD는 각 단계가 모호성을 줄일 때 작동합니다. 서류 작업을 생성할 때 실패합니다.

재사용 가능한 템플릿

이것들을 저장소에 복사하고 적응하십시오. 기능 브랜치와 함께 규격을 저장하고, 풀 리퀘스트에서 검토하며, 에이전트와 인간이 동일한 소스를 읽도록 버전 컨트롤에 유지하십시오.

요구사항 템플릿

# 기능 -- [이름]

## 문제
## 사용자
## 목표
## 비목표
## 수용 기준
## 미결정 사항

설계 템플릿

# 설계 -- [기능 이름]

## 요약
## 영향받는 모듈
## 데이터 모델 변경
## API 계약
## 마이그레이션
## 보안
## 관찰성
## 테스트 전략
## 위험 및 완화

작업 목록 템플릿

# 작업 -- [기능 이름]

## 작업 1 -- [제목]
의존성:
파일:
만족:
검증:
검토 체크포인트:

## 작업 2 -- [제목]
...

검증 체크리스트

# 검증 -- [기능 이름]

## 자동화
- [ ] 모든 테스트 통과
- [ ] 린트 클린
- [ ] 타입 확인 클린

## 수용 기준
- [ ] AC-1 --
- [ ] AC-2 --

## 규격-코드
- [ ] 변경된 파일이 계획과 일치
- [ ] 문서화되지 않은 아키텍처 변경 없음
- [ ] 구현이 달랐으면 규격 업데이트

결론

규격 기반 개발은 더 많은 문서를 작성하는 것이 아닙니다. 이는 각 단계마다 검토 게이트를 가지고 규격 정의, 계획, 작업, 구현, 검증을 순차적으로 진행하는 것입니다. 각 단계는 이전 단계보다 다음 액터(인간 또는 에이전트)에게 더 적은 추측을 남겨야 합니다.

작게 시작하십시오. 하나의 중간 크기 기능에 전체 워크플로우를 실행하십시오. 저장소의 마크다운에서 산출물을 유지하십시오. 현실이 벗어나면 규격을 업데이트하십시오. 병합 전에 검증하십시오. 연쇄가 작동하면, 드리프트가 적어지고, 검토 가능한 diff가 작아지며, 세션 리셋과 팀 인계에서도 살아남는 내구성 있는 의도 기록을 얻게 됩니다.

연쇄가 서류 작업이 되면, 범위를 줄이십시오 – 검토가 아닙니다. 검증된 2페이지 규격이 읽지 않은 30페이지 규격보다 낫습니다.

유용한 링크

GitHub Spec Kit 문서 – 유사한 규격-계획-작업-구현 루프를 구현하는 오픈소스 툴킷
Martin Fowler의 규격 기반 개발 도구 분석 – Kiro, Spec Kit, Tessl 분석