명세 기반 AI 개발 방법론 (Spec-Driven AI Development)

AI가 실패하는 이유는 단지 신뢰할 수 없기 때문만은 아닙니다.

AI는 우리가 설명하지 않은 기대치를 충족하라고 요구할 때 자주 실패합니다.

이것이 제가 생각하는 명세 기반 개발 (Spec-driven development)의 핵심입니다.

프로세스가 아닙니다. 문서화 쇼 (Documentation theater)도 아닙니다. 느린 소프트웨어 전달 방식으로의 회귀도 아닙니다.

명세 기반 개발이란 AI가 작업을 올바르게 수행하는 데 필요한 정보, 즉 목적 (Purpose), 맥락 (Context), 경계 (Boundaries), 제약 조건 (Constraints), 아키텍처 (Architecture), 비즈니스 기대치 (Business expectations), 수락 기준 (Acceptance criteria), 그리고 리뷰 게이트 (Review gates)를 제공하는 관행입니다.

AI가 어떤 기대치를 충족해야 한다면, 그 기대치는 반드시 AI가 접근할 수 있는 상태여야 합니다.

당연한 소리처럼 들릴 것입니다.

하지만 실제로 많은 AI 보조 프로젝트가 무너지는 지점이 바로 여기입니다.

다루는 내용

• 목표는 더 많은 코드를 만드는 것이 아니다
• AI는 볼 수 있는 기대치만을 충족할 수 있다
• 인간의 언어가 인터페이스가 된다
• 명세 기반 개발은 알려진 사실(Knowns)에서 시작한다
• 인간의 업무는 한 단계 높은 수준으로 이동한다
• 좋은 명세는 기대치를 실행 가능하게 만든다
• 계획은 업무를 위임 가능하게 만든다
• 구현 단계에서 무언가를 발명해서는 안 된다
• 리뷰는 신뢰 파이프라인이 된다
• 나에게 효과적이었던 방법
• 다뤄야 할 열린 질문들
• 결론

목표는 더 많은 코드를 만드는 것이 아니다

목표는 더 많은 코드를 더 빠르게 생산하는 것이 아닙니다.

그것은 너무 작은 목표입니다.

엔터프라이즈 소프트웨어에는 사용자, 데이터, 보안 경계 (Security boundaries), 컴플라이언스 압박 (Compliance pressure), 레거시 시스템 (Legacy systems), 감사 질문 (Audit questions), 운영 (Operations), 예산, 마감일, 그리고 시스템이 왜 그렇게 동작하는지 이해해야 하는 사람들이 있습니다.

AI는 구현을 더 빠르게 만들 수 있지만, 그것은 단지 표면적인 부분일 뿐입니다.

AI를 잘 활용하면 엔터프라이즈 요구사항을 가시화하는 데에도 도움을 줄 수 있습니다. 보안 경계가 커버되었는지 확인할 수 있습니다. 데이터가 시스템을 통해 어떻게 흐르는지 설명할 수 있습니다. 테스트를 지목할 수 있습니다. 아키텍처 결정 (Architectural decisions)을 요약할 수 있습니다. 감사 증거 (Audit evidence)를 준비할 수 있습니다. 그리고 다음과 같이 질문하는 인간에게 답할 수 있습니다: "이 주제가 어떻게 다뤄지고 있나요? 보여주세요. 설명해 주세요. 증명해 주세요."

그것이 훨씬 더 흥미로운 목표입니다.

AI 보조 전달 (AI-assisted delivery)은 팀이 기대치를 충족하고, 제약 사항을 준수하며, 설명 가능하고, 테스트 가능하며, 감사 (audit) 가능한 소프트웨어를 구축할 수 있도록 도와야 합니다.

이를 위해서는 공유된 지식 계층 (shared knowledge layer)이 필요합니다.

제 관점에서 이것이 명세 (spec)의 가장 중요한 역할 중 하나입니다. 명세는 인간과 AI 모두를 위한 중앙 집중식의 포괄적인 지식입니다. 사람은 의도 (intent), 경계 (boundaries), 결정 사항 (decisions), 그리고 수락 기준 (acceptance criteria)을 확인할 수 있습니다. AI 에이전트 (AI agents)는 동일한 소스를 사용하여 작업을 구현, 설명, 테스트 및 증명할 수 있습니다.

