명세 기반 개발(Spec-driven development)이란 무엇인가? (AI 코딩 에이전트 활용)

대부분의 AI 코딩 워크플로우는 동일한 방식으로 시작됩니다. 에이전트를 열고, 원하는 내용을 한두 문장으로 설명한 뒤, 코드가 작성되는 것을 지켜보는 것이죠. 매우 빠르게 느껴집니다. 하지만 곧 diff(차이점)가 돌아오면 에이전트가 잘못된 것을 만들었거나, 옳은 것을 잘못된 방식으로 만들었다는 것을 알게 되고, 다음 한 시간 동안 후속 프롬프트(follow-up prompts)를 통해 이를 수정하는 데 시간을 보냅니다. 에이전트는 코드를 어떻게 작성할지에 대해 혼란을 느낀 것이 아니었습니다. 당신이 실제로 무엇을 원하는지에 대해 혼란을 느꼈던 것입니다.

명세 기반 개발(spec-driven development)은 이러한 실패 모드에 대한 직접적인 대응책입니다. 에이전트에게 바로 코드를 작성하라고 프롬프트를 주는 대신, 먼저 명세(spec) — 요구사항, 설계, 그리고 작업에 대한 서술된 설명 — 를 생성하고, 이것이 올바를 때까지 해당 명세를 수정합니다. 그 후에야 명세가 구현(implementation)을 주도합니다. 무엇을 만들 것인지에 대한 결정은 코드가 존재하기 전, 종이 위에서 명시적으로 단 한 번 이루어집니다.

명세 기반 개발이 실제로 의미하는 것

이 용어는 IDE에

각 단계는 다음 단계의 토대가 됩니다. 요구사항 (Requirements)이 설계를 제한하고, 설계는 작업 (Tasks)으로 분해되며, 에이전트는 이 작업을 구현합니다. 사람은 각 단계에서 검토하고 수정하므로, 코드 생성 (Code generation)이 시작될 때쯤이면 에이전트는 한 줄짜리 프롬프트 (Prompt)에서 명시되지 않은 수천 가지 세부 사항을 추측하는 대신, 당신이 이미 합의한 문서를 바탕으로 작업하게 됩니다.

이것이 지금 왜 중요한가

소프트웨어 역사의 대부분 동안, 비용이 많이 들고 느린 부분은 코드를 작성하는 것이었습니다. 타이핑이 병목 현상 (Bottleneck)이었고 오해는 리팩터링 (Refactoring)을 통해 해결할 수 있었기에, 명세 (Specs)는 오버헤드 (Overhead)처럼 느껴졌습니다. 하지만 그 경제 논리가 변했습니다. 에이전트가 몇 분 만에 기능 하나 분량의 코드를 생성할 수 있게 되면서, 코드를 작성하는 것은 더 이상 제약 사항이 아닙니다. 병목 현상은 무엇을 만들지 정확하게 결정하는 단계로 이동했습니다.

명세는 당신과 에이전트 모두가 읽을 수 있는 형태로, 그 결정을 단 한 번 내리는 방법입니다. 모호한 의도는 모델이 공백을 채우도록 강요하며, 모델은 그 공백을 그럴듯한 추측으로 채웁니다. 그리고 당신은 코드가 작성된 후에야 그 추측이 틀렸음을 발견하게 됩니다. 명세는 이러한 추측 과정을 비용이 저렴한 문서 단계로 앞당깁니다. 여기서는 잘못된 가정이 스프린트 (Sprint) 전체를 되돌려야 하는 상황이 아니라, 문장 한 줄을 수정하는 비용만 발생하기 때문입니다.

명세의 목적은 문서화가 아닙니다. 당신의 의도와 에이전트가 이해한 내용 사이의 불일치가 2,000줄의 코드 대신 단 한 단락에 불과할 때, 그 불일치를 표면화하는 것입니다.

도움이 되는 부분

차이점(diffs)이 아닌 의도를 검토합니다

차이점(diffs)이 아닌 의도를 검토합니다

