Spec‑Driven Development 완벽 가이드: 소프트웨어 사양으로 AI Coding Agent 개발 완료하기

코드를 고칠 때마다 AI Coding Agent가 다른 파일을 건드리고, 이전에 합의한 조건을 잊는다면 문제는 프롬프트 길이가 아니라 실행 기준의 부재입니다.

가장 빠른 해결책은 요구사항을 바로 코드로 넘기지 않고, 제약 조건 → Specification → 설계 → 독립 작업 → 검증 증거로 변환하는 것입니다. 이것이 Spec-Driven Development를 실제 개발 흐름에 적용하는 핵심입니다.

이 글을 읽어야 하는 개발자

AI Coding Agent를 사용하지만 매번 결과를 다시 설명해야 하는 개인 개발자에게 적합합니다.
팀 개발에 AI 프로그래밍을 도입하면서 코드 변경의 근거와 승인 기준을 남겨야 하는 기술 책임자도 대상입니다.
테스트 결과와 사양을 연결해 생성 코드의 품질을 감사하려는 개발 조직에도 유용합니다.

프로젝트 규칙과 변경 경계

Spec-Driven Development의 첫 단계는 기능 설명이 아닙니다. Agent가 프로젝트의 바깥 규칙을 벗어나지 않도록 기본 제약 조건을 먼저 고정하는 단계입니다.

다음 항목은 기능마다 반복해서 설명하지 않도록 프로젝트 문서로 남겨야 합니다.

• 사용하는 언어와 주요 프레임워크
• 디렉터리와 파일 이름 규칙
• 테스트, 정적 검사, 빌드 실행 방법
• 인증 정보와 개인정보를 다루는 금지 영역
• 수정하면 안 되는 파일과 외부 인터페이스
• 브랜치, 커밋, 코드 리뷰 규칙
• 완료로 인정할 조건과 실패 시 처리 방법

공식 Spec Kit 흐름에서도 프로젝트의 원칙과 개발 기준을 먼저 constitution.md에 정리한 뒤 기능 사양을 생성하도록 안내합니다. 이후 사양, 계획, 작업 목록, 구현 명령이 단계적으로 이어집니다. 프로젝트 원칙과 핵심 흐름에 대한 공식 설명에서 이 구조를 확인할 수 있습니다. (github.com)

주의: 프로젝트 규칙과 기능 요구사항을 한 문서에 섞으면 수정 범위가 불명확해집니다. 모든 기능에 공통인 규칙은 프로젝트 기준으로 두고, 특정 기능의 조건만 Specification에 넣는 편이 안전합니다.

Specification을 실행 가능한 기준으로 바꾸기

Spec-Driven Development는 어떻게 시작해야 하나요?

처음에는 “로그인 기능을 만들어 달라”처럼 목표만 적지 말고, Agent가 판단할 수 있는 행동 단위로 바꿔야 합니다. 좋은 Specification은 다음 질문에 답합니다.

• 어떤 사용자가 어떤 조건에서 시작하는가
• 입력값은 무엇이며 허용되지 않는 값은 무엇인가
• 성공했을 때 어떤 화면, 응답, 파일 상태가 나와야 하는가
• 네트워크 오류, 권한 부족, 중복 요청이 발생하면 어떻게 처리하는가
• 보안, 접근성, 호환성 같은 비기능 조건은 무엇인가
• 테스트나 수동 확인으로 완료 여부를 어떻게 판단하는가

예를 들어 “사용자가 이메일을 변경할 수 있어야 한다”는 목표만으로는 부족합니다. 다음처럼 작성해야 합니다.

사용자는 본인 계정의 새 이메일을 입력할 수 있습니다.
형식이 올바르지 않으면 저장 요청을 보내지 않습니다.
변경 전 이메일에는 확인 메시지를 보내며, 확인되지 않은 주소는 계정에 반영하지 않습니다.
확인 토큰이 만료되면 기존 이메일을 유지하고 다시 요청할 수 있어야 합니다.

이 문장은 구현 기술을 강제하지 않으면서도 행동, 예외, 상태 변경을 구분합니다. 핵심 조건마다 테스트, 정적 검사, 인터페이스 예시 또는 수동 검토 중 하나의 증거를 연결하면 “완성했다”는 표현을 판정할 수 있습니다.

소프트웨어 사양은 어느 정도로 작성해야 하나요?

Specification은 코드 한 줄을 지시하는 문서가 아닙니다. 반대로 Agent가 여러 해석을 할 수 있는 추상적인 목표만 담아서도 안 됩니다.

다음 기준을 적용하면 적정 수준을 찾기 쉽습니다.

• 구현 방법이 아니라 관찰 가능한 결과를 씁니다.
• 성공 조건과 실패 조건을 함께 씁니다.
• 데이터 형식, 권한, 상태 전이를 빠뜨리지 않습니다.
• 여러 기능이 한 문장에 섞이면 기능 단위로 나눕니다.
• 성능 수치는 실제 측정값이나 제품 요구사항이 있을 때만 넣습니다.
• 검증 방법이 떠오르지 않는 문장은 다시 구체화합니다.