하지만 이는 AI가 추론할 수 있는 적절한 정보를 가지고 있을 때만 가능합니다.

AI는 볼 수 있는 기대치만을 충족할 수 있다

알고 있다면, 기록하십시오.

너무 단순하게 들릴 수도 있지만, 이것이 전체 워크플로 (workflow)의 중심입니다.

비즈니스 이유를 알고 있다면, 기록하십시오.

기술적 경계 (technical boundary)를 알고 있다면, 기록하십시오.

기존 아키텍처 패턴 (architecture pattern)을 알고 있다면, 기록하십시오.

보안 제약 사항 (security constraint)을 알고 있다면, 기록하십시오.

무엇이 결과를 잘못되게 만드는지 알고 있다면, 기록하십시오.

AI 에이전트는 당신의 기억을 공유하지 않습니다. 작업 (task)에 해당 정보가 포함되어 있지 않는 한, 그들은 회의, 정치적 제약, 레거시의 흔적 (legacy scar), 제품에 대한 약속, 감사 압박, 또는 아키텍처 규칙을 알지 못합니다.

알고 있는 것부터 시작하십시오:

• 목적, 의도, 그리고 비즈니스 관점
• 경계, 비목표 (non-goals), 그리고 기존 컨텍스트 (context)
• 기술 스택 (tech stack) 및 아키텍처 결정 사항
• 보안, 컴플라이언스 (compliance), 그리고 운영 제약 사항
• 수락 기준 (acceptance criteria) 및 검토 질문

기대치가 더 잘 기술될수록, AI가 추측해야 하는 부분은 줄어듭니다.

그리고 추측은 전달 리스크 (delivery risk)가 시작되는 지점입니다.

인간의 언어가 인터페이스가 된다

프로그래밍 언어는 항상 인간과 컴퓨터 사이의 인터페이스 역할을 해왔습니다.

하지만 프로그래밍 언어는 어느 쪽에게도 모국어였던 적이 없습니다.

인간은 목표 (goals), 제약 조건 (constraints), 트레이드오프 (tradeoffs), 예시 (examples), 리스크 (risks), 그리고 이야기 (stories)를 통해 사고합니다. 그런 다음 우리는 이를 TypeScript, Python, SQL 또는 시스템이 필요로 하는 어떤 스택으로든 번역합니다. 컴퓨터는 여전히 훨씬 더 낮은 수준에서 명령을 실행하는 파서 (parsers), 컴파일러 (compilers), 인터프리터 (interpreters), 런타임 (runtimes), 운영 체제 (operating systems), 그리고 머신 (machines)을 필요로 합니다.

프로그래밍 언어는 양측 모두가 사용할 수 있는 중간 계층 (middle layer)입니다.

그것들은 강력하고, 정밀하며, 필수적입니다.

하지만 인간에게 프로그래밍 언어는 여전히 제2외국어입니다.

수십 년 동안 소프트웨어 개발은 대부분 단방향이었습니다. 인간이 의도 (intent)를 코드로 번역하면, 기계는 이를 수락하거나 거부했습니다. 피드백 루프 (feedback loop)는 존재했지만, 컴퓨터는 우리 자신의 언어로 우리와 의도를 논의하지 않았습니다.

그것이 바로 패러다임 전환 (paradigm shift)입니다.

AI 지원 개발 (AI-assisted development)을 통해 인간의 언어는 양방향 인터페이스 (two-way interface)가 됩니다. 우리는 목표, 제약 조건, 동작, 예시, 리스크, 그리고 검토 질문을 설명할 수 있습니다. AI는 이에 응답하고, 명확히 하기 위한 질문을 던지며, 트레이드오프를 설명하고, 코드를 검사하며, 테스트를 생성하고, 아키텍처를 요약하며, 그 결과를 구현 (implementation)으로 번역하는 것을 도울 수 있습니다.

이것이 프로그래밍 언어의 중요성이 사라진다는 의미는 아닙니다.

그것들은 여전히 매우 중요합니다. 런타임 동작 (runtime behavior), 타입 시스템 (type systems), 패키지 생태계 (package ecosystems), 성능 (performance), 보안 (security), 배포 (deployment), 그리고 유지보수성 (maintainability)은 여전히 실재하는 요소들입니다.

하지만 인간 인터페이스의 관점에서 볼 때, 더 높은 수준의 산출물 (artifact)은 더 이상 코드만이 아닙니다.