방대한 차이점(diff)을 검토하는 것은 역공학(reverse-engineering)과 같습니다. 즉, 코드를 읽고 작성자가 무엇을 의도했는지 재구성한 다음, 그 의도가 올바른지 판단하는 과정입니다. 명세(spec)는 이 순서를 뒤집습니다. 먼저 언어를 통해 의도에 합의한 다음, 이미 승인된 의도에 따라 구현(implementation)이 제대로 되었는지 확인합니다. "이메일 형식을 검증하고 중복을 거부한다"라는 문구를 읽고 그것이 맞는지 결정하는 데는 몇 초밖에 걸리지 않습니다. 반면, 엔드포인트(endpoint), 검증(validation), 데이터베이스 쿼리(database query)를 읽으며 동일한 내용을 추론하는 데는 훨씬 더 오랜 시간이 걸리며, 여전히 간극을 놓칠 수 있습니다.

비용을 치르기 전에 잘못된 빌드를 잡아냅니다

AI 보조 작업에서 가장 비용이 많이 드는 실수는 잘못된 것을 제대로 만드는 것입니다. 명세는 이를 잡아낼 수 있는 가장 저렴한 지점입니다. 요구사항에는 기능이 X를 수행해야 한다고 되어 있는데 정작 당신은 Y를 원했다면, 에이전트가 세련되고 테스트까지 완료된, 하지만 완전히 방향이 잘못된 구현물을 만들어내기 전, 즉 단 하나의 태스크(task)가 실행되기도 전에 이를 발견할 수 있습니다.

정직하게 병렬화를 수행할 수 있습니다

설계가 명확한 경계를 가진 개별 태스크로 분해되면, 여러 에이전트를 투입하더라도 서로 충돌하거나 작업을 중복하지 않고 병렬로 작업을 수행할 수 있습니다. 명세는 독립적인 작업들이 일관성을 유지하도록 만드는 공유 계약(shared contract) 역할을 합니다. 명세가 없다면, 병렬로 작동하는 에이전트들은 각각 모호한 목표에 대해 자신만의 해석을 만들어낼 것이고, 당신은 절약한 시간을 그 차이를 조정하는 데 허비하게 될 것입니다.

정직한 한계

명세 기반 개발(spec-driven development)은 공짜가 아니며, 항상 그만한 가치가 있는 것도 아닙니다. 이 규율에는 실제적인 비용이 따르며, 이를 공정하게 받아들이는 것이 명세를 잘 사용하는 유일한 방법입니다.

작은 작업에는 과잉 대응(overkill)입니다. 한 줄짜리 수정, 문구 변경, 이름 변경 등의 작업에 대해 요구사항-설계-태스크 문서를 작성하는 것은 그냥 직접 처리하는 것보다 느리며, 그렇지 않은 척하는 것은 좋은 관행을 단순 업무(busywork)로 변질시키는 길입니다. 명세의 규모는 변경 사항의 규모 및 리스크와 일치해야 하며, 사소한 작업의 경우 명세가 전혀 필요 없음을 의미합니다.

명세(Spec)는 노후화됩니다. 명세가 유지 관리되지 않는다면 그것은 진실의 원천(source of truth)이 될 수 없습니다. 코드가 문서로부터 벗어나고 아무도 문서를 업데이트하지 않는 순간, 명세는 확신에 찬, 시대에 뒤떨어진 거짓말이 됩니다. 이는 명세가 아예 없는 것보다 더 나쁜데, 사람들이 그것을 신뢰하기 때문입니다. 이것이 초기 모델 기반 접근 방식(model-driven approaches)을 침몰시킨 실패 요인이었으며, 여전히 사라지지 않았습니다.

그리고 에이전트가 항상 복종하는 것도 아닙니다. 더 큰 컨텍스트 윈도우(context window)와 상세한 명세가 모델이 모든 줄을 따를 것을 보장하지는 않습니다. 명세는 모호함을 줄여줄 뿐, 출력물을 검토해야 할 필요성을 없애주지는 않습니다. 일부 실무자들은 장황한 마크다운(markdown) 명세를 검토하는 것 자체가 지루하다고 느끼기도 하는데, 이는 해결된 문제가 아니라 실제적인 트레이드오프(tradeoff)입니다. 명세를 모델이 반드시 준수해야 하는 계약이 아니라, 의도(intent)를 명확하게 만들기 위한 도구로 취급하십시오.