사양 중심 개발: 장점 - 그리고 3개월 후 얻은 교훈

사양 중심 개발: 장점 - 그리고 3개월 후 얻은 교훈

2026년 9월 16일

3개월이 지난 후, 추가된 구조가 도움이 되는 경우와 방해가 되는 경우를 더 명확하게 파악할 수 있었습니다.

저희 엔지니어 중 한 명이 데이터 마이그레이션을 준비하고 있었고, 작업을 계획하기 위해 사양 중심 개발(SDD)을 사용하기로 결정했습니다. SDD는 엔지니어가 초기에 누락 사항을 파악하고, 접근 방식을 더 쉽게 검토하고, 상담원에게 명확한 지침을 제공할 수 있도록 고안되었습니다. 그 결과 나온 계획은 상세했으며, 서면상으로는 상당히 합리적으로 보였습니다. 업무는 다음과 같이 구성되었습니다.

문제 → 조사 → 사양 → 검토 → 구현 → 검증

구현이 진행되면서 엔지니어는 두 개의 작업이 경합하여 중복된 사용자 지정 필드를 생성할 수 있다는 것을 깨달았습니다. 이 접근 방식은 또한 코드를 점점 더 복잡하게 만들고 이해하기 어렵게 만들었습니다. 다행히도 엔지니어는 문제를 포착하고 구현을 중단했으며, 1페이지 분량의 설계 문서를 작성하고 몇몇 동료를 태그하여 의견을 구했습니다. 함께 디자인을 검토한 결과, 더 안전한 접근 방식을 찾을 수 있었습니다.

기존 사양은 우리가 요청한 대로 프로젝트를 기존 방향으로 진행했습니다. 문제는 방향이 잘못되었다는 것이었습니다. 상세한 사양 덕분에 시작 아이디어가 불안정하더라도 프로젝트를 쉽게 계속할 수 있었습니다. 에이전트는 사람들이 멈춰서 의문을 제기할 수 있는 것보다 더 빠르게 그 아이디어를 구축할 수 있었습니다.

이 프로젝트는 구조를 추가할 때의 한 가지 위험을 보여주었습니다. 한 에이전트가 사양에서 동일한 잘못된 가정을 코드와 테스트로 가져올 수 있다는 것입니다. 사양, 코드, 테스트가 서로 일치했지만, 그렇다고 해서 그 이면에 깔린 가정이 옳다는 의미는 아니었습니다. 더 위험한 결정을 내리는 경우, 여전히 다른 사람이 원래 목표로 돌아가 구현이 목표를 위반할 수 있는 방법을 찾아야 했습니다.

그럼에도 불구하고 에이전트는 한 세션보다 오래 지속되는 작업을 수행하고 있었으며, 프롬프트만으로는 프로젝트의 목표나 이유를 유지하기에 종종 부족했습니다. 이를 통해 우리는 사양이 중심이 되는 워크플로 하네스인 /spec-driven을 구축하게 되었습니다. 사양은 다음 세션에서도 프로젝트의 방향을 유지할 수 있도록 했습니다. 스크립트는 배경 정보를 가져와 검사를 실행했습니다. 실행 중에 누락된 규칙, 검사 또는 컨텍스트가 발견되면 이를 워크플로에 추가할 수 있으므로 이후의 에이전트가 동일한 누락을 다시 발견할 필요가 없습니다.

SDD의 추가 구조가 그만한 가치가 있는지 여부에 대해서는 여전히 상당한 의견 차이가 있습니다. Microsoft와 AWS는 SDD를 홍보하는 반면, Thoughtworks는 이를 신흥적이고 논쟁적인 것으로 묘사하며, 실무자들은 엇갈린 경험을 보고하고 있습니다. 비판가들은 SDD가 엔지니어가 유지 관리할 수 있는 것보다 더 많은 마크다운을 생성하거나, 상세한 사양을 산문으로 작성된 코드로 전환하거나, 코드와 동떨어진 시스템에 대한 또 다른 설명을 남길 수 있다고 경고합니다.[1][2][3]

