요구사항부터 코드까지: 스펙 기반 개발 워크플로우

의도에서 검증된 코드로의 5단계

Page content

스팩 주도 개발(Spec-Driven Development, SDD)은 스펙이 문서가 아닌 워크플로우일 때 작동합니다. 핵심은 방대한 제품 요구사항 문서(PRD)를 산출하는 데 있지 않습니다.

핵심은 인간이나 AI 에이전트가 프로덕션 코드를 변경하기 전에 모호성을 단계적으로 줄여나가는 검토 가능한 아티팩트(artifacts)의 시퀀스를 거쳐가는 것입니다.

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

스팩 주도 개발 워크플로우 – 요구사항, 설계, 작업, 구현, 검증

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

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

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

flowchart LR A[Specify] --> B[Plan] B --> C[Tasks] C --> D[Implement] D --> E[Validate] E -->|drift found| A E -->|ship| F[Done]

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

1단계 – 요구사항 Specify하기

Specify 단계는 해결하려는 문제와 ‘완료’된 상태가 어떤 모습인지에 대한 답을 찾습니다. 어떻게 구축할지는 의도적으로 배제합니다. 요구사항 스펙에 “Redis 정렬된 집합(sorted sets)을 사용하라"라고 쓰는 순간, 당신은 스펙을 정의하는 것을 멈추고 잘못된 문서에서 설계를 시작하게 됩니다. 구현 내용은 요구사항에서 제외하십시오. 계획(plan)에 넣으십시오.

문제 진술과 사용자

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

API 속도 제한(rate-limiting) 기능의 예시:

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

목표, 비목표(Non-goals), 수용 기준(Acceptance Criteria)

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

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

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

미결정 사항(Open Questions)

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

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

## Problem
[단락 하나: 누가 고통받고 있는지, 왜, 그리고 어떤 것이 고통을 유발하는지.]

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

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

## Non-goals
- [명확히 범위 제외]
- [명확히 범위 제외]

## Acceptance criteria
- [ ] [검증 가능한 행동]
- [ ] [검증 가능한 행동]

## Open questions
- [ ] [기획을 막는 질문]

2단계 – 설계 Plan하기

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

아키텍처와 영향받는 모듈

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

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

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

보안, 관찰성(Observability), 테스트 전략

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

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

flowchart TB subgraph plan [Design plan contents] R[Requirements spec] C[Project constitution / ADRs] R --> D[Architecture decisions] C --> D D --> M[Data model and migrations] D --> A[API contracts] D --> S[Security constraints] D --> T[Test strategy] end

3단계 – 구현 작업(Task) 분해

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

작업 크기 및 의존성

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

flowchart TD T1[Task 1 -- schema migration] --> T2[Task 2 -- repository layer] T2 --> T3[Task 3 -- HTTP handler] T2 --> T4[Task 4 -- metrics instrumentation] T3 --> T5[Task 5 -- integration tests] T4 --> T5

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

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

최소한의 작업 항목:

### Task 3 -- Add rate-limit middleware

**Depends on:** Task 1 (schema), Task 2 (repository)
**Files:** middleware/ratelimit.go, middleware/ratelimit_test.go, server.go
**Satisfies:** AC-2 (429 over limit), AC-3 (limit headers in response)
**Validate:** `go test ./middleware/...` passes; curl over limit returns 429 with Retry-After
**Review checkpoint:** Confirm middleware runs after auth, before handler

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

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

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

스펙 스택에서 제약 조건 적용

구현 에이전트는 요구사항 스펙, 설계 계획, 현재 작업 설명, 프로젝트 수준 제약 조건을 읽어야 합니다. 제약 조건은 대부분의 팀이 건너뛰는 가장 높은 투자 대비 수익(ROI) 섹션입니다. 이는 에이전트에게 무엇을 하지 말아야 하는지 알려줍니다 – 관련 없는 모듈을 리팩토링하지 말 것, 이 기능 외부에서 공개 API 시그니처를 변경하지 말 것, 계획을 업데이트하지 않고 새 의존성을 도입하지 말 것 등.

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

구현은 놀라움을 표출합니다. 라이브러리가 가정된 동작을 지원하지 않습니다. 마이그레이션이 예상보다 오래 걸립니다. 수용 기준에서 엣지 케이스가 누락되었습니다. 그럴 때, 계속하기 전에 스펙을 업데이트하십시오. 요구사항이나 계획을 수정하고, 빠른 리뷰를 받은 후, 수정된 아티팩트에 대해 구현을 재개하십시오. 스펙과 침묵하게 벗어나는 코드가 드리프트를 영구적으로 만듭니다.

sequenceDiagram participant H as Human reviewer participant A as AI agent participant S as Spec artifacts H->>S: Approve task N A->>S: Read task + plan + constraints A->>A: Implement task N A->>A: Run task validation A->>H: Submit diff for review H->>H: Review diff against task alt drift or surprise H->>S: Update spec/plan H->>A: Re-run with corrected context else approved H->>S: Mark task N complete H->>A: Proceed to task N+1 end

