마이크로소프트와 깃허브는 AI 보조 기능을 소프트웨어 개발 툴의 핵심 요소로 키웠다. 최신 비주얼 스튜디오와 비주얼 스튜디오 코드 릴리스에 내장된 깃허브 코파일럿은 AI 기반 코드 완성, 코딩 에이전트, 다양한 모델 컨텍스트 프로토콜(Model Context Protocol, MCP) 서버가 결합된 다면적인 페어 프로그래머를 편집기 내에서 바로 사용할 수 있게 해준다.

이렇게 만들어진 툴킷은 잘 설계된 애플리케이션 개발 수명 주기의 일부로 사용할 때 특히 빛을 발한다. 그러나 적절한 소프트웨어 엔지니어링의 관행을 따르지 않을 경우 바이브 코딩이 통제를 벗어나 불필요한 기능을 더하거나 코드의 복잡성만 높일 수 있다.

스펙 키트 소개

깃허브는 최근 단순한 코딩 툴 이상을 목표로 하는, AI 보조 애플리케이션 개발에 대한 새로운 접근 방식을 발표했다. 이 접근법은 일련의 설계 원칙으로 시작해 소프트웨어 개발 프로세스의 많은 부분에 대한 지침을 제시한다. 이를 통해 기본 사양에서 실제로 작동하는 프로토타입(모든 종속 항목의 설치와 실행 포함)까지 하루만에 진행할 수 있다.

오픈소스로 제공되는 깃허브 툴 스펙 키트(Spec Kit)는 깃허브 자체의 코파일럿과 같은 AI 코딩 어시스턴트와 호환되도록 설계됐으며, 에이전트 프레임워크에 연결해 명령줄 개발 환경을 제공한다. 목적은 사용자 중심의 바이브 코딩 개념을 기반으로 하되 소프트웨어 엔지니어링 방법론으로 이를 뒷받침하는 것이다. 이 접근 방식은 의도한 대로 작동할지 여부가 불확실한 코드 블록이 아닌 더 우수한 엔드 투 엔드 솔루션을 제공한다.

깃허브 수석 제품 관리자인 덴 델리마스키는 블로그 글에서 이와 관련해 “문제는 코딩 에이전트의 코딩 능력이 아니라 사람들의 접근 방식이다. 흔히 코딩 에이전트를 검색 엔진처럼 다루는데, 이는 잘못된 방식이다. 코딩 에이전트는 상상력 없이 문자 그대로 이해하는 페어 프로그래머처럼 대해야 한다”라고 말했다. 사양 기반 개발의 핵심은 바로 이런 설명을 통해 문자를 있는 그대로 받아들이는 에이전트의 특성을 다루는 것이다.

결국 필요한 것은 코딩 에이전트가 안정적인 엔터프라이즈 소프트웨어를 빌드하는 데 필요한 단계를 캡슐화하는 프레임워크를 사용해서 소프트웨어 개발 베스트 프랙티스에 기반해 작동하도록 하는 방법이다. 이것이 스펙 키트의 역할, 즉 코딩 에이전트를 관리하는 데 필요한 구조를 갖춘 깃 리포지토리를 구축한 다음 일련의 트리거를 통해 개발 프로세스의 다음 단계를 이행하는 것이다.

비주얼 스튜디오 코드에서 스펙 키트 사용하기

이 툴은 윈도우와 유닉스 및 유닉스 계열 개발 환경에서 모두 작동하며 윈도우에서는 파워셸, 유닉스에서는 배시를 사용한다. 필자는 원격 개발 환경에서 스펙 키트가 어떻게 작동하는지 확인할 겸 리눅스용 윈도우 서브시스템을 사용해 실험했다. 먼저 우분투(Ubuntu) WSL 터미널 내에서 스냅(Snap) 패키지 관리자를 사용해 아스트랄(Astral) uv 파이썬 환경을 설치했다.

