사양 주도 개발이란 무엇인가요?

Microsoft의 GitHub Copilot, Anthropic의 Claude Code, IBM의 Bob과 같은 AI 툴과 코딩 어시스턴트의 접근성이 높아지면서 코드 생성의 진입 장벽도 낮아졌습니다. 고도화된 AI 모델을 활용하는 LLM 기반 AI 에이전트는 사용자가 입력한 자연어 프롬프트 하나만으로도 언제든 실시간으로 일련의 반복 작업을 수행할 수 있습니다.

소프트웨어 개발에서는 이를 통해 프로토타입, 신규 기능, 단위 테스트 등을 구축하는 개발 워크플로를 최적화하고 자동화할 수 있습니다. 코드를 생성하는 일은 그 어느 때보다 쉬워졌습니다. 하지만 바이브 코더가 반드시 유의해야 할 함정이 있습니다. AI의 성능은 결국 입력받는 지시의 품질을 넘어서지 못한다는 점입니다.

여러분도 실제 현장에서 자신도 모르는 사이 기술 부채를 접한 적이 있을 것입니다. 기술 부채는 바이브 코딩보다 훨씬 이전부터 존재해 왔으며, 속도를 우선시해 지름길을 택할 때 누적되는 소프트웨어 개발의 오랜 문제였습니다. 하지만 바이브 코딩은 생성된 코드를 충분히 이해하거나 검증하지 않은 상태에서도 대량의 코드를 쉽게 만들어낼 수 있게 함으로써 기술 부채를 더욱 빠르게 누적시킵니다. 빠른 출시 압박 때문일 수도 있고, 혹은 바이브 코더가 애초에 기술 부채를 방지할 만큼의 기술적 배경지식을 갖추지 못했기 때문일 수도 있습니다.  

AI 지원 개발 환경에서 기술 부채는 여러 형태로 나타날 수 있습니다.

• 컨텍스트 드리프트는 한 영역의 버그를 수정하는 과정에서 의도치 않게 다른 영역의 기능이 손상되는 현상을 말합니다. 이는 시스템 전체에 대한 충분한 이해 없이 생성된 코드에서 나타나는 대표적인 징후입니다.  
• 파편화 역시 흔히 나타나는 문제입니다. 새로 생성된 기능이 기존 아키텍처 규칙과 일치하지 못하면서 코드베이스의 일관성과 유지보수성이 점차 저하됩니다.  
• 고려해야 할 운영 비용도 있습니다. 생성 과정을 뒷받침할 명확한 사양이 없으면 개발자는 긴 프롬프팅 반복 과정에 빠질 수 있습니다. 이러한 방식은 잘 정의된 사양이 있었다면 애초에 발생하지 않았을 오류를 해결하는 데 수천 개의 토큰을 소모하게 만들 수 있습니다. 

업계의 많은 개발자가 한 번쯤 겪어봤을 법한 상황을 떠올려 보겠습니다. 며칠 또는 몇 주에 걸쳐 새로운 기능을 개발했고, 이제 출시를 눈앞에 두고 있습니다. 그런데 마감일이 다가오면서 압박을 느낀 나머지 AI에 프롬프트를 입력해 일련의 변경 작업을 서둘러 적용하며 마지막 수정을 진행합니다.

Python이든 다른 언어로 작성되었든 생성된 코드의 기능은 사용자 입장에서는 정상적으로 작동하는 것처럼 보일 수 있습니다. 하지만 그 과정에서 여러 보안 취약점이 노출되고, 의존성 충돌이 발생하며, 예외 상황 처리와 테스트는 완전히 누락될 수 있습니다.

사전에 수립된 공식 사양은 누가 코드를 작성하든 관계없이 팀이 소프트웨어 개발 수명 주기(SDLC)의 모든 단계를 관리할 수 있도록 공통 기준을 제공합니다. 

사양 주도 개발에는 사양 유지 관리 수준과 장단점이 서로 다른 다양한 접근 방식과 템플릿이 존재합니다. 어느 하나가 절대적으로 더 우수한 방식이라기보다는, 적절한 선택은 코드베이스와 팀, 그리고 해결하려는 문제의 특성에 따라 달라집니다. 따라서 방식을 선택하기 전에 팀의 요구 사항과 제약 조건을 충분히 고려해야 합니다.