3개월간 실제 사용한 결과, 중요한 질문은 SDD를 사용할지 여부가 아니라는 것을 알게 되었습니다. 그것은 담당자가 해당 프로젝트에서 놓치고 있던 것이었습니다. 때로는 답이 사양인 경우도 있었습니다. 때로는 더 나은 예시, 자동화된 검사 또는 해당 영역을 잘 아는 엔지니어였습니다.

/spec-driven을 만든 이유

Asana의 일부 엔지니어는 이미 GitHub Spec Kit과 OpenSpec을 사용해 보았지만, 두 가지 모두 정규 워크플로의 일부가 되지는 못했습니다. 우리는 학습하면서 조정하고 Asana의 개발 프로세스에 연결할 수 있는 버전을 원했습니다.

기본 제공되는 계획 모드는 이미 코드베이스를 조사하고 변경 사항을 적용하기 전에 유용한 구현 계획을 수립할 수 있었습니다. SDD는 이 계획에 더 많은 구조를 추가했습니다. 즉, 구현 및 검증을 통해 문제, 주요 결정 사항, 수락 기준을 계속 확인할 수 있었습니다.

구현 전에 /spec-driven은 문제에 대한 이해를 되짚어 보고 계획을 변경할 수 있는 질문을 제기했습니다. 이를 통해 엔지니어는 코드를 다시 작성하기 전에 방향을 수정할 수 있는 기회를 얻었습니다.

이러한 상태를 리포지토리에 저장했기 때문에 이후 세션에서 무슨 일이 있었는지 추측할 필요가 없었습니다. 워크플로의 규칙이 결정적이기(deterministic)를 원했기 때문에 스크립트가 기록 및 확인 작업을 처리했습니다. 이 모델은 판단이 필요한 부분, 즉 질문을 던지고, 장단점을 비교하며, 결정을 설명하는 부분을 처리했습니다.

워크플로에는 여러 명령이 포함되어 있었습니다. 엔지니어는 /spec-driven spec을 사용하여 미해결 질문을 해결하고 사양 및 실행 계획을 수립했습니다. 계획을 검토한 후 /spec-driven ship을 사용하여 계획을 실행하고, 결과를 확인하고, 검토를 위한 작업을 준비했습니다. 상태 머신은 이러한 명령을 거치는 동안 프로젝트를 추적했기 때문에 이후 세션에서 어떤 일이 있었고 다음에 어떤 일이 일어날지 파악할 수 있었습니다.

처음부터 우리는 /spec-driven이 단순히 사양을 작성하고 실행하는 것 이상의 역할을 하기를 원했습니다. 또한 에이전트 워크플로를 조율하기를 원했습니다. 종속성에 따라 작업을 정렬하고 중복되는 파일 변경 사항을 별도의 실행 라운드에 보관합니다. 독립적인 작업을 여러 에이전트에 동시에 전송한 다음, 결과를 사용하여 다음에 실행할 수 있는 작업을 결정합니다.

Asana 엔지니어는 /spec-driven을 'spec-first' 방식과 'spec-anchored' 방식 모두에서 사용했습니다. Spec-first의 경우, 엔지니어들은 사양을 사용하여 방향을 선택한 다음 사양을 업데이트하지 않았습니다. 사양 기반 방식에서는 업무가 변경됨에 따라 사양을 최신 상태로 유지했습니다. 또한 엔지니어들은 더 큰 작업량의 일부에 대해 독립적인 사양을 작성했기 때문에 한 사람이 팀 전체에 워크플로를 도입하도록 요청하지 않고도 워크플로를 사용할 수 있었습니다.

/spec-driven이 추가 작업에 가치가 있는 경우

추가된 구조는 중요한 배경 정보가 세션, 인계 또는 여러 관련 작업에 걸쳐 유지되어야 할 때 가장 큰 효과를 발휘했습니다. 엔지니어는 계획이 어떻게 변경되었는지 검토할 수 있었고, 업무가 다른 에이전트 세션이나 담당자로 이동했을 때도 프로젝트의 방향을 계속 확인할 수 있었습니다. 두 가지 제품 작업에서 약 2~3개월 동안 살아있는 사양을 유지했습니다. 하나는 주요 신기능을 구축하는 것이었고, 다른 하나는 하위 작업 날짜를 상위 작업으로 이전하는 것이었습니다.

