이제 병목 현상은 코드가 아니라 코드 설명이다

요약 (TL;DR)

• Spec-Kit이 7개월 만에 90,000개의 스타(stars)를 기록했는데, 이는 이제 코드 설명(code description)이 구축 과정에서 가장 느린 부분이 되었기 때문입니다.
• 코드를 작성하는 것은 더 이상 어려운 부분이 아닙니다. AI에게 무엇을 만들지 충분히 명확하게 전달하는 것이 어려운 부분입니다.
• 실제 시스템을 출시하는 빌더(Builders)들은 단순히 프롬프팅 (prompting)을 잘하는 것을 넘어, 명세 작업 (spec work)에 더 능숙해져야 합니다.

Spec-Kit이 7개월 만에 90,000개의 스타를 기록했습니다. 이것이 바로 신호입니다. 코드 설명이 새로운 병목 현상 (bottleneck)이며, 이를 해결하는 도구들은 개발 스택 (dev stack)의 그 어떤 것보다 빠르게 성장하고 있습니다.

왜 Spec-Kit은 이렇게 빠르게 성장했는가?

AI는 코드를 작성할 수 있지만, 당신의 마음을 읽을 수는 없기 때문입니다.

Spec-Kit은 특정한 고통을 해결합니다. 바로 AI가 정확하게 작업할 수 있도록 충분한 문맥 (context)을 가질 수 있게끔 코드가 무엇을 하는지 문서화하는 것입니다. 이는 화려한 문제는 아닙니다. 하지만 실질적인 문제입니다. 대부분의 빌더들이 이를 느껴왔을 것입니다. Claude나 Cursor에 엉망인 저장소 (repo)를 건네주면 결과물의 품질이 빠르게 저하됩니다. 모델은 무엇이 무엇과 연결되어 있는지 알지 못합니다. 코드 설명이 그 간극을 메워줍니다. Spec-Kit이 이렇게 빠르게 성장했다는 것은 그 간극이 엄청나게 컸음을 말해줍니다.

이것이 자동화를 출시하는 빌더들에게 무엇을 의미하는가?

기술의 중심이 작성(writing)에서 설명(describing)으로 이동하고 있으며, 대부분의 빌더들은 아직 이를 따라잡지 못했습니다.

저는 호주의 서비스 기업들을 위해 음성 AI 에이전트(voice AI agents)와 N8N 워크플로우(workflows)를 구축하여 납품합니다. 금융 브로커, 보험사, 회계 법인 등이 주요 고객입니다. 이제 구축(build) 자체는 매우 빠르게 진행됩니다. Claude Code를 사용하면 Retell AI 에이전트를 GHL에 연결하는 작업을 예전보다 훨씬 짧은 시간 안에 완료할 수 있습니다. 하지만 여전히 모든 과정을 느리게 만드는 부분은 무엇일까요? 바로 단 한 줄의 코드가 실행되기 전에 사양(spec)을 정확하게 정의하는 것입니다. 에이전트가 무엇을 말해야 하는가? 어떤 조건에서 작동해야 하는가? 통화가 잘못될 경우 어떤 일이 발생하는가? 이것은 아직 코드가 존재하지 않을 때조차도 코드 설명(code description) 작업에 해당합니다. 이것이 바로 계획 모드(Plan Mode)가 모든 자동화 구축 단계 중 가장 비용이 적게 드는 단계인 이유입니다. 설명(description)의 문제를 구축(build)의 문제로 만들기 전에 미리 해결하는 것이기 때문입니다.

코드 설명은 실제로 어디에서 무너지는가?

코드 설명은 인수인계(handover) 시점, 범위(scope) 변경 시점, 그리고 새로운 사람이 시스템을 만질 때마다 무너집니다.

대부분의 팀이 고통을 느끼는 지점은 다음과 같습니다:

• N8N으로 구축된 워크플로우에 문서화(documentation)가 되어 있지 않습니다. 다음 빌더는 이를 역공학(reverse-engineering)하지 않고서는 확장할 수 없습니다.
• 음성 에이전트 프롬프트(prompt)가 작성 당시에는 작성자에게 말이 되는 것처럼 보였습니다. 하지만 6주가 지나면, 왜 특정 분기(branch)가 존재하는지 아무도 기억하지 못합니다.
• 고객이 변경 사항을 요청합니다. 빌더는 무언가를 건드리기 전에 시스템 전체를 다시 읽어야 합니다.
• 인수인계(handover) 통화가 깔끔한 지식 전달(knowledge transfer) 대신 2시간짜리 고고학 세션으로 변질됩니다.