사양 우선 개발에서는 코드가 생성되기 전에 사용자 스토리, 승인 기준 또는 공식 요구사항 문서의 형태로 사양을 먼저 작성합니다. 초기 요구사항을 명확히 정리하고 코드가 생성된 이후에는 사양이 계속 유지 관리되지 않을 수도 있습니다. 소프트웨어가 발전함에 따라 사양이 오래되어 실제 상태와 맞지 않게 될 수 있습니다. 이 방식의 주된 목적은 지속적인 사양 관리 없이도 초기 단계의 명확성을 확보하는 데 있습니다. 이러한 특성 때문에 이 방식은 SDD의 '입문 단계'로 여겨집니다.¹

사양 기반 개발에서는 사양이 소프트웨어와 함께 지속적으로 발전합니다. 요구사항이 변경되고 새로운 기능이 추가되면 사양도 시스템의 현재 상태를 반영하도록 함께 업데이트됩니다. 이러한 방식은 특히 대규모 이니셔티브를 지원하는 프로젝트에서 효과적입니다.

자동화된 테스트는 문서와 구현을 연결하는 가교 역할을 하며, 두 요소가 개발 수명 주기 전반에 걸쳐 일관성을 유지하고 실제로 실행 가능한 상태로 유지되도록 CI/CD 파이프라인에 통합되는 경우가 많습니다. 구조화와 유연성의 균형을 제공한다는 점에서 사양 기반 개발은 대부분의 엔지니어링 팀에 실용적이고 확장 가능한 접근 방식으로 평가됩니다.¹

이 스펙트럼의 가장 극단적인 형태에는 가장 AI 중심적인 접근 방식인 사양 소스 개발이 있습니다. 사양 소스 개발에서는 사양이 변경되면 코드도 자동으로 변경됩니다. 사람이 직접 코드를 리팩터링하는 일은 없습니다.

이처럼 사양에 강력한 권한을 부여하려면 본질적으로 비결정적인 특성을 가진 현재의 AI 코드 생성 파이프라인의 품질과 일관성에 대해 높은 수준의 신뢰가 필요합니다. 실제로는 강력한 사람의 감독이 없다면 엄격성이 떨어질 수 있다는 의미입니다. 이 접근 방식을 도입하기 전에 팀은 기술 스택과 사양 체계의 성숙도, 관련 시스템의 중요도, 그리고 AI가 생성한 결과물을 검증할 수 있는 역량을 신중하게 평가해야 합니다.¹

실제로는 많은 팀이 다음과 같은 하이브리드 접근 방식을 채택합니다.

• 사양을 항상 최신 상태로 유지하기보다는 아키텍처 의사결정 기록(ADR)처럼 버전이 관리되는 누적형 산출물로 취급합니다.
• 의도적으로 역할을 분리하기 위해 이슈 추적기와 같은 외부 시스템을 단일 기준 정보원으로 활용합니다.
• 변경 사항에 대한 엄격한 통제가 중요한 고복잡도 프로젝트나 커뮤니티 중심 프로젝트에서는 과도한 자동화를 지양합니다.

각 접근 방식에는 장점과 한계가 있으며, 특정 모델을 엄격하게 따르는 것보다 상황에 맞는 선택이 더 중요합니다.

사양에 어느 정도의 권한을 부여할지에 따라 효과적인 사양의 형태는 달라질 수 있습니다. 그러나 이 스펙트럼의 중간 지점에 해당하는 사양 기반 개발을 선택한다면, 사양은 시스템이 무엇을 해야 하는지를 명확하고 검증 가능한 형태로 설명해야 합니다. 또한 이러한 사양은 어떻게 구현할 것인지를 너무 이른 단계에서 확정하지 않도록 해줍니다.

사양에는 입력 및 출력 정의, 데이터 스키마, 예외 상황, 성공 기준이 포함될 수 있을 만큼 충분한 수준의 상세함이 필요합니다. 동시에 문제에 대한 이해가 깊어짐에 따라 유연하게 발전시킬 수 있을 만큼 간결해야 합니다. 무엇보다 좋은 사양은 개발 속도를 높여야 합니다. 더 나은 코드를 더 빠르게 작성하는 데 도움이 되지 않거나 오해를 줄여주지 못한다면, 필요 이상으로 상세하게 작성된 것일 수 있습니다. 

효과적인 사양이 실제로 어떤 모습인지 보여주기 위해 사용자 인증 기능의 예를 살펴보겠습니다. 

웹 애플리케이션의 사용자 로그인 기능을 구현하고 있습니다.  
아래 사양을 단일 기준으로 사용하세요.  
여기에 명시되지 않은 요구사항은 추정해서는 안 됩니다. 
 
기능: 사용자 로그인 
 
개요: 
등록된 사용자가 이메일 주소와 비밀번호를 사용해 안전하게 인증할 수 있도록 합니다. 
 