사양 덕분에 인계가 더 쉬워졌습니다. 일시 중지된 프로젝트를 맡게 된 사람은 팀이 무엇을 하려고 했는지, 왜 그런 형태를 취했는지, 무엇이 남아 있는지 확인할 수 있었습니다. 커밋과 대화를 통해 프로젝트를 다시 구성할 필요가 없었습니다.

엔지니어는 또한 /spec-driven을 사용하여 에이전트가 실행하는 대량의 업무를 조율했습니다. 고객사 IT 팀이 조직 전체의 보안, 액세스, 연동 및 공유 설정을 관리하는 Asana 관리 콘솔에서 엔지니어들은 이를 사용하여 66개의 설정을 공유 프레임워크로 이전했습니다. 이러한 설정을 이전하려면 여러 관리 콘솔 프레임워크에서 약 150회의 마이그레이션이 필요했습니다. 각 마이그레이션은 클라우드 에이전트를 위한 Asana 티켓이 되었으며, 엔지니어들은 이를 병렬 배치로 실행하고 이전 결과를 기반으로 나머지 티켓을 업데이트했습니다.

이 작업을 수행한 팀은 마이그레이션의 91%가 검토 후 수정이 필요하지 않았으며, 전체 작업량이 당초 계획보다 한 달 이상 앞당겨졌다고 보고했습니다.

또 다른 대규모 마이그레이션에는 짧은 프롬프트만 필요했습니다. 차이점은 코드베이스가 이미 얼마나 명확하게 되어 있었는지에 있었습니다. 에이전트가 따를 수 있는 예시와 결과를 확인할 수 있는 검사가 있었습니다. 관리 콘솔 에이전트는 코드에서 모든 요구 사항을 파악할 수 없었기 때문에 업무에 더 많은 구조가 필요했습니다.

/spec-driven은 또한 신속한 프로토타입 제작에도 도움이 되었습니다. 엔지니어는 작동하는 엔드투엔드 경험을 구축하기에 충분할 만큼의 미해결 제품 질문에 신속하게 답할 수 있었습니다. PM과 디자이너는 엔지니어가 프로덕션 강화에 투자하기 전에 프로토타입을 시도할 수 있었습니다. 엔지니어가 코드를 유지하기로 결정한 경우, 일반적으로 병합하기 전에 상당한 정리 작업이 필요했습니다. 그때쯤이면 프로토타입을 통해 해당 아이디어를 추진할 가치가 있는지 여부가 이미 드러났습니다.

초기 수치가 보여준 것

저희는 모든 구성원에게 /spec-driven을 한 번 사용해 보도록 권장했지만, 계속 사용하도록 요구하지는 않았습니다. 엔지니어의 약 절반이 이를 사용해 보았습니다. 마지막 달에는 매주 30~50명의 엔지니어가 사용했습니다. 엔지니어들이 직접 호출한 기본 제공 및 Asana에서 개발한 에이전트 스킬 중 /spec-driven이 3위를 차지했습니다. 지속적인 사용은 고무적이었지만, /spec-driven이 결과물에 어떤 영향을 미쳤는지는 알 수 없었습니다.

엔지니어링 속도는 측정하기가 매우 어렵기로 악명이 높습니다. 끌어오기 요청과 구현 코드 추가는 생산성을 나타내는 완벽한 지표는 아니지만, 종종 방향성을 파악하는 데 유용한 지표라고 생각합니다. 속도 비교를 위해 4개월 동안 7명의 엔지니어와 524건의 병합된 끌어오기 요청을 살펴보았습니다. 각 엔지니어가 /spec-driven을 처음 명확하게 사용하기 전후의 작업을 비교했으며, 사양, 계획 및 기타 워크플로 아티팩트는 제외했습니다. 되돌리기 비교의 경우, 워크플로의 프로젝트 파일을 변경한 끌어오기 요청을 /spec-driven으로 분류했습니다.