그것은 명세 (spec), 아키텍처 (architecture), 수락 기준 (acceptance criteria), 검토 체크리스트 (review checklist), 그리고 에이전트 (agents)에게 무엇이 기대되는지 그리고 그들의 작업이 어떻게 확인될 것인지를 알려주는 재사용 가능한 지침 (reusable instructions)입니다.

명세 기반 개발은 '알려진 사실'에서 시작됩니다

소프트웨어 팀은 항상 계획을 세워왔습니다.

폭포수 (Waterfall) 모델은 구현 전에 집중적으로 계획을 세웠습니다. 애자일 (Agile)은 이에 반대하며 계획을 인도 (delivery) 시점에 더 가깝게 이동시켰습니다. 사용자 스토리 (User stories), 아키텍처 결정 기록 (architecture decision records), RFC, 티켓 (tickets), 수락 기준 (acceptance criteria), 그리고 스프린트 계획 (sprint planning)은 모두 동일한 근본적인 문제에서 비롯되었습니다.

소프트웨어는 실수로 만들어지기에는 너무나 비용이 많이 듭니다.

명세 기반 개발 (Spec-driven development)은 '알려진 사실 (knowns)'에서 시작됩니다.

이는 폭포수 (Waterfall) 모델의 강점 중 일부, 즉 정밀함(precision), 가능한 범위 내에서의 완전성(completeness), 그리고 비용이 많이 드는 작업이 시작되기 전에 기대 사항을 명시적으로 만들려는 진지한 시도를 제공합니다.

하지만 폭포수 모델의 약점까지 물려받아서는 안 됩니다.

명세 (Spec)는 초기에 돌에 새겨진 듯 고정된 것이 아닙니다.

그것은 살아있는 문서 (living document)입니다.

이 지점이 바로 애자일 (Agile)의 유용한 부분을 취하는 곳입니다. 첫 번째 유용한 구현이 일어나기 전에 전체 최종 시스템을 모두 기술할 필요는 없습니다. 현재 알려진 것을 기술하고, 그것을 바탕으로 구현하며, 학습하고, 다음 기능, 다음 워크플로 (workflow), 다음 제약 조건, 또는 다음 아키텍처 결정 (architectural decision)을 위해 명세를 확장해 나갑니다.

중요한 차이점은 반복 (iteration)이 추측을 의미하지 않는다는 것입니다.

각 반복은 구현이 시작되기 전에 여전히 알려진 사실 (knowns)을 명시적으로 만들어야 합니다.

바이브 코딩 (Vibe coding)은 하나의 증상입니다. 탐색 단계에서는 효과적일 수 있지만, 인간이 AI에게 제공되지 않은 비즈니스 의도 (business intent), 아키텍처 규칙 (architecture rules), 보안 제약 조건 (security constraints), 그리고 제품 기대 사항 (product expectations)을 알고 있기를 기대할 때, 이는 인도 모델 (delivery model)로서 무너집니다. 명세 기반 개발 (Spec-driven development)은 질문을 "AI가 충분히 추측할 수 있는가?"에서 "우리가 AI에게 올바른 정보, 경계 (boundaries), 그리고 검증 항목 (checks)을 제공했는가?"로 바꿉니다.

과거의 계획 (Planning)은 인간과 인간을 정렬시키는 것이었습니다.

명세 기반 개발은 인간과 인간, 그리고 인간과 AI를 정렬시켜야 합니다.

인간의 업무는 한 단계 위로 이동합니다

알려진 사실이 명시되면, 인간의 역할이 변화합니다.

가장 가치 있는 인간의 업무는 목적 (purpose), 비즈니스 압박 (business pressure), 아키텍처 (architecture), 그리고 리스크 (risk)에 더 가까워집니다.

업무는 어떤 결과가 중요한지, 트레이드오프 (tradeoffs)가 어디에 있는지, 그리고 기존 시스템이 어떻게 동작하는지를 설명하는 것이 됩니다. 또한 유지보수성 (maintainability), 운영 (operations), 컴플라이언스 (compliance), 소유권 (ownership), 그리고 리스크와 같은 경계, 실패 모드 (failure modes), 그리고 인도 제약 조건 (delivery constraints)을 명시하는 것을 의미합니다.

그렇다고 해서 엔지니어링이나 아키텍처적 판단이 덜 중요해지는 것은 아닙니다.