공식 템플릿은 기능 사양을 바탕으로 계획과 작업 목록을 만들도록 설계되어 있으며, 작은 기능 단위로 사양을 나누는 방식도 안내합니다. 각 기능 조각은 별도의 spec.md, plan.md, tasks.md를 가질 수 있어 긴 문서가 Agent의 문맥을 압박하는 문제를 줄입니다. 기능 단위 사양 분할에 대한 공식 설명을 참고할 수 있습니다. (github.com)

설계와 작업 목록의 분리

Specification이 승인되면 AI Coding Agent에게 곧바로 구현을 맡기지 않는 편이 좋습니다. 먼저 기술 설계를 제안하게 하고, 영향 범위를 검토한 뒤 작업 목록을 생성해야 합니다.

설계 단계에서 확인할 항목은 다음과 같습니다.

• 변경 대상 파일과 새로 만들 파일
• 데이터 모델과 외부 인터페이스의 변화
• 기존 기능과의 의존성
• 마이그레이션 또는 하위 호환성 문제
• 테스트 위치와 실행 명령
• 보안상 추가 검토가 필요한 부분

그다음 작업은 한 번에 독립적으로 구현하고 확인할 수 있는 크기로 나눕니다. 화면, 데이터 처리, 인터페이스, 테스트가 모두 한 작업에 들어가면 실패 원인을 찾기 어렵습니다. 반대로 파일 하나의 이름만 바꾸는 수준으로 지나치게 쪼개면 Agent가 전체 목적을 잃을 수 있습니다.

공식 작업 템플릿은 작업마다 순번을 두고, 병렬 실행이 가능한 경우 표시하며, 사용자 이야기와 파일 경로를 함께 기록하도록 요구합니다. 예시는 다음과 같은 형태입니다. 작업 목록 형식에 대한 공식 템플릿 (github.com)

- [ ] T001 [US1] 이메일 변경 입력 검증을 src/account/email.ts에 구현
- [ ] T002 [P] [US1] 만료 토큰 테스트를 tests/account/email.test.ts에 작성

여기서 중요한 점은 작업 설명에 “관련 파일”과 “검증 방법”을 같이 넣는 것입니다. “이메일 변경 기능 구현”보다 “입력 검증을 추가하고 잘못된 형식의 요청이 전송되지 않는 테스트를 실행”이 훨씬 명확합니다.

AI Coding Agent는 사양에 따라 어떻게 작업을 나누나요?

다음 지시 순서를 사용하면 작업 분해의 품질을 일정하게 유지할 수 있습니다.

• 현재 Specification에서 구현 대상 범위를 한 문장으로 요약하게 합니다.
• 변경 예상 파일과 영향받는 인터페이스를 먼저 제시하게 합니다.
• 의존성이 없는 작업과 선행 작업을 구분하게 합니다.
• 각 작업에 완료 조건과 검증 명령을 적게 합니다.
• 한 작업이 여러 모듈을 동시에 바꾸면 더 작은 단위로 다시 나누게 합니다.
• 사람이 승인하기 전에는 코드를 수정하지 않게 합니다.

Spec Kit의 기본 흐름은 specify, plan, tasks, implement로 이어지며, 필요할 때 모호성 확인과 산출물 일관성 분석 단계를 추가할 수 있습니다. 공식 참조 문서의 명령과 단계 설명 (github.com)

작업 단위의 코드 구현

구현 단계에서는 Agent에게 프로젝트 전체를 다시 제공하지 않는 것이 좋습니다. 현재 작업에 필요한 Specification 부분, 관련 파일, 실행할 검증 명령만 전달해야 합니다.

수정 전에는 다음 형식의 응답을 요구할 수 있습니다.

목표:
변경 파일:
변경하지 않을 영역:
구현 순서:
검증 명령:
예상되는 위험:

수정 후에는 반드시 차이를 검토할 수 있는 결과를 남겨야 합니다.

• 변경 파일 목록
• 각 파일의 핵심 변경 내용
• 실행한 테스트와 결과
• 실패한 검사의 원인
• 아직 완료하지 못한 조건
• 다음 작업에 필요한 의존성

이 방식은 Agent가 성공하지 못한 테스트를 숨기거나, 원래 범위를 넘어 리팩터링하는 문제를 줄입니다. 특히 권한, 결제, 파일 삭제, 외부 API 호출처럼 되돌리기 어려운 영역은 자동 실행보다 승인 단계를 앞에 둬야 합니다.

경험상 가장 위험한 요청은 “필요한 부분은 알아서 개선하라”입니다. 개선 범위가 Specification에 없으면 Agent는 품질 향상과 범위 확장을 구분하지 못할 수 있습니다.

검증과 회귀 처리

검증은 구현이 끝난 뒤 새로 만드는 단계가 아닙니다. Specification을 작성할 때부터 각각의 조건에 증거를 연결해야 합니다.

