🤖 AI가 코드는 짜는데 왜 자꾸 틀릴까? "스펙 레이어"가 답입니다

빌드도 됐고, 테스트도 통과했는데, 왜 이상한 코드가 나오죠?

요즘 AI 코딩 에이전트를 쓰다 보면 이런 경험 한 번쯤은 하셨을 거예요.

"분명히 테스트는 다 통과했는데, 실제로 돌려보니 원하던 기능이 아니야." "컴파일은 잘 됐는데, 기존에 잘 되던 기능이 슬쩍 망가졌어." "AI가 실패하는 테스트를 고친 게 아니라... 그냥 비활성화해버렸어."

Cursor나 Claude Code 같은 도구를 써본 분이라면 공감이 많이 되실 것 같아요. 코드가 실행된다는 것과, 코드가 올바르다는 것은 이제 완전히 다른 이야기가 됐습니다. AI 에이전트 시대에 새롭게 등장한 이 문제, 오늘 제대로 한번 파헤쳐 볼게요.

AI 에이전트는 인간 개발자와 전혀 다른 방식으로 실패합니다

인간 개발자가 실수를 저지르면 보통 눈에 보이는 신호가 나옵니다. 빌드가 깨지거나, 테스트가 터지거나, 런타임 에러가 발생하죠. 그러면 바로 알아채고 고칠 수 있어요.

그런데 AI 에이전트는 다르게 망가집니다.

컴파일은 통과합니다. 테스트도 통과합니다. 그런데 막상 보면 원래 있던 기능이 하나 사라져 있거나, 똑같은 서비스가 두 개 생겨 있거나, 실패하는 테스트 케이스가 갑자기 주석 처리돼 있거나 합니다.

실리콘밸리 엔지니어링 커뮤니티에서 화제가 됐던 Matt Rickard의 글 "The Spec Layer"에서는 이 현상을 "지역적으로는 유효하지만 코드베이스 전체 관점에서는 잘못된 결정들이 축적된다"고 정확하게 짚었어요. 기존 린터, 테스트, 컴파일러는 인간이 저지르는 실수를 잡도록 설계됐기 때문에 AI 에이전트의 새로운 실패 방식을 걸러내지 못하는 거죠.

왜 이런 일이 생기냐면, 핵심 원인은 "결정이 문서화되지 않은 것"입니다

AI 에이전트는 실행 시점에 자유롭게 결정을 내립니다. 어떤 서비스를 어떻게 구조화할지, 어떤 패턴을 사용할지, 기존 코드와 어떻게 연결할지. 이런 결정들이 어디에도 적혀 있지 않으면, 에이전트는 매 세션마다 그것을 새로 판단해버립니다.

세션이 길어질수록 또 다른 문제가 생겨요. 컨텍스트 창은 유한하기 때문에, 처음에 나눴던 중요한 맥락이 점점 압축되거나 날아가버립니다. 이걸 "컨텍스트 오염(Context Rot)"이라고 부르는데, AI가 세션 초반의 중요한 결정을 잊어버리고 일관성 없는 코드를 뱉기 시작하는 현상이에요.

에이전틱 AI를 도입한 한 글로벌 컨설팅 업체에 따르면, 생성형 AI만 사용했을 때 개발자 생산성이 30% 향상됐지만, 에이전틱 AI를 체계적으로 도입했을 때는 200%까지 향상됐다고 합니다. 하지만 이 200%를 달성하려면 단순히 AI 도구를 사용하는 것 이상이 필요하다는 게 점점 명확해지고 있어요.

바이브 코딩, 작은 프로젝트에서는 완벽하지만 규모가 커지면 무너집니다

바이브 코딩이 뭔지 아시나요? AI와 함께 즉흥적으로 코딩하는 방식이에요. 아이디어가 생기면 바로 AI에게 말하고, AI가 코드를 만들어주면 이어서 발전시키는 방식이죠. 빠르고 재미있어서 요즘 개발자들 사이에서 엄청 인기예요.

작은 기능 하나 뚝딱 만들 때는 정말 탁월합니다.

문제는 프로젝트가 커질 때 생겨요. 기능을 수정할 때마다 "아 맞다, 이전에 이렇게 설계했었어" 하고 처음부터 다시 설명해야 하고, 세션이 길어질수록 AI가 점점 멍청해지는 느낌이 들기 시작합니다. 전체 아키텍처 맥락이 사라지면서 앞뒤가 안 맞는 코드가 쌓이는 거예요.

카카오페이 AI 플랫폼 팀도 같은 경험을 공개적으로 밝혔어요. 에이전틱 코딩을 도입해서 개발 생산성이 크게 높아졌지만, 프로젝트가 고도화될수록 무분별한 코드 생성과 환각이 심각한 문제가 됐다고 해요. 그래서 그들이 도입한 것이 바로 스펙 주도 개발, SDD였습니다.

스펙 레이어란 무엇인가요? 코드 대신 의도를 먼저 씁니다

Matt Rickard의 "스펙 레이어" 개념은 이렇게 정의됩니다.

스펙 주도 개발이란, 구현하기 전에 지속적인 의도를 글로 써두고, 그것을 계획, 구축, 검증, 수정의 기준으로 삼는 방식입니다.

스펙이 코드를 대체하는 게 아니에요. 에이전트가 실행 시점에 즉흥적으로 판단할 여지를 줄여주는 "제약의 레이어"입니다.

스펙은 여러 층위로 나뉩니다.

스펙(Spec)은 시스템이 무엇을 해야 하는지, 즉 의도를 제약합니다. 플랜(Plan)은 이 코드베이스에서 어떻게 구현할지, 접근 방식을 제약합니다. 태스크(Task)는 순서와 우선순위를 정합니다. 테스트, 스키마, 린트는 실제 동작을 제약하죠.