주당 끌어오기 요청은 38% 증가했으며, 구현 코드 추가는 2.66배 증가했습니다. 한 번의 짧고 이례적으로 많은 양의 기간이 추가 결과에 영향을 미쳤습니다. 이 기간을 제외하더라도 추가된 코드는 여전히 66% 더 많았습니다. 명시적 되돌리기율도 약간 낮았습니다. /spec-driven 작업의 경우 1.2%였고, 다른 끌어오기 요청의 경우 1.66%였습니다.

코드의 양이 많다고 해서 반드시 좋은 결과라고 할 수는 없습니다. 상담원은 더 작은 구현으로도 충분한 경우에도 더 큰 구현을 생성할 수 있으므로, 코드 추가의 증가는 더 많은 완료된 작업이 아닌 불필요하게 큰 솔루션을 반영했을 수 있습니다. 일반적인 검토를 통해 이러한 실패 모드에 대해 한 번의 확인을 할 수 있었습니다. 우리는 검토자가 문제 해결에 필요한 것보다 더 크거나 더 복잡한 구현을 표시하도록 의존했으며, 이러한 변경 사항은 여전히 통과되었습니다. 이를 통해 과도한 구현이 전체 증가를 주도하지 않았다는 어느 정도의 확신을 가질 수 있었습니다.

이러한 비교는 통제되지 않았으며, /spec-driven의 효과를 프로젝트 조합이나 에이전트 도구의 광범위한 개선과 분리할 수 없었습니다. 이러한 한계에도 불구하고, 우리는 결과에 고무되었습니다.

아직 개선이 필요한 사항

문서 검토가 병목 현상이 될 수 있습니다.

엔지니어가 해당 분야에 얼마나 익숙한지, 프로젝트의 복잡성과 위험이 어느 정도인지에 따라, 사양을 작성하는 데 30분에서 며칠까지 걸렸습니다. 엔지니어는 /spec-driven을 사용하여 에이전트가 사양 초안을 빠르게 작성하도록 할 수 있지만, 이를 검토하는 데 여전히 시간이 걸렸습니다.

한 번의 작업에서 엔지니어는 research.md가 포함된 풀 리퀘스트를 검토하는 데 몇 시간을 할애했습니다. research.md는 에이전트가 사양 초안을 작성하기 전에 코드베이스, 문서 및 이전 결정에서 파악한 내용을 기록한 작업 파일입니다. 이러한 결과 중 일부는 모호하거나, 정확하지 않거나, 약간 잘못되었습니다.

이 검토를 통해 이러한 파일이 임시 작업 메모인지, 아니면 향후 엔지니어가 신뢰해야 할 문서인지에 대해 합의가 이루어지지 않았다는 사실이 드러났습니다. 일부 엔지니어는 결정이 내려진 과정에 대한 기록을 중요하게 여겼습니다. 다른 사람들은 불완전한 연구 결과를 체크인하면 신뢰할 수 있는 것으로 보일까 봐 걱정했습니다.

한 인프라 팀에서는 구현 전에 사양 검토가 새로운 장애 요소가 되었습니다.

대부분의 검토자는 긴 사양을 읽은 후 코드를 검토하고 싶어 하지 않았습니다. 작업이 끌어오기 요청 단계에 도달했을 때, 인계 시에는 결정 사항, 결정 이유, 위험 요소로 보이는 사항, 결과 확인 방법을 요약해야 했습니다. 방향 자체를 검토해야 하는 경우, 아직 변경하기 쉬운 시점에 더 일찍 검토를 요청해야 했습니다.

프로젝트가 진행됨에 따라 유용한 사양이 변경됩니다.

엔지니어들은 계획을 실행하면서 계속해서 배워나갔습니다. 학습한 내용을 바탕으로 사양을 업데이트하는 데는 작업량이 소요되었습니다. 세부 정보는 에이전트가 무엇을 구축하고 있다고 생각했는지 보여줌으로써 구현 과정에서 도움이 되었습니다. 그 후, 이러한 세부 정보의 대부분이 코드를 반복했습니다.