아스트랄 uv는 러스트 기반 파이썬 프로젝트 관리 툴로, 패키지와 종속 항목의 다운로드를 관리하고 가상 환경을 설정, 관리한다. 필자는 이 도구를 통해 제공된 스크립트를 사용해서 최신 버전의 스펙 키트를 다운로드하고 사양 기반 개발에 필요한 폴더 구조를 설정하고 비주얼 스튜디오 코드 내의 깃허브 코파일럿을 사용해 원하는 코딩 에이전트를 구성할 수 있었다. 스펙 키트를 한 번 실행해서 프로젝트를 위한 템플릿을 설정한 다음 삭제할 수도 있고, 개발 툴체인에 포함하려는 경우에는 설치해서 나중에 사용할 수도 있다.

명령줄 스펙 툴은 대상 디렉토리를 선택하고 단계를 따르기만 하면 간단히 실행할 수 있다. 먼저 대상 경로를 선택한 다음 AI 코딩 어시스턴트를 선택한다. 그러면 툴이 폴더를 생성하고 관련 템플릿을 다운로드한다. 이 과정이 완료되면 사양 기반 개발의 주요 단계가 표시되고 원하는 개발 툴 내에서 사용할 수 있게 된다.

필자는 WSL 내에서 비주얼 스튜디오 코드를 사용 중이었으므로 code 명령을 사용해 원격 서버를 실행했다. 서버가 최신 버전으로 업데이트된 다음 윈도우 버전이 열리면서 WSL 인스턴스에 원격으로 연결할 준비가 됐다. 해당 폴더로 이동한 후 비주얼 스튜디오 코드의 깃허브 코파일럿 사이드바에서 사양 기반 개발 명령을 사용할 수 있었다.

스펙 키트 사용기

사양 프롬프트부터 제공할 수도 있지만 프로젝트를 위한 원칙부터 정의하는 편이 더 합리적이다. 이는 코파일럿 에이전트가 코드를 빌드할 때 따라야 하는 접근 방식을 규정하는 고수준의 원칙 모음으로, 예를 들어 코드가 테스트를 거처 성능에 최적화되도록 보장한다. 개발팀이 원래 갖고 있던 아키텍처 표준을 체계화한다고 생각하면 된다.

원칙이 준비되면 /specify 명령을 사용해 프로젝트를 위한 사양을 작성할 수 있다. 이는 프론트엔드에서 백엔드까지 계획된 애플리케이션을 제공하기 위해 사용되는 전체 스택을 고려해서 무엇을, 왜 빌드해야 하는지에 대한 자세한 설명이어야 한다. 사양은 고정된 것이 아니다. 프로젝트가 진행됨에 따라 사양을 변경하고 새 개발 반복 과정을 트리거하는 새로운 요구사항과 사용자 스토리를 생성할 수 있다.

이제 /plan 형태로 사용할 기술 스택을 추가할 수 있다. 이를 통해 예를 들어 인증 방법이나 스토리지를 교체하는 등 스택의 요소를 변경해서 개발 단계에서 테스트를 거쳐 배포 단계로 진행할 수 있다. 따라서 개인용 PC에서 개발을 위한 기본적인 SQLite 구현으로 시작한 다음 테스트 시스템에서 마이SQL용으로 다시 빌드하고, 이후 배포를 위해 애저 SQL로 변경할 수 있다.

스펙 키트의 중요한 특징 중 하나는 기본 시스템 프롬프트가 환각 위험을 최소화하도록 설계됐다는 점이다. 패스는 함수를 구현할 수 없는 경우 코드에 [NEEDS CLARIFICATION] 마커를 질문과 함께 삽입해 에이전트가 가정에 따라 행동하지 않고 사용자에게 구체적인 의도를 묻도록 한다. 기본 프롬프트에 이 마커를 확인하는 작업이 포함되므로 시스템은 이전 패스에서 식별된 문제를 건너뛰지 않고 검사를 수행한다.

사양과 계획이 마련되면 /tasks 단계를 실행할 수 있다. 이 단계에서 프로젝트는 각각 프론트엔드, 비즈니스 로직, 서비스 인터페이스, 스토리지 구성과 같은 일련의 작업으로 분할된다. 작업 자체는 다시 하위 작업으로 구성될 수 있는데, 이는 소프트웨어 개발 수명 주기의 프로젝트 계획 단계에서 프로젝트 관리자와 협업하는 방식과 거의 비슷하다.