5단계 – 스펙에 대해 검증

검증은 SDD가 그 가치를 증명하는 곳입니다. 검증이 없으면 스펙은 단지 계획 연습일 뿐입니다. 검증이 있으면, 스펙은 출시된 코드에 대해 확인할 수 있는 계약이 됩니다.

자동화된 체크

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

수용 기준 및 수동 리뷰

요구사항 스펙의 각 수용 기준을 검토합니다. 각각을 만족, 실패, 또는 정당성을 갖춘 보류로 표시합니다. 수동 리뷰는 테스트가 결함이 있는 스펙을 맞추기 위해 작성되어 누락된 UX 문제, 보안 격차, 잘못된 행동을 포착합니다.

스펙-코드 Diff

최종 검증 단계는 구현을 설계 계획과 비교합니다. 변경된 파일이 계획이 예측한 파일과 일치했나요? 코드의 아키텍처 결정이 기록된 결정과 일치했나요? diff의 예상치 못한 파일은 신호입니다 – 계획이 불완전했거나 에이전트가 방황했다는 의미입니다. 둘 다 병합 전에 주의가 필요합니다. AI 개발에서 스펙, 테스트, 코드의 동기화 유지는 이 일회성 diff 리뷰를 반복 가능한 추적 테이블과 CI 체크 세트로 변환하여, 드리프트가 누군가 기억할 때만 아닌 모든 PR에서 포착되도록 합니다.

검증 레이어	포착 대상
단위 및 통합 테스트	범위 내 회귀 및 논리 오류
린트 및 타입 체크	스타일 문제 및 타입 오류
수용 기준 검토	스펙대로 구축된 잘못된 행동
스펙-코드 diff	아키텍처 드리프트 및 범위 크리프

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

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

flowchart LR subgraph human [Human owns] H1[Intent and priorities] H2[Architecture approval] H3[Diff review at checkpoints] H4[Final acceptance] end subgraph agent [Agent accelerates] A1[Draft requirements] A2[Draft design plan] A3[Generate task list] A4[Implement task slices] A5[Draft tests] end H1 --> A1 --> H1 A1 --> A2 --> H2 H2 --> A3 --> A4 --> H3 H3 --> A4 A4 --> A5 --> H4

에이전트는 초안 및 부트스트랩 테스트 생성에 특히 유용합니다. 인간은 잘못된 목표, 안전하지 않은 아키텍처, 미묘한 범위 크리프를 포착하는 데 특히 유용합니다. 워크플로우는 어느 한쪽이 건너뛰면 실패합니다 – 에이전트가 스펙 없이 구현하거나, 인간이 스펙을 작성하지만 코드에 대해 결코 검증하지 않을 때.

이 워크플로우 아티클은 의도적으로 도구 중립을 유지합니다. 도구별 실행 가이드(에디터 설정, 슬래시 명령, 에이전트 구성)는 AI 개발 도구 클러스터 하위에 속합니다. 프로세스 기둥은 아티팩트가 벤더보다 중요하기 때문에 문서화 관행 하위에 여기에서 존재합니다.

스펙 주도 개발을 죽이는 공통 실수

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

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

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

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

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

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

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

재사용 가능한 템플릿

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

요구사항 템플릿

# Feature -- [name]

## Problem
## Users
## Goals
## Non-goals
## Acceptance criteria
## Open questions

설계 템플릿

# Design -- [feature name]

## Summary
## Affected modules
## Data model changes
## API contracts
## Migrations
## Security
## Observability
## Test strategy
## Risks and mitigations

작업 목록 템플릿

# Tasks -- [feature name]

## Task 1 -- [title]
Depends on:
Files:
Satisfies:
Validate:
Review checkpoint:

## Task 2 -- [title]
...

검증 체크리스트

# Validation -- [feature name]

## Automated
- [ ] All tests pass
- [ ] Lint clean
- [ ] Type check clean

## Acceptance criteria
- [ ] AC-1 --
- [ ] AC-2 --

## Spec-to-code
- [ ] Changed files match plan
- [ ] No undocumented architectural changes
- [ ] Spec updated if implementation differed

결론

스팩 주도 개발은 더 많은 문서를 작성하는 것이 아닙니다. 각 단계에 검토 게이트를 두고 specify, plan, task, implement, validate를 거쳐가는 것입니다. 각 단계는 이전 단계보다 다음 행위자(인간 또는 에이전트)에게 더 적은 추측을 남겨야 합니다.

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

연쇄가 서류 작업이 될 때, 검토가 아닌 범위를 줄이십시오. 검증된 2페이지 스펙은 아무도 읽지 않는 30페이지 스펙보다 낫습니다.

유용한 링크

GitHub Spec Kit 문서 – 유사한 specify-plan-tasks-implement 루프를 구현하는 오픈 소스 툴킷
Martin Fowler의 스펙 주도 개발 도구 분석 – Kiro, Spec Kit, Tessl에 대한 분석