사양 조건	검증 증거	통과하지 못했을 때의 회귀 위치
올바른 입력만 저장 요청을 보냄	단위 테스트와 요청 기록 확인	해당 구현 작업
만료 토큰은 계정을 변경하지 않음	만료 상황 테스트	예외 처리 사양
기존 화면의 저장 흐름을 유지함	회귀 테스트와 수동 확인	영향 분석 또는 설계
권한 없는 사용자가 요청할 수 없음	권한 테스트와 로그 확인	보안 경계 규칙
변경 결과를 검토할 수 있음	차이 검토와 작업 보고서	작업 정의

자동 테스트가 통과해도 원래 사용자 행동을 만족하지 못할 수 있습니다. 따라서 인터페이스 예시와 수동 확인 항목을 함께 두어야 합니다. 반대로 수동 확인만 통과하고 테스트가 부족하면 다음 변경에서 같은 문제가 반복될 가능성이 큽니다.

공식 워크플로 기능은 단계 사이에 사람의 승인 지점을 넣고, 각 단계의 상태를 저장한 뒤 중단된 실행을 이어갈 수 있도록 구성됩니다. 공식 워크플로 문서의 승인 지점과 상태 보존 설명 (github.com)

사양 변경과 버전 관리

요구사항이 바뀌었을 때 기존 코드를 먼저 고치고 문서를 나중에 맞추면 추적성이 사라집니다. 순서는 반대여야 합니다.

• 변경된 사용자 목표를 Specification에 먼저 기록합니다.
• 변경된 조건과 유지해야 할 조건을 구분합니다.
• 영향을 받는 설계, 작업, 테스트를 표시합니다.
• 승인된 변경만 새로운 작업으로 전환합니다.
• 구현 후 기존 사양의 통과 여부와 새 사양의 통과 여부를 모두 확인합니다.
• 더 이상 유효하지 않은 테스트와 문서는 함께 정리합니다.

사양과 코드가 같은 버전 관리 흐름에 들어가면 특정 커밋이 어떤 요구사항을 구현했는지 확인하기 쉬워집니다. 사양 파일의 식별자와 작업 번호를 임의로 바꾸지 않는 규칙도 중요합니다. 그래야 이후 작업과 검증 기록이 과거 변경을 계속 참조할 수 있습니다.

다음 점검 목록은 개인 프로젝트와 팀 프로젝트 모두에 적용할 수 있습니다.

• [ ] 프로젝트 공통 규칙과 기능별 조건을 분리했습니다.
• [ ] 각 주요 조건에 성공과 실패 사례가 있습니다.
• [ ] 모든 핵심 조건에 테스트, 검사 또는 수동 확인 방법이 있습니다.
• [ ] 설계가 먼저 승인되며 구현 작업과 섞이지 않습니다.
• [ ] 작업마다 변경 파일과 종료 조건이 적혀 있습니다.
• [ ] Agent가 수정 전에 계획을 설명하도록 했습니다.
• [ ] 수정 후 차이, 검사 결과, 미완료 항목을 기록합니다.
• [ ] 사양 변경이 설계와 작업 목록에 반영되었는지 확인합니다.
• [ ] 실패 시 임시 프롬프트가 아니라 해당 사양이나 작업으로 되돌아갑니다.
• [ ] 실행 환경을 초기화하고 같은 검증을 다시 수행할 수 있습니다.

실행 환경 선택과 다음 단계

이 흐름을 실제로 운영하려면 버전 관리 저장소뿐 아니라 테스트 도구, 정적 검사 도구, 의존성 설치 환경, 초기화 가능한 실행 환경이 필요합니다. 로컬 장비에서만 실행하면 팀원이 같은 조건을 재현하기 어렵고, 장시간 테스트나 여러 브랜치 검증에서는 환경 충돌이 생길 수 있습니다.

단기 기능 개발, 원격 협업, 반복 테스트가 목적이라면 클라우드 맥 개발 환경과 맥 미니 렌탈 구성을 비교해 볼 수 있습니다. 접속 방식과 운영 조건은 도움말 센터에서 먼저 확인하는 편이 안전합니다.

현재 노트북이나 일반 클라우드 서버로 계속 진행하는 방식은 초기 비용이 낮을 수 있지만, 개발 환경이 팀마다 달라지고 macOS 전용 빌드와 자동화 테스트를 별도로 준비해야 하며, 장시간 실행 중인 작업이 로컬 사용을 방해하는 문제가 생길 수 있습니다. 반면 Zutcloud의 맥 환경을 임대하면 필요한 기간에 격리된 실행 환경을 확보하고, Specification에 기록한 설치 절차와 검증 명령을 반복 적용하기가 더 쉽습니다. 장기간 고정 부하를 계속 처리하거나 물리 장비와 직접 연결해야 한다면 직접 구매가 더 적합하지만, 임시 개발과 재현 가능한 테스트 환경이 목적이라면 임대 방식이 현실적인 선택이 될 수 있습니다.