코드 설명은 단순히 AI 도구가 여러분의 코드베이스(codebase)를 읽는 것만을 의미하지 않습니다. 그것은 인간이 무엇이 구축되었는지를 이해하는 것에 관한 것입니다. 이 과정을 건너뛰면 두 가지 문제 모두 심화됩니다. 저희는 모든 인수인계 과정에 설명(description)의 규율을 녹여냅니다. 저희가 고객에게 제공하는 오프보딩 키트(offboarding kit)에 정확히 일반 텍스트 형태의 프롬프트를 포함하는 이유도 바로 이 때문입니다.

코드 설명은 기술의 문제인가, 도구의 문제인가?

둘 다입니다. 하지만 기술(Skill)이 우선입니다.

Spec-Kit은 도구입니다. 도움을 주죠. 하지만 도구가 불분명한 사고를 해결해주지는 않습니다. 시스템이 무엇을 해야 하는지 평이한 영어(Plain English)로 설명할 수 없다면, 어떤 도구를 사용하더라도 빌드(Build)를 살릴 수 없습니다. 현재 Claude Code로부터 최고의 결과물을 얻어내고 있는 개발자와 AI 빌더들은 반드시 타자 속도가 가장 빠르거나 프롬프트 엔지니어링 (Prompt Engineering) 지식이 가장 깊은 사람들이 아닙니다. 그들은 시작하기 전에 명확하고 구체적인 브리프(Brief)를 작성할 수 있는 사람들입니다. 그것은 글쓰기 기술입니다. 사고 기술입니다. 그리고 현재 매우 부족한 상태입니다. McKinsey의 AI 보조 개발에 관한 광범위한 연구에 따르면, 출력 품질의 핵심 동력은 모델도, 도구도 아닌 명세(Specification)의 품질임을 일관되게 지적하고 있습니다. 바로 입력값(Input)입니다.

빌드 프로세스에서 실제로 무엇을 바꿔야 하는가?

IDE를 열기 전에 명세(Spec)를 작성하세요. 매번 말입니다.

당연한 소리처럼 들릴 것입니다. 하지만 이를 일관되게 실천하는 사람은 거의 없습니다. 제 빌드 과정에서 실제로 적용되는 방식은 다음과 같습니다:

• 어떤 도구도 열기 전에 시스템이 수행해야 할 일을 평이한 영어로 작성합니다.
• 예외 케이스(Edge cases)를 명시적으로 정의합니다. 호출이 끊기면 어떻게 되나요? CRM 필드가 비어 있다면? 잠재 고객(Lead)이 거절한다면?
• 모든 워크플로우 노드(Workflow node)의 기능뿐만 아니라 의도(Intent)를 문서화합니다. 미래의 당신이 현재의 당신에게 감사하게 될 것입니다.
• 명세를 사전 작업(Pre-task)이 아닌 산출물(Deliverable)로 취급하세요. 명세는 프로젝트에서 그 자체로 하나의 항목(Line)을 차지할 가치가 있습니다.

이것은 우리가 인수인계 콜(handover call)에 비용을 청구하는 이유와 같습니다. 문서화(Documentation)와 설명 작업은 실제 노동입니다. 이는 세 배의 비용이 드는 재구축(rebuild)을 방지합니다.

핵심 요약 (Key Takeaways)

• Spec-Kit이 7개월 만에 90,000개의 스타(stars)를 기록하며 성장한 것은 명확한 신호입니다. 코드 설명(code description)이 현재 AI 보조 개발(AI-assisted development)의 병목 현상(bottleneck)이라는 것입니다.
• 코드를 작성하는 것은 더 이상 어려운 부분이 아닙니다. AI가 신뢰할 수 있게 동작할 수 있을 만큼 명확하게 원하는 바를 설명하는 것이 어려운 부분입니다.
• 명세(specs)와 문서화(documentation)에 대한 빌더(Builder)의 규율은 모든 인수인계(handover), 모든 변경 요청(change request), 그리고 새로 추가되는 모든 시스템(new system)에서 보상으로 돌아옵니다.

만약 비즈니스를 위한 자동화(automation)를 구축하고 있는데 여러분의 명세가 구조(structure)보다는 느낌(vibes)에 의존하고 있다면, 비용이 발생하기 전에 이를 바로잡아야 합니다. 저에게 AUDIT이라고 DM을 보내주시면, 제가 새로운 빌드(build)에 착수하기 전 던지는 다섯 가지 질문을 보내드리겠습니다.

원문은 theautomate.io에 게시되었습니다.