마지막 단계는 /implement 실행이다. 이 작업에는 여러 단계가 필요하고 대부분의 경우 얼마간의 수동 개입도 필요하다. 코파일럿 에이전트는 테스트 기반 개발 방법론을 사용해 테스트를 빌드하고 실행하는 것을 포함해 코드를 생성하고 확인한다. 툴의 기반을 모범 사례에 두는 것은 매우 타당하다. 이를 통해 스펙 키트와 코파일럿이 독단적으로 움직이지 않고 툴을 사용하는 개발자와 협업하게 되기 때문이다. 여기서 사용자는 HIL을 담당하게 되며, 원할 때 언제든 작업을 가져와 직접 처리할 수도 있고, 간섭하지 않다가 에이전트가 요청할 때만 결정을 내릴 수도 있다.

스펙 키트를 사용한 애플리케이션 빌드

필자는 위 단계에 따라 몇 시간 만에 기본 사양에서 출발해 프로토타입 애플리케이션까지 도달할 수 있었다. 결과로 얻은 코드는 필자의 로컬 WSL 개발 시스템에서 문제없이 실행됐으며 동료들에게도 불안감 없이 전달할 만한 수준이었다.

코파일럿을 통해 /implement 명령을 실행하자 몇 가지 흥미로운 동작을 볼 수 있었다. 서비스는 코드를 작성하고 구성을 설정하지만 필요한 모든 소프트웨어를 자동으로 설치하지는 않는다(특히 관리자 권한이 필요한 경우). 서비스는 일시 중지돼 사용자가 터미널에서 작업을 완료할 때까지 기다리고, 필요한 소프트웨어가 설치된 이후에는 사용자가 수동으로 다시 시작할 때까지 기다린다. 스펙 키트를 사용하려면 코파일럿 창과 터미널 창을 모두 열어야 한다.

너무 오래 걸리거나 정해진 시간을 초과하는 단계의 경우 모두 수동 개입이 필요하지만, 개입은 코파일럿 창에서 이뤄진다. 이 툴은 “실행한 다음 더 이상 신경 쓰지 않아도 되는” 종류의 툴이 아니므로 여전히 수동 감독이 필요하다. 예를 들어 테스트를 실행할 때 배시 명령을 승인하라는 요청에 응답해야 한다.

특히 구현 과정에서 일부 단계의 경우 두 번 이상 실행이 필요하다. 스페시파이(Specify)는 테스트 주도 개발 방법론을 사용하며, 코드뿐만 아니라 테스트도 작성해야 한다. 테스트가 구현되고 나면 툴은 애플리케이션에 필요한 서비스를 생성하고 로컬 웹 서버에서 사용할 수 있도록 한다.

스펙 키트를 사용해야 할까?

코딩 에이전트를 사용한 사양 기반 개발은 바이브 코딩만큼 속도가 빠르지는 않지만 어차피 속도는 초점이 아니다. 이 방법은 기업에 더 적합한 코드를 만들어낼 수 있는가? 적어도 일반적인 시나리오에서는 그렇다. 기존 개발 기술이 필요하지만 비즈니스 분석가와 설계자가 한나절 만에 실제 동작하는 새 애플리케이션 프로토타입을 완성하고 개선을 위해 개발팀에 전달할 수 있다. 분석가와 설계자가 이 방법론과 가장 잘 맞는 스킬셋을 보유하고 있기 때문이다. 분석가는 세부적인 사양을 정의하고 새로운 사용자 스토리와 사용 사례를 통해 반복적이고 민첩한 접근 방식에 따라 결과 프롬프트를 개선할 수 있고, 설계자는 프론트엔드부터 서비스, 스토리지에 이르기까지 대상 툴셋을 정의할 수 있다.

주목해야 할 중요한 점은 기반 프롬프트와 프로젝트 원칙의 활용을 통해 문제 발생 위험을 줄이고 깃허브 사양 기반 개발 툴을 유용하게 만들어주는(특히 프로토타입 제작이나 레거시 애플리케이션 업그레이드에 유용) 엄격한 제약 조건을 제공할 수 있다는 것이다. 비주얼 스튜디오 코드와 깃허브 코파일럿을 사용 중이라면 스펙 키트를 직접 체험하면서 자신에게 필요한 AI 페어 프로그래머가 될 수 있을지 확인해볼 가치는 있다.
dl-itworldkorea@foundryco.com