오히려 그러한 사고의 중요성이 더 커지는 것입니다.

만약 당신이 스스로의 가치를 직접 작성하는 코드의 줄 수로만 측정한다면, AI는 위협으로 느껴질 것입니다. 하지만 당신의 가치를 비즈니스 요구사항을 견고한 시스템으로 얼마나 잘 전환하느냐로 측정한다면, AI는 레버리지 (Leverage)가 됩니다.

인간의 역할은 더 이상 구현 (Implementation)을 생산하는 것만이 아닙니다.

인간의 역할은 구현이 위임되고, 검증되며, 설명되고, 개선될 수 있을 만큼 기대치를 명확하게 만드는 것입니다.

인간이 목적, 경계, 그리고 리스크를 더 잘 정의할수록, AI는 워크플로 (Workflow)를 더 잘 처리할 수 있습니다: 명세 (Spec) 작성, 작업 계획, 범위가 지정된 티켓 (Ticket) 구현, 그리고 결과 검토.

좋은 명세는 실행 가능한 기대치를 만든다

당연한 질문이 곧 뒤따라옵니다: 어떻게 하면 좋은 명세를 얻을 수 있을까?

저에게 그것은 어려운 일이었습니다.

명세 기반 개발 (Spec-driven development)에 대한 저의 첫 실질적인 접점은 Kiro specs를 통해서였습니다. 이후 저는 GitHub Spec Kit, Tessl의 명세 기반 개발 워크플로, 그리고 유사한 접근 방식들을 살펴보았습니다. 개념적으로 저는 그 방향성이 즉시 마음에 들었습니다: 요구사항 (Requirements), 설계 (Design), 작업 (Tasks), 구현 (Implementation), 검토 (Review).

하지만 실제로는 여전히 너무 많은 수동 작업이 필요했습니다.

너무 많은 작성 작업. 너무 많은 수동 단계. 그리고 업무 압박 속에서 바쁜 팀들이 일관되게 충분한 품질로 채워 넣기에는 너무 과도한 구조.

그러한 도구들은 개념적이고 기술적인 관점에서는 가치가 있습니다. 하지만 엔터프라이즈 수준의 인도 (Delivery)를 위해서는 워크플로가 실행 가능해야 합니다. 만약 매번 인간이 완벽한 명세, 티켓, 그리고 검토 노트를 수동으로 작성해야 한다면, 그 워크플로는 실패할 것입니다.

그렇기 때문에 저는 명세 워크플로 자체가 AI의 지원을 받고 자동화되어야 한다고 생각합니다.

명세는 인간의 판단이 속해야 하는 핵심적인 영역이지만, AI는 명세를 생성하고, 검증하며, 수정하고, 검토하는 것을 도와야 합니다. 그렇지 않으면 인간은 여전히 명세를 작성하고, 명세를 수정하고, 컨텍스트 (Context)를 수집하고, 계획을 티켓으로 나누고, 범위를 관리하며, 구현 내용을 의도와 비교하고, 팀의 정렬 (Alignment)을 유지해야만 합니다.

그것이 바로 사람들이 피곤하거나, 서두르거나, 인도(Delivery) 압박을 받을 때 일관성이 깨지게 되는 작업들입니다.

이것이 제가 sebastianwessel/skills를 만든 이유입니다. 시니어의 판단력을 대체하기 위해서가 아니라, 시니어의 판단력을 재사용 가능한 컨텍스트(Context), 게이트(Gates), 그리고 지침(Instructions)으로 옮기기 위해서입니다.

Skills: 판단을 가이드로 전환하기

저의 접근 방식은 AI에게 "좋은 명세(Spec)를 작성해줘"라고 요청하고 결과가 좋기를 바라는 것이 아닙니다.

Skills는 AI에게 명세를 작성하고 유지 관리하기 위한 운영 모델(Operating model)을 제공합니다. 이는 AI에게 '좋음'이 무엇을 의미하는지 알려줍니다. 즉, 간결하고(Concise), 공백이 없으며(Gap-free), 추적 가능하고(Traceable), 구현 준비가 되어 있으며(Implementation-ready), 에이전트(Agents)가 추측할 필요가 없을 정도로 명확해야(Explicit) 한다는 것을 의미합니다.

인간은 의도(Intent), 컨텍스트(Context), 제약 조건(Constraints), 그리고 결정 사항(Decisions)을 제공합니다.