이 각각의 레이어가 AI 에이전트의 선택지를 좁혀줍니다. 스펙이 없으면 에이전트는 이 모든 것을 스스로 결정하고, 매 세션마다 다르게 결정합니다. 그게 바로 일관성 없는 코드가 쌓이는 이유예요.

비슷한 원리가 오래된 소프트웨어 공학에도 있어요. 1981년 RFC 791로 표준화된 인터넷 프로토콜, HTTP 표준, TLS 규격들. 이 스펙들 덕분에 수많은 구현체가 수십 년에 걸쳐 일관성 있게 진화할 수 있었잖아요. AI 에이전트에게도 같은 원리가 적용되는 겁니다.

실제로 이미 SDD를 구현한 도구들이 나오고 있어요

지금 시장에는 이 개념을 구현한 다양한 도구가 빠르게 늘고 있어요.

GitHub Spec Kit은 코드 우선 방식에서 사양 우선 방식으로 전환을 돕는 워크플로우입니다. Initialize, Constitution, Specify, Plan, Tasks, Implement 이렇게 6단계를 정형화해서 체계적으로 AI 에이전트와 협업할 수 있게 해줘요.

Kiro는 개발자가 단일 프롬프트를 넣으면 요구사항, 설계, 구현 태스크 목록을 자동으로 만들어줍니다. "제품 리뷰 시스템 추가해줘"라고 하면, 사용자 스토리와 수용 기준, 예외 상황까지 포함한 요구사항 문서를 뽑아내는 방식이에요.

GSD(Get Shit Done)는 Claude Code, Gemini CLI 같은 AI CLI 도구를 위한 메타 프롬프팅 및 스펙 주도 개발 시스템으로, 컨텍스트 오염 문제를 근본적으로 잡으려는 접근법입니다.

이 도구들이 모두 다른 제품처럼 보이지만, Matt Rickard의 지적대로 결국 같은 뼈대를 다시 쌓고 있어요. 지속적 컨텍스트, 기능 의도, 기술 계획, 명시적 태스크, 검증. 이 다섯 가지가 공통 핵심입니다.

또한 위시켓의 분석에 따르면 SDD는 크게 세 가지 방식으로 나뉩니다. 스펙을 먼저 쓰고 개발하는 스펙 우선, 작업 완료 후에도 스펙을 유지해서 유지보수에 활용하는 스펙 고정형, 그리고 스펙 자체가 주요 소스 파일이 되어 개발자는 스펙만 수정하는 스펙-소스 방식이 있어요.

스펙 주도 개발, 이것만 조심하면 됩니다

SDD가 좋다고 해서 모든 것을 스펙으로 도배하면 오히려 역효과가 납니다.

Dijkstra가 수십 년 전에 경고했던 것처럼, 충분히 상세한 스펙은 결국 코드 자체가 되어버려요. 스펙을 수정해야 할 또 다른 복잡한 코드가 생기는 역설이죠.

실제로 SDD를 사용해본 개발자들이 공통적으로 지적하는 단점들이 있어요. 단계가 많아서 처음 접하는 사람에게는 복잡하게 느껴집니다. 간단한 버그 수정이나 빠른 프로토타입에는 과도한 절차예요. 스펙 파일이 늘어날수록 토큰 소모도 비례해서 증가하고요.

Matt Rickard의 결론은 명확해요. 스펙은 가능한 한 얇아야 합니다. 기계적으로 검증 가능한 규칙은 스펙에서 꺼내서 린트, 스키마, 테스트, 하네스로 옮겨야 합니다. 산문은 줄이고, 기계적 강제를 늘리는 방향으로 가야 해요.

더 작은 스펙, 더 강한 검사, 덜 추측. 이것이 SDD의 황금률입니다.

기획자와 PO가 이 이야기에서 얻어야 할 가장 중요한 것

여기까지 읽으시면서 이게 개발자 이야기라고 느끼셨나요? 사실 기획자와 프로덕트 오너에게도 직접적인 의미가 있어요.

AI 에이전트 시대에 결정사항이 문서화되지 않으면, 에이전트는 그것을 매번 스스로 결정합니다. 그 결정은 여러분의 의도와 다를 수 있고, 세션이 달라지면 또 다르게 결정됩니다.

기획서, 요구사항 문서, 기능 정의서가 단순한 팀 내 커뮤니케이션 도구가 아니라, AI 에이전트를 위한 실행 제약 레이어가 되는 시대가 왔습니다. 잘 쓴 PRD 하나가 AI의 자유도를 좁혀서 더 일관된 코드를 만들어냅니다.

코딩을 직접 안 해도 됩니다. 하지만 무엇을 만들지, 왜 만드는지, 어떤 방식으로 동작해야 하는지를 명확하게 정의하는 사람이 AI 에이전트를 가장 잘 활용하는 사람이 됩니다. 그 의도를 가장 잘 아는 사람은 결국 기획자와 PO예요.

마무리

AI 에이전트는 이제 테스트를 통과하는 코드를 쉽게 만들어냅니다. 하지만 "올바른 코드"를 만드는 건 여전히 어려운 일이에요. 그 간극을 메우는 것이 스펙 레이어입니다.

구현 전에 의도를 적고, 적은 것을 기준으로 검증하고, 기계적으로 강제할 수 있는 것은 코드로 옮기고, 스펙은 가볍게 유지하는 것. 이것이 바이브 코딩의 한계를 넘어서는 방법이에요.

AI가 코드를 짜는 시대, 진짜 경쟁력은 무엇을 만들지 명확하게 정의하는 능력으로 이동하고 있습니다. 개발자든 기획자든, 지금 가장 필요한 스킬은 코딩 실력이 아니라 의도를 정확하게 언어화하는 능력일지도 모르겠어요.