승인 기준: 
1. 로그인 양식은 이메일 주소와 비밀번호를 입력받아야 합니다. 
2. 자격 증명이 유효하면 사용자를 대시보드로 리디렉션해야 합니다. 
3. 자격 증명이 유효하지 않으면 어떤 항목이 잘못되었는지는 명시하지 않고 일반적인 오류 메시지를 표시해야 합니다. 
4. 로그인에 5회 연속 실패하면 계정을 15분 동안 잠가야 합니다. 
5. 비밀번호는 반드시 HTTPS를 통해서만 전송해야 하며, 평문으로 저장해서는 안 됩니다. 
 
범위 제외: 
- 소셜 로그인(OAuth) 
- 2단계 인증 
- 비밀번호 재설정 절차 
 
예외 상황: 
-제출 전에 클라이언트 측에서 빈 입력 필드를 검사해야 합니다. 
- 세션이 만료된 경우 안내 메시지와 함께 로그인 페이지로 리디렉션해야 합니다. 
- JavaScript가 비활성화된 경우에도 양식은 정상적으로 작동해야 합니다. 
승인 기준을 정확히 이해했음을 확인하기 전에는 구현을 시작하지 마세요.

이는 제품 관리자가 작성하는 기능 사양과 유사하지만, 구현에 반드시 포함되어야 하는 사항, 즉 승인 기준과 예외 상황 처리 방식에 더욱 초점을 맞추고 있습니다.

일반적으로 이러한 사양은 GitHub의 프로젝트 리포지토리("repo")에 SPEC.md 또는 /docs/auth-login.md과 같은 Markdown 파일 형태로 저장되며, 코드베이스와 함께 Git으로 버전 관리됩니다. AI 코딩 에이전트는 사용자가 해당 내용을 프롬프트에 붙여넣어 접근할 수도 있고, 보다 바람직하게는 CLI를 통해 파일을 참조한 뒤 프로젝트 디렉터리에서 직접 읽어 들일 수도 있습니다. 예를 들어, "/docs/auth-login.md에 설명된 기능을 구현하세요."와 같은 방식입니다.

자동화 수준이 높은 파이프라인에서는 작업이 시작될 때 사양 파일이 시스템 프롬프트 또는 컨텍스트 윈도우의 일부로 전달되어 에이전트가 작업을 시작하기 전에 필요한 지침을 받게 됩니다.

사양 주도 개발은 시간과 기술 부채를 크게 줄여줄 수 있지만, 지나치게 많은 시간을 '과도한 설계'에 소비할 수도 있다는 점을 기억해야 합니다. 한 달 뒤 삭제될 수도 있는 기능을 위해 단 하나의 JSON 키 이름이나 특정 API 엔드포인트를 두고 3주 동안 논쟁을 벌인다면, 이는 사양 주도 개발의 취지에 어긋납니다.  

발생 가능한 모든 미래 상황을 설계하는 데 지나치게 집중하지 마세요. 완벽하고 '최종적인' 사양보다는 가볍고 지속적으로 발전하는 사양을 우선하세요. 앞으로 나아가는 데 필요한 만큼만 문서화하고, 이를 코드로 빠르게 검증한 뒤 실제 상황 변화에 맞춰 반복적으로 개선하세요. 일반적인 원칙은 사양을 다듬는 비용이 구현 과정에서 발생한 오해를 수정하는 비용보다 항상 낮아야 한다는 것입니다. 그 균형이 뒤바뀌었다면, 더 이상 사양을 다듬기보다 구현을 시작해야 할 시점이라는 신호입니다.

AI 코딩 지원 툴의 등장과 함께 테스트 주도 개발(TDD)과 행동 주도 개발(BDD)은 새로운 흐름인 사양 주도 개발에 영감을 주었습니다. TDD가 테스트를 통해 기대 결과를 정의하도록 하고, BDD가 협업을 통해 동작을 정의하도록 한다면, 사양 주도 개발은 그보다 더 근본적인 질문을 먼저 던집니다. "우리가 무엇을 만들고 있으며, 그것이 누구를 위한 것인지 명확하게 정의했는가?"^2,3

AI 에이전트가 구현 작업에서 더 큰 비중을 담당하게 되면서, 결과물의 품질은 에이전트가 받는 지침의 품질에 직접적으로 좌우됩니다. 잘 작성된 사양은 개발 프로세스를 제약하는 것이 아니라, 현대 소프트웨어 개발 환경에서 개발 속도를 높이는 역할을 합니다.