AI는 Skills를 사용하여 해당 입력을 정밀한 명세로 전환하고, 집중적인 질문을 던지며, 공백을 찾아내고, 자료를 구조화하며, 일관성을 유지하고, 프로젝트가 진화함에 따라 진실의 원천(Source of truth)을 깨끗하게 유지합니다.

이것이 제가 원하는 업무 분담입니다. 인간은 무엇이 중요한지 결정하고, AI는 그 기대 사항을 사용 가능하게 만드는 데 필요한 규율 있는 명세 작업(Spec work)을 처리합니다.

명세 작성은 반복적인 루프(Iterative Loop)입니다

명세를 작성하는 것은 한 번에 방대한 문서를 쏟아내는 작업이 아닙니다.

그것은 위에서 아래로 이어지는 반복적인 루프(Iterative loop)입니다.

저는 전체적인 목적부터 시작합니다. 무엇이 존재해야 하는지, 그것이 왜 중요한지, 누구를 위한 것인지, 어떤 비즈니스 결과(Business outcome)를 지원하는지, 그리고 이미 알려진 제약 조건은 무엇인지 정의합니다.

그 다음 기능(Features), 워크플로(Workflows), 경계(Boundaries), 인터페이스(Interfaces), 데이터(Data), 실패 모드(Failure modes), 보안(Security), 운영(Operations), 그리고 수락 기준(Acceptance criteria)으로 내려갑니다.

각 단계에서 저는 AI를 단순히 과업 수행자(Task fulfiller)로만 사용하지 않습니다.

저는 AI를 스파링 파트너(Sparring partner)로 사용합니다. 저는 AI가 저의 제안에 이의를 제기하고, 취약한 가정에 반박하며, 제 아이디어가 아직 충분히 정밀하지 않은 부분이 어디인지 말해주기를 바랍니다.

• 공백(Gaps)은 어디에 있는가?
• 이 제안에서 어떤 점에 이의를 제기하겠는가?
• 누락된 예외 경로(Unhappy paths)는 무엇인가?
• 이 단계가 실패할 때 어떤 일이 일어나야 하는가?
• 어떤 인터페이스나 의존성(Dependencies)이 불분명한가?
• 운영 환경(Production)에서 어떤 리스크가 예상되는가?

그 지점이 바로 AI가 매우 유용하게 쓰이는 곳입니다. AI는 인간이 편안하게 기억할 수 있는 수준보다 더 큰 컨텍스트 (Context)를 유지할 수 있습니다. AI는 의존성 트리 (Dependency trees), 인터페이스 (Interfaces), 흐름 (Flows), 그리고 엣지 케이스 (Edge cases)를 추적할 수 있습니다. 또한 인간이 피곤할 때 건너뛰곤 하는 지루한 질문들을 반복해서 던질 수 있습니다.

이것이 바로 저의 spec-architect 스킬이 구축된 핵심 원리입니다. 명세 (Spec)는 단순히 그럴듯하게 들린다고 해서 준비된 것이 아닙니다. 에이전트 (Agent)가 동작 (Behavior), 인터페이스 (Interfaces), 실패 (Failures), 보안 (Security), 데이터 (Data), 복구 (Recovery), 릴리스 (Release), 관측 가능성 (Observability), 또는 테스트 (Tests)에 대해 별도로 결정할 필요 없이 명세만 보고 구현할 수 있을 때, 비로소 준비된 것입니다.

명세 검토 또한 AI 워크플로우 (Workflow)입니다

저는 모든 명세 문서를 일일이 한 줄씩 수동으로 읽고 싶지 않습니다.

그것은 인간의 주의력 (Attention)을 가장 잘 사용하는 방법이 아닙니다.

대신, 저는 AI에게 정밀한 질문을 던집니다. 이 흐름을 단계별로 설명해 줘. 위험한 가설들을 보여줘. 의존성 (Dependencies)을 시각화해 줘. 불분명한 인터페이스를 찾아줘. 더 단순한 패턴을 제안해 줘. 확장성 (Scaling) 및 성능 (Performance) 문제를 찾아줘. 수락 기준 (Acceptance criteria)이 실제로 동작을 증명하는지 확인해 줘.

기본적으로, 저는 수동 검토 (Manual review) 중에 던졌을 법한 질문들을 AI에게 던지는 것입니다.