이제 우리는 프로젝트가 불확실한 동안에는 작동하는 사양이 늘어나야 하고, 코드가 구현을 설명할 수 있게 되면 사양이 줄어들어야 한다고 생각합니다. 남아 있는 부분은 다음 독자가 설계, 중요한 결정, 제약 조건 및 해결되지 않은 위험을 이해하는 데 도움이 되어야 합니다.

완료된 사양은 관련 질문을 제기합니다. 완료된 사양을 어떻게 처리해야 할까요? 우리는 이 질문에 답하는 데 너무 오래 기다렸습니다. 모노레포에 두면 찾기 쉽지만, 아무도 소유하지 않는 문서가 남게 됩니다. 우리는 이를 별도의 보관소로 옮기고 있습니다. 우리는 여전히 나중에 중요한 정보를 보존하는 더 짧은 인계 절차가 필요합니다. 문서가 절약한 것보다 더 많은 작업을 생성했다면, 도움이 되지 않았습니다.

하네스에 피드백 루프 구축하기

때때로 해결책은 또 다른 문서가 아니라 에이전트를 둘러싼 시스템을 변경하는 것이었습니다. 한 가지 예는 /spec-driven이 마크다운을 읽는 방식의 버그였습니다. 예시 내의 제목과 체크박스가 실제 마일스톤이나 미완료 작업으로 오인될 수 있었습니다. 버그를 기록한 후, /spec-driven의 나머지 부분을 검색한 결과, 자체적인 작은 마크다운 파서가 있고 동일한 사각지대가 있는 여러 명령을 발견했습니다. 우리는 이를 하나의 공유 파서로 교체하고, 회귀 테스트와 아키텍처 검사를 추가한 후, 수정 사항을 환경에 적용했습니다. OpenAI는 관련 접근 방식을 하네스 엔지니어링이라고 설명합니다. 즉, 에이전트가 찾을 수 있는 곳에 중요한 지식을 배치하고, 규칙을 시행 가능하게 만들고, 실패를 활용하여 에이전트 주변의 환경을 개선하는 것입니다.

다른 교훈은 테스트나 아키텍처 규칙이 될 수 없었습니다. 우리는 반복되는 실수를 지침으로 정리했습니다. /spec-driven이 예측 가능한 워크플로를 통해 사용자에게 안내하므로, 에이전트가 관련 단계에 도달했을 때 각 학습 내용을 표시할 수 있었습니다. 엔지니어들은 여전히 원래 프로젝트를 넘어 어떤 교훈이 적용되는지 결정했습니다.

우리는 8건의 과거 끌어오기 요청과 관련 없는 조언을 포착하도록 설계된 합성 사례를 통해 가이던스를 테스트했습니다. 후속 조치로, 이러한 과거 작업 중 세 가지를 짧은, 중간, 상세한 프롬프트로 테스트하여 총 9가지 비교를 수행했습니다. 가이던스는 9가지 비교 중 8가지에서 유용한 추가 질문이나 계획 범위를 제시했습니다. 별도의 테스트에서는 과거 작업 3건을 더 다뤘습니다. 이 테스트는 두 가지 계획을 명확히 개선했습니다. 세 번째 계획에서는 가이던스가 없는 에이전트가 이미 문제를 발견했습니다.

가장 유용한 가이던스는 동작 변경, 영향받는 소비자 및 변형, API, 스키마 또는 파서 간의 계약에 대해 질문했습니다. 평가는 질문과 계획에만 적용되었습니다. 지침이 구현 속도를 높였는지 여부는 측정하지 않았습니다. 또한, 좁은 범위의 지침은 더 빨리 쓸모없어졌으며 때로는 관련 없는 업무에서 나타나기도 했습니다.

지침과 평가를 유지하는 데는 첫 번째 버전을 구축하는 것보다 더 많은 작업이 필요했습니다. 우리는 지침을 통해 지뢰를 파악하고, 기본 시스템을 수정하여 지뢰를 제거하거나, 상담원이나 검토자가 다시 지뢰를 찾아야 하는 위험을 감수할 수 있었습니다. 비용이 더 저렴했기 때문에 보통은 먼저 매핑했습니다. 기본 API, 테스트, 문서 또는 예시를 수정하는 데 더 많은 작업이 필요했지만, 모든 사람에게 도움이 되었고 지침이 필요하지 않게 되었습니다.

