명세를 읽으세요: 구현하기 전에 의도를 확정하세요

저는 에이전트 기반 코딩 (agentic coding)에 대해 사람들이 서로 매우 다른 것을 원한다는 점을 이해해가고 있습니다. 이는 놀라운 일이 아닙니다. 모든 사람이 같은 종류의 소프트웨어를 만드는 것은 아닙니다. 모든 사람이 같은 종류의 조직에서 일하는 것도 아닙니다. Claude Code, Codex, Cursor, Gemini 또는 다른 어떤 코딩 에이전트를 실행할 때 모든 사람이 동일한 문제를 해결하려고 시도하는 것도 아닙니다.

어떤 사람들에게 에이전트 기반 코딩은 탐색을 위한 방법입니다. 그들은 아이디어는 있지만 아직 확정된 설계 (design)는 없습니다. UI의 세 가지 버전을 시도해 보거나, API 형태를 살펴보거나, 라이브러리를 테스트하거나, 문제가 실제로 무엇인지 배우기 위해 일회성 프로토타입 (prototype)을 구축하고 싶어 합니다. 그것은 유효한 작업 방식입니다. 저도 그렇게 합니다. 소프트웨어의 형태를 파악하고 있을 때, 저는 종종 소프트웨어가 저의 가설에 반론을 제기해주기를 필요로 합니다.

하지만 그것이 소프트웨어 개발의 유일한 모드는 아닙니다. 그리고 많은 진지한 소프트웨어 팀들에게 그것은 일반적인 모드가 아닙니다. 제가 함께 일했던 대부분의 소프트웨어 기업에서는 개발자들에게 다음과 같이 말하는 것이 허용되지 않을 것입니다: "여러 가지 다른 것들을 프로토타입으로 만들어 오세요. 그러면 제품 팀 (product team)이 어떤 것을 선호할지 결정하겠습니다." 그것은 프로세스가 아닙니다. 그것은 비용이 많이 드는 모호함 (ambiguity)입니다. 주말 동안 아이디어를 해킹하는 창업자에게는 효과가 있을 수 있습니다. 새로운 도메인을 이해하려는 1인 개발자에게는 효과가 있을 수 있습니다. 하지만 제품 소유자 (product owners), 비즈니스 분석가 (business analysts), 고객, 인도 약속 (delivery commitments), 아키텍처 제약 사항 (architecture constraints), 컴플라이언스 기대치 (compliance expectations), 그리고 릴리스 게이트 (release gates)가 있는 팀에서는, 구현이 통제 불능 상태가 되기 전에 작업이 명시적으로 변해야 합니다.

이것이 저에게 명세 기반 개발 (spec-driven development, SDD)이 의미하는 바입니다. 그것은 단순히 서류 작업을 위한 것이 아닙니다. 그것은 무거운 요구사항 문서 (requirements documents)로의 향수 어린 회귀가 아닙니다. 그것은 엔지니어의 속도를 늦추기 위한 방법도 아닙니다. 명세 기반 개발은 합의를 형성하는 것에 관한 것입니다. 코드가 작성되기 전에, 팀은 소프트웨어가 무엇을 해야 하는지에 대한 공유된 이해 (shared understanding)가 필요합니다. 제품 의도 (product intent), 고객 의도 (customer intent), 비즈니스 규칙 (business rules), 엣지 케이스 (edge cases), 비목표 (non-goals), 어휘 (vocabulary), 그리고 제약 사항 (constraints) 모두가 어딘가에 기록되어 존재해야 합니다.

역사적으로 볼 때, 이를 위한 매체로서 여전히 단어(words)보다 더 나은 것은 없습니다. 우리는 다이어그램(diagrams)을 그릴 수 있습니다. 스크린샷(screenshots)을 가리킬 수 있습니다. 티켓(tickets)을 연결하거나 채팅 스레드(chat threads)를 붙여넣을 수도 있습니다. 하지만 결국 우리가 의도하는 바는 다른 사람, 혹은 이제는 다른 에이전트(agent)가 그에 따라 행동할 수 있을 만큼 언어로 명확하게 표현되어야 합니다. 이것이 바로 에이전트 기반 코딩(agentic coding)이 날카롭게 드러내는 격차입니다. 코딩 에이전트(coding agents)는 코드를 생성하는 데 매우 능숙합니다. 코드를 읽는 능력도 점점 더 좋아지고 있습니다. 이들은 대규모 리포지토리(repositories)를 탐색하고, 패턴을 추론하며, 테스트를 실행하고, 몇 년 전의 어떤 인간 팀도 상상할 수 없었던 속도로 변경 사항을 적용할 수 있습니다. 하지만 그들은 여전히 우리가 무엇을 의도하는지 알아야 합니다. 의도(intent)가 모호하면 출력물(output)도 모호해질 것입니다. 어휘(vocabulary)가 일관되지 않으면 구현(implementation)은 표류하게 됩니다. 제품(product) 팀과 엔지니어링(engineering) 팀이 동작(behavior)에 대해 합의하지 않았다면, 이해관계자들이 머릿속에 세 가지 서로 다른 해석을 품고 있는 동안 에이전트는 기꺼이 그중 한 가지 해석만을 코드로 인코딩할 것입니다. 이것이 바로 팀 소프트웨어(team software) 개발에서 "그냥 에이전트가 무언가를 만들게 두라"는 식의 접근이 충분하지 않은 이유입니다. 문제는 에이전트가 코드를 생성할 수 있느냐가 아닙니다. 그들은 할 수 있습니다. 문제는 팀이 에이전트가 이를 바탕으로 구축할 수 있고, 리뷰어(reviewers)가 이를 기준으로 평가할 수 있으며, 미래의 유지보수자(maintainers)가 이해할 수 있는 지속 가능한 의도의 표현(durable expression of intent)을 만들어냈는가 하는 점입니다. 이것이 바로 Spec Kitty가 집중하고 있는 부분입니다. Spec Kitty는 그러한 단어들에 도달하는 경로를 가속화합니다. 이는 의도를 서로 다르지만 연결된 두 가지 산출물(artifacts)로 분해하도록 돕습니다:

무엇을(The What): 명세(specification). 소프트웨어가 무엇을 해야 하는가? 누구를 위한 것인가? 사용자 시나리오(user scenarios)는 무엇인가? 수락 기준(acceptance criteria)은 무엇인가? 명시적으로 범위 밖(out of scope)인 것은 무엇인가?

어떻게(The How): 계획(plan). 시스템이 어떻게 변경되어야 하는가? 어떤 아키텍처 결정(architecture decisions)이 중요한가? 어떤 파일, 서비스, 데이터 모델(data models), API, 또는 워크플로(workflows)가 관여하는가? 리스크(risks), 의존성(dependencies), 그리고 순서(sequencing)에 관한 우려 사항은 무엇인가?

이러한 구분은 중요합니다. 제품 소유자(product owner)가 고객의 의도를 표현하기 위해 구현 세부 사항(implementation details)까지 명시할 필요는 없어야 합니다.

개발자는 절반만 작성된 티켓(ticket)으로부터 제품의 의미를 추론해야 할 필요가 없어야 합니다. 리뷰어는 디프(diff)로부터 의도된 동작을 역공학(reverse-engineer)해야 할 필요가 없어야 합니다. 명세(spec)와 계획(plan)은 가교를 형성합니다. 그러면 작업은 작업 패키지(work packages)로 분해될 수 있고, 명시된 의도에 따라 검토될 수 있으며, 명확한 기준에 따라 수락될 수 있습니다. 그 과정에서 팀 자체의 규칙들을 적용할 수 있습니다: 품질 게이트(quality gates), 공통 어휘(common vocabularies), 아키텍처 제약 사항(architecture constraints), 테스트 기대치(testing expectations), 용어집(glossary terms), 리뷰 정책(review policies), 그리고 조직 내에 축적된 어렵게 얻은 베스트 프랙티스(best practices)들이 그러합니다. 사람들이 명세 기반 개발(spec-driven development)을 단순히 "코딩하기 전에 프롬프트를 작성하는 것"으로 축소할 때 놓치는 부분이 바로 이것입니다. 명세는 단순한 프롬프트가 아닙니다. 그것은 합의의 지점입니다. 제어 표면(control surface)입니다. 그것은 팀이 다음과 같이 말하는 장소입니다: 이것이 우리의 의미이며, 이것이 중요하고, 이것이 우리가 작업 완료 여부를 알 수 있는 방법이다. 탐색을 위한 여지는 항상 존재할 것입니다. 때로는 프로토타입(prototypes)이 필요할 수도 있습니다. 때로는 빠른 실험이 필요할 수도 있습니다. 때로는 원하는 것을 알기 전에 에이전트(agent)를 스케치패드(sketchpad)로 사용해야 할 수도 있습니다. 하지만 작업이 실질적이 될 때, 다른 사람들이 그 작업에 의존하게 될 때, 소프트웨어가 제품, 코드베이스(codebase), 고객과의 약속, 그리고 팀 프로세스에 부합해야 할 때, 의도는 반드시 기록되어야 합니다. 소프트웨어의 미래는 인간이 의도를 표현하고 AI가 이를 구현하는 모습일지도 모릅니다. 하지만 그 미래는 의도를 잘 표현하는 우리의 능력에 달려 있습니다. 그래서 저에게 있어, 이 모든 것은 결국 한 가지로 귀결됩니다: 명세를 읽으세요. Spec Kitty는 에이전트 기반 코딩(agentic coding)을 위한 오픈 소스 SDD 프레임워크입니다. 한번 사용해 보세요!