AI 코딩 에이전트가 단순 코드 완성을 넘어 복잡한 기능 구현까지 해내는 시대입니다. 하지만 “사양서를 작성하면 AI가 전체 시스템을 구축해줄 것”이라는 기대는 현실에서 종종 무너집니다. Arcturus Labs의 최근 분석에 따르면, 스펙 기반 개발(Spec-Driven Development)이 대규모 프로젝트에서 실패하는 근본 원인은 자연어의 모호성에 있습니다. 이 글에서는 왜 완벽한 사양서 작성이 불가능한지, 그리고 인간 개발자는 어떻게 이 문제를 우회하는지 살펴보고, AI 시대에 맞는 새로운 개발 워크플로우를 제시합니다.
핵심 포인트:
- 자연어 사양서의 근본적 한계: 모호성을 완전히 제거하려면 사양서가 코드만큼 방대해져야 하며, 결국 사양서 작성 자체가 개발이 됨
- 인간의 성공 비결: 공유된 조직 맥락과 실시간 명확화 대화를 통해 자연어의 모호성을 효과적으로 관리
- 살아있는 사양서 시스템: 코드 변경이 사양서를 자동 업데이트하는 양방향 동기화 구조로, 제품 의사결정이 역사 속으로 사라지지 않음
AI 코딩의 진화: 완성에서 자율까지
GitHub Copilot이 2021년 등장했을 때, 개발자들은 코드 자동완성의 혁명을 목격했습니다. 하지만 불과 1~2년 만에 코드 완성은 “바이브 코딩(vibe coding)”에 자리를 내줬죠. 바이브 코딩은 개발자가 대략적인 의도만 전달하면 AI가 더 큰 작업 단위를 처리하는 방식입니다.
그러나 바이브 코딩에도 문제가 있었습니다. AI 에이전트는 과도하게 야심찬 인턴처럼 행동하며, 매 단계마다 세심한 가이드 없이는 해를 끼치는 경우가 많았습니다. 이런 한계를 극복하기 위해 등장한 것이 스펙 기반 개발입니다.
스펙 기반 개발의 기본 아이디어는 간단합니다. 코드 변경에 착수하기 전에 먼저 상세한 사양서를 작성하고, 그 사양서를 AI의 가이드로 사용하는 것입니다. AI가 큰 그림을 더 잘 이해하도록 돕죠. 구현이 완료되면 사양서는 목적을 다했으니 폐기합니다.
GitHub는 최근 이 접근법을 체계화한 오픈소스 툴킷 Spec Kit를 공개했습니다. Specify(사양 작성) → Plan(기술 계획) → Tasks(작업 분해) → Implement(구현)의 4단계로 구조화된 워크플로우를 제공하죠.
완벽한 사양서는 왜 불가능한가
이제 극단적인 실험을 해봅시다. 제품의 전체 사양서를 작성하고, AI 에이전트에게 처음부터 끝까지 웹사이트 전체를 구축하게 합니다. 이틀 후 에이전트가 완성품을 돌려줬는데, 원하던 것과 미묘하게 다릅니다.
문제는 에이전트의 능력이 아닙니다. 에이전트의 작업은 사양서와 완벽히 일치했습니다. 진짜 문제는 사양서 자체가 모호했다는 점입니다. 큰 규모의 사양서일수록 자연어의 불완전성이 더 심각해집니다.
그렇다면 모호한 부분을 모두 찾아 하위 섹션과 하위의 하위 섹션을 추가해 명확히 하면 어떨까요? 자연어를 충분히 정밀하게 만들려면 너무 많은 내용을 작성해야 해서, 사양서 작성의 이점이 완전히 사라집니다. 사양서는 형식 언어가 되고, 차라리 다른 형식 언어, 즉 코드를 사용하는 게 낫습니다.
인간은 어떻게 성공하는가
그런데 인간 개발자는 자연어로도 꽤 잘 해냅니다. AI가 실패하는 대규모 소프트웨어 개발을 우리는 어떻게 합리적으로 수행할까요?
첫째, 공유된 맥락입니다. 우리는 바로 주변 세계에 대한 공통된 이해를 갖고 있습니다. AI는 공개 도메인의 모든 텍스트와 코드를 읽어서 일반적으로 어떻게 작동하는지 잘 알지만, 당신의 회사와 코드베이스에서 일이 어떻게 돌아가는지는 전혀 모릅니다. 우리가 제공하는 컨텍스트로는 이런 뉘앙스를 절대 포착할 수 없죠.
반면 당신은 시행착오를 통해 즉각적인 환경에 대한 이해를 쌓아왔습니다. 회사에서 첫 코드 변경을 구현했을 때, PR 리뷰에서 “우리가 여기서 일하는 방식”에 대해 많은 것을 배웠습니다. 코드와의 모든 상호작용, 회의에서의 대화, 복도에서 나눈 이야기를 통해 더 많이 배웠죠. 이렇게 배운 것은 거대한 문서로 만들어 에이전트에게 컨텍스트로 제공하기가 거의 불가능합니다.
둘째, 명확화 대화입니다. 인간은 명확화를 추구합니다. 진술이 이루어지면 모호한 점을 파악하고, 대화를 통해 가능성을 명확히 합니다. 게다가 우리는 정말 중요한 모호성만 효율적으로 다룹니다. 공유된 맥락에 기대어 “모두가 알아야 할” 것들에 대해서는 묻지 않습니다. 어떤 라이브러리를 사용할지, 작은 구현 세부사항에 대해서는 묻지 않죠. 혼란스럽거나 불명확한 것에 대해서만 묻습니다.
AI 모델은 이제야 명확화를 잘하기 시작했습니다. 하지만 명확화를 정말 잘 하려면, 앞 문단에서 제시한 미묘한 맥락적 이해가 필요한데, AI 에이전트에게는 그것이 없습니다.
해결책: 대화와 계층, 그리고 코드
대규모 스펙 기반 개발에서 사양서 모호성 문제를 어떻게 해결할까요? 역순으로 살펴보겠습니다.
대화를 통한 명확화
명확화와 관련해서는, 에이전트가 사양서의 모호하거나 불명확한 부분에 대해 질문할 수 있도록 허용하지 않으면 더 나은 이해에 도달할 방법이 없습니다. 스펙 기반 개발이 작동하려면 모호성을 파악하고 명확히 하는 일련의 대화가 반드시 필요합니다. 이는 아마도 채팅 경험 형태로 구현될 것입니다.
작은 작업 단위에서 사용할 수 있는 또 다른 방법은 AI가 사양서를 여러 번 구현하도록 해서, 서로 다른 구현이 모호성의 지점을 드러내게 하는 것입니다. 에이전트는 서로 다른 구현을 비교하고, 배운 내용을 활용해 개발자와 어느 방향으로 가야 할지 대화할 수 있습니다.
계층적 사양서를 통한 세계관 구축
명확화의 궁극적 목표는 에이전트의 세계관을 바로잡고 구체화하는 것입니다. 에이전트는 이 회사와 이 코드베이스에서 일이 일반적으로 어떻게 돌아가는지 알아야 합니다.
앞서 사양서에 하위 섹션과 하위의 하위 섹션을 추가하는 아이디어를 기억하시나요? 개발자에게는 엄청난 노력이 필요하지만, AI 에이전트에게는 시간을 잘 쓰는 것일 수 있습니다. 다만 사양서가 너무 방대해지므로 문자 그대로 모든 하위 섹션을 추가하는 것은 권장하지 않습니다.
대신 글로벌 사양서가 하위 사양서 문서로 링크할 수 있도록 하는 계층적 접근법이 아마도 있을 것입니다. 실제로 이전 포스트에서 보여줬듯이, AI 에이전트는 이런 링크를 탐색하는 데 꽤 능숙합니다.
다만 계층 구조의 최적 조직 방식은 명확하지 않습니다. 모든 파일에 사양서 하나를 두고, 각 디렉토리에 해당 디렉토리 내용의 요약 버전을 두어 최상위까지 올라가는 방식도 가능합니다. 이 경우 사양서가 코드 측면에 엄격히 부착되므로, 자유 형식 위키 같은 더 나은 접근법이 있을 수 있습니다. 하지만 그것도 다른 이유로 통제를 벗어날 수 있습니다.
코드 자체를 최종 사양으로
어느 시점에서 코드의 저수준 가정을 인코딩하는 가장 좋은 방법은 코드 자체를 사용하는 것입니다. 자연어에는 모호성이 있지만, 코드에는 모호성이 없기 때문입니다.
이는 철학적 변화를 의미합니다. 일부 사람들은 잘 정의된 사양서가 매번 기능적으로 동등한 생성물을 만들어야 한다는 입장인데, Arcturus Labs는 이에 반대합니다. 자연어가 그런 수준의 정밀성을 제공하기에는 근본적으로 부적합하다는 이유에서입니다.
코드 자체를 리프 레벨 사양서로 사용하면 사양서 모호성 문제가 제거됩니다. 코드 변경이 이미 존재하는 코드에 근거하기 때문이죠. 그리고 마스터 제품 사양서에서 코드를 전역적으로 재생성할 것으로 기대하지 않습니다.
거꾸로 생각하기: 코드가 사양서를 업데이트한다
전통적인 스펙 기반 개발은 “사양서 작성 → 구현 → 사양서 폐기” 순서입니다. 하지만 Arcturus Labs는 이 접근법이 역방향이어야 한다고 주장합니다. 코드가 변경될 때마다 사양서도 함께 업데이트되어 동일한 PR에 포함되어야 한다는 것이죠.
이렇게 하면 오래된 코드베이스가 일관성 없는 패치워크가 되는 문제를 막을 수 있습니다. 개발자는 과거의 제품 결정을 모른 채 코드를 수정하곤 했죠. 이제 AI 에이전트가 계층적 사양서를 탐색하며 “이 변경은 기존 사양과 충돌합니다”라고 알려줄 수 있습니다.
제품 관리자에게도 유용합니다. PR에서 코드 대신 사양서 변경 내용을 읽고 개입할 수 있으니까요. 자동으로 최신 상태가 유지되는 사양서를 AI 비서가 읽고 제품 진화 상황을 설명해줄 수도 있습니다.
핵심은 완벽한 사양서를 만드는 것이 아니라, 대화와 맥락을 통해 모호성을 관리하는 시스템을 구축하는 것입니다. 사양서와 코드가 함께 진화하는 피드백 루프. 이것이 스펙 기반 개발의 진짜 미래입니다.
참고자료:
답글 남기기