현재 /spec-driven에 대한 접근 방식

우리는 유용한 마찰 요소를 제거하지 않으면서 엔지니어들이 동일한 프롬프트를 반복하고 프로젝트를 다시 설명하는 것을 막고자 했습니다. 에이전트는 여전히 중요한 질문이 있거나, 증거가 누락되었거나, 다음 단계에 사람의 판단이 필요한 경우 작업을 중단해야 했습니다. 우리는 몇 가지 실용적인 가이드라인을 얻었습니다.

대부분의 작고 국지적인 변경의 경우, 대화나 간단한 계획으로 충분합니다.
방향에 대한 합의를 위해서는 '스펙 우선' 방식을 사용하세요. 후속 세션이나 인계 과정에서도 결정이 유지되어야 하는 경우 사양을 고정하세요.
누락된 모든 부분을 사양에 포함하지 마세요. 하네스는 컨텍스트를 제공하고 검사를 실행해야 합니다. 아키텍처 판단은 여전히 사람의 검토가 필요합니다.

스펙을 유지할 가치가 있다면 다음 읽는 사람을 위해 작성하세요. 의사 결정 사항과 위험 요소를 쉽게 찾을 수 있도록 하고, 증빙 자료를 복사하는 대신 링크를 연결하며, 프로젝트가 종료될 때 사양에 어떤 조치를 취해야 할지 결정하세요.

앞으로의 방향

3개월이 지난 후에도 엔지니어들은 작업이 여러 세션에 걸쳐 지속되거나, 여러 사람에게 전달되거나, 여러 관련 작업으로 나뉘는 경우에도 여전히 /spec-driven을 사용합니다. 엔지니어들은 이를 사용하여 몇 달에 걸친 프로젝트를 계속 진행하고 에이전트가 실행하는 대량의 작업을 체계적으로 관리했습니다. 이는 내부 실험에서 좋은 결과입니다.

더 많은 종류의 업무를 지원하기 위해 /spec-driven을 확장하면서 일부 새로운 기능이 특정 팀의 실제 문제를 해결했지만, 모든 사람의 워크플로를 더 복잡하게 만들었습니다. 다음 버전에서는 더 작고 집중도가 높은 핵심 기능으로 나아가고자 합니다.

사람들은 SDD와 하네스 엔지니어링에 대해 강한 의견을 가지고 있습니다. 저희는 둘 중 하나에 대해 논쟁하는 것보다 실제 업무에 적용해 봄으로써 더 많은 것을 배웠습니다. 이제 더 많은 프로세스를 추가하기 전에 해당 프로젝트에서 에이전트에게 부족한 것이 무엇인지 질문합니다. 작게 시작하여 워크플로가 도움이 되는 부분과 방해가 되는 부분을 파악한 다음, 파악한 내용을 바탕으로 조정하세요.

[1] Birgitta Böckeler, “Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl,” 2025년 10월.

[2] François Zaninotto, “Spec-Driven Development: The Waterfall Strikes Back,” 2025년 11월.

[3] 가브리엘라 곤잘레스, “충분히 상세한 사양은 코드다”, 2026년 3월.

작성자 소개

Walter Li는 Asana의 핵심 스토리지 인프라 팀의 소프트웨어 엔지니어이며, Rohan Batra는 백엔드 프레임워크 팀의 소프트웨어 엔지니어입니다. 두 사람 모두 Agent Success Tiger 팀에 몇 달 동안 소속되어 이 게시물에 설명된 /spec-driven 워크플로의 개발 및 평가를 이끌었습니다.

팀에 대한 감사 인사

/spec-driven을 구상하고 개발하는 데 도움을 주시고 얼리어답터가 되어 주신 Leo Zhang, Karol Krupa, Gordie Levitsky, Mitch Conquer 님께 특별히 감사드립니다.