SDD (spec-kit) 에이전트 코딩 실전기 | 카카오페이 기술 블로그

요약: 에이전틱 코딩은 개발 생산성을 높여주지만 프로젝트가 고도화될수록 무분별한 코드 생성과 환각 문제가 발생하여 카카오페이 AI 플랫폼 팀에서는 스펙 기반 개발 방법론인 SDD(Spec-Driven Development)를 도입하게 되었습니다. SDD는 팀 단위 협업에서 일관성과 체계적인 개발을 가능하게 하며 앞으로 개발자의 역할이 ‘코드를 작성하는 사람’에서 ‘스펙을 검증하고 테스트를 설계하는 사람’으로 변화하는 흐름에 부합하는 방법론입니다.

💡 리뷰어 한줄평

will.109 최근 AI를 활용한 최신 개발 흐름에 정리해 주신 Spec-kit이라는 도구를 주목해 보는 것도 좋을 것 같습니다. 이미 관련 스킬이나 도구들이 많이 있지만 Spec-kit의 상호작용 방식과 산출물은 어떠한 도구를 사용하던 귀감이 되지 않을까 싶습니다.

geuru.geon 프로덕트를 만들 때, 이제는 코드를 작성하는 시간보다는 계획하는 시간이 더 필요하다는 것을 느끼는 요즘입니다. 웨인의 글은 Spec-kit과 피그마 MCP를 이용해 스펙을 정의하고, 컨텍스트가 발산되지 않게 규칙을 정하여 개발하는 과정이 담겨 있습니다. AI가 올바른 방향으로 코드를 짜낼 수 있게 하는 과정을 살펴보시죠!

0. 시작하며

본 자료에는 생성형 AI를 일부 사용한 콘텐츠가 포함되어 있습니다.

안녕하세요, AI 플랫폼팀 wayne입니다.
혹시 AI 에이전트가 생성한 코드가 이상한 작업을 하여 오히려 직접 코딩할 때보다 더 복잡한 상황을 겪어보신 적이 있으신가요?

에이전틱 코딩은 개발을 엄청 효율화시켜주지만 제어되지 않은 에이전틱 코딩을 프로젝트가 고도화될수록 무분별한 코드 생성과 환각이라는 숙제를 안겨줍니다. 카카오페이 AI 플랫폼 팀 또한 이러한 어려움 속에서 개발자가 팀단위로 스펙과 일관성을 제어하는 SDD(Spec-Driven Development) 방법론을 고민하게 되었습니다. 이 글에서는 단순한 에이전틱 코딩을 넘어 스펙을 정의하고 단계적으로 업무를 수행하는 Spec-kit 실전 코딩기를 공유합니다.

1. AI Platform과 에이전틱 코딩

저희팀에서는 이번에 AI Model들을 배포하고 사용할 수 있는 AI Platform을 구축하였습니다. 이번에는 에이전틱 코딩을 적극 활용하여 개발기간을 크게 단축하였고 생산성을 향상할 수 있었습니다. 개발초기, 중기, 후기의 단계별 AI의 협업전략으로 최대한 환각을 제어하고 개발자는 구체적인 로직 사용을 강제하는 지휘자 역할을 수행하여 개발을 하였습니다. 하지만 엔터프라이즈 시스템에서 AI와 협업을 하면서 고려해야 할 사항들이 많았고 후반으로 갈수록 여기저기 막 생성되는 코드를 줄이기 위한 프롬프트와 노력이 필요했습니다. 결국 마지막 단계에서는 AI가 생성한 코드를 검토하고 수정하는 시간이 점점 더 길어졌습니다. 이러한 에이전틱 코딩의 어려움으로 인하여 거의 모든 AI 코딩 도구들이 다음 단계로 스펙을 정의하여 한 단계씩 업무를 수행하는 방식을 채택하고 있고 저희도 이번에 Spec-kit을 도입하여 이러한 어려움을 많이 해결하고자 하였습니다. 이에 Spec-kit 사용방법과 실제 작업 예제를 공유드립니다.

2. Spec-kit 방식

기존 에이전틱 코딩 방식은 개발자가 AI에게 프롬프트로 지시를 내리고 AI가 코드를 생성하는 방식이었습니다. Spec-kit은 이러한 방식을 개선하여 개발자가 Spec-kit에 스펙을 정의하면 Spec-kit이 자동으로 AI 프롬프트를 생성하고 AI가 코드를 생성하는 방식입니다. 이를 통해 개발자는 스펙 정의에 집중할 수 있고 AI가 생성한 코드를 검토하고 수정하는 역할을 수행합니다. Spec-kit은 다음과 같은 주요 기능을 제공합니다:

constitution 시스템의 최상위 규칙을 정의합니다.
specify 이번에 개발할 구체적인 스펙을 정의합니다.
plan Spec-kit은 정의된 constitution과 스펙을 바탕으로 계발 계획을 생성합니다.
tasks 스펙과 계획을 바탕으로 구체적인 개발 작업을 생성합니다.
implement tasks에 맞춰서 개발작업을 합니다.

constitution → specify ↔ clarify → plan → tasks → analyze → implement

※ 각 단계에서 마음에 안 드는 부분이 있다면 직접 수정하지 않고 specify 로 돌아가 스펙을 재정의하는 것이 좋습니다.

3. Spec-kit 설정

Specify CLI 설치

uv가 미리 설치되어 있어야 합니다. uv 설치 가이드

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

설치 후 다음과 같이 사용할 수 있습니다:

# 새 프로젝트 생성 (디렉토리도 함께 만들어 줍니다)
specify init <PROJECT_NAME>

# 기존 프로젝트에서 초기화 (기존 프로젝트 위치에서 실행합니다)
specify init --here

보통 기존 프로젝트에서 설정을 많이 하게 되는데 이때는 specify init --here 명령어를 사용합니다.

초기화를 하면 원하는 에이전트를 선택할 수 있습니다.

초기화 설정이 완료된 모습입니다.

정상적으로 초기화가 되었다면 다음과 같은 메뉴를 볼 수 있습니다.

4. Constitution

개발하기 전에 대원칙 즉, 헌법을 정의하는 단계입니다. AI가 코드를 생성할 때 반드시 따라야 할 규칙을 정의합니다. 예를 들어, 코드 스타일, 테스트 커버리지, 문서화 요구사항 등을 포함할 수 있습니다.

이때 너무 프롬프트를 잘 쓸 필요는 없습니다. 다만 필요한 요소를 다 적는 것이 중요합니다. 정리는 에이전트에서 해줍니다.

저 같은 경우에는 아래와 같이 적었습니다 현재 프로젝트의 구조를 읽고 원칙을 세워달라고 주문하였습니다.

실행하게 되면 다음과 같은 constitution.md 파일이 생성됩니다. 이 파일은 spec, tasks, plan 등 다른 단계에서도 사용하는 대원칙이 됩니다.

이때 한글로 해달라고 마지막에 덧붙여야 알아보기 쉽게 됩니다.

5. Specify, Clarify

Specify

이제 개발할 상세 스펙을 정의해야 할 때입니다.

Specify 단계에서는 개발할 기능의 구체적인 요구사항을 작성합니다. 예를 들어 API 엔드포인트, 데이터 모델, 비즈니스 로직 등을 포함할 수 있습니다.

/speckit.specify 명령어를 사용하여 스펙을 정의하면 되는데 너무 깔끔하게 적으려고 하지 말고 필요한 요구사항을 최대한 많이 적는 것이 중요합니다.

이때 피그마mcp 혹은 스펙이 적혀있는 위키mcp 같은 mcp도 함께 호출 가능한데 클립모양의 아이콘을 눌러서 mcp를 미리 정의해 두면 편리합니다.

저 같은 경우 다음의 예제처럼 정말 두서없이 요구사항을 많이 적는 식으로 적었습니다. 정리는 spec-kit이 해줍니다.

완성된 스펙 정의 문서의 일부분은 다음과 같습니다.

이 스펙문서들을 검토하고 필요한 부분을 수정하거나 보완합니다. 이 과정에서 AI가 놓친 요구사항이나 잘못 이해한 부분을 바로잡을 수 있습니다.

저 같은 경우에는 아래와 같이 피그마 디자인 링크가 빠져있어서 추가해 달라고 하였습니다.

다음은 추가된 스펙화면입니다.

Clarify

specify가 끝나면 선택지가 생기는데 clarify는 선택입니다. 필요에 따라 요구사항을 더 명확히 하고 싶을 때 사용합니다.

저 같은 경우에는 보통 한 두 번 정도 하는 편입니다. 이 clarify 명령이 좋은 점은 기획문서나 요구사항이 있을 때 우리가 찾지 못한 점들을 찾을 수 있어 개발자뿐만 아니라 기획자와 함께 보기에도 유용하다는 점입니다.

아래와 같이 별다른 말없이 한글로 진행해 달라고만 하고 실행하면 됩니다.

아래는 실행결과 화면입니다. 스펙분석 결과를 보여주고 명확하게 하기 위한 질문을 최대 5개까지 저희에게 제안해 줍니다.

문답이 끝나면 스펙문서가 업데이트되고 다음 단계로 넘어갈 수 있습니다.

6. Plan, Tasks, Analyze, Implement

Plan

이제 본격적으로 개발 계획을 세우고 작업을 수행할 차례입니다.

/speckit.plan 한글로 진행해

이런 프롬프트를 사용하여 개발 계획을 생성합니다. Spec-kit은 constitution과 spec을 바탕으로 개발 계획을 수립합니다.

이러한 계획 문서가 생성되고 tasks를 실행하라고 나옵니다.

여기서 data model 정의도 볼 수 있는데 마음에 안 들면 바로 직접 수정하는 것보다는 SDD 원칙에 따라 /speckit.specify로 다시 명확한 스펙을 정의하여 ai 가 수정하도록 하는 게 좋습니다.

만약 직접 수정하게 되면 스펙 문서와 실제코드/계획이 불일치하여 일관성 유지 원칙에 어긋나며 나중에 스펙문서를 보고 개발자들이 혼란스러워 할 수 있습니다.

Tasks

이제 /tasks 명령어를 사용하여 구체적인 개발 작업을 생성합니다.

/speckit.tasks 한글로 작성해

이 명령어를 사용하면 Spec-kit은 constitution, spec, plan을 바탕으로 구체적인 개발 작업을 생성합니다.

작업이 완료되면 tasks.md 파일이 생성됩니다. 이 파일에는 각 작업의 세부사항과 완료 기준이 포함되어 있습니다. 이 작업도 체크해 보고 마음에 안 드는 작업이 있다면 직접 수정하지 않고 /speckit.specify로 다시 명확한 스펙을 정의하여 ai가 수정하도록 하는 게 좋습니다.

하지만 실무를 진행하다 보면 specify 수정만으로는 안될 때가 있습니다. 예를 들어 mcp 주소를 tasks에 넣길 원했지만 안 넣어줄 때가 있습니다.

지금 진행하고 있는 예제에서도 spec에는 피그마 mcp가 정의되어 있지만 tasks에는 피그마 작업이 누락되어 있었습니다. 이럴 때는 직접 tasks.md 파일을 참조하여 mcp 주소를 넣어달라고 프롬프팅해야 합니다 (이때 작성된 스펙과 일치하는지 반드시 확인해야 합니다.)

/speckit.tasks tasks에 피그마 mcp를 직접 사용하는 작업을 추가해줘

아래와 같이 피그마 작업이 추가된 모습을 볼 수 있습니다.

Analyze

다음으로 implements를 이용하여 바로 작업을 시작할 수도 있지만 저는 먼저 analyze로 작업을 분석하는 단계를 거칩니다.

/speckit.analyze 한글로 작성해

이 작업을 하게 되면 constitution 기준으로 spec, plan, task들이 잘 작성이 되었는지 서로 모순은 없는지 분석해 줍니다.

분석이 완료되면 결과를 보여주고 수정사항을 제안합니다. 이걸 수용할지 그냥 그대로 개발할지 선택하면 됩니다.

저는 분석 내용을 수정하는 편입니다. 수정을 해달라고 하면 모순되는 부분을 변경하고 task도 변경할 것이 있으면 변경해 줍니다. 수정을 마치고 이제 드디어 implement 단계로 넘어갑니다.

Implement

/speckit.implement 한글로 진행해

명령어를 통해 작업을 시작합니다. Spec-kit은 constitution, spec, plan, tasks를 바탕으로 개발을 수행합니다.

여기서 느낀 점은 AI가 코드를 생성할 때 tasks에 중점을 두는 것처럼 느꼈습니다. 그래서 constitution에 있는 말을 가끔 안 들을 때도 있습니다. 이럴 땐 constitution에 기반하여 tasks가 잘 생성되었는지 다시 체크를 해보아야 합니다.

아래와 같이 implement 작업이 진행됩니다. 이제 기다림의 시간입니다.

작업이 진행되면 tasks.md 파일이 업데이트되고 task 별로 완료된 작업이 표시됩니다.

위의 tasks 단계에서 mcp도 함께 정의했으므로 mcp 호출까지 하는 모습을 볼 수 있습니다.

SDD를 진행하며 느낀 점

이렇게 간단한 예제를 통해서 SDD 방법론을 이용한 Spec-kit을 사용하여 에이전틱 코딩을 수행하는 방법을 알아보았습니다.

SDD는 개발자가 스펙 정의에 집중할 수 있도록 도와주고 AI가 생성한 코드를 검토하고 수정하는 역할을 수행합니다. 이를 통해 개발 생산성을 향상할 수 있고 엔터프라이즈 환경에서 무엇보다 중요한 일관성을 유지할 수 있습니다.

물론 Spec-kit으로 모든 것을 해결할 수는 없습니다. 직접 개발하면서 느낀 단점으로는

constitution, spec, plan, tasks, implement 단계가 많아서 처음 접하는 개발자에게는 다소 복잡하게 느껴질 수 있습니다.
간단한 개발은 어떻게 해야 할지 애매합니다. specify 단계를 수정해야 할지 그냥 간단하게 agent 모드로 수정을 해야할지 판단이 개발자마다 다를 수 있습니다.
일단 파이프라인을 거치면 개발문서가 굉장히 많이 만들어 집니다 이에 따른 토큰도 많이 소모합니다. (물론 문서 같은 경우 반대로 이건 장점이 될 수도 있습니다)

단계별 복잡함은 분명 허들이 있습니다. 하지만 팀 단위 프로젝트에서 가장 중요한 ‘일관성’과 ‘체계적인 협업’에서 가치가 크다고 느꼈습니다. 제가 느낀 장점은 다음과 같습니다.

개발자가 스펙 정의에 집중할 수 있고 기획자와 함께 세심하게 검토 가능합니다.
협업환경에서 다른 개발자가 어떤 작업을 했는지 스펙문서를 통해서 명확하게 알 수 있습니다.
tasks 단계에서 구체적인 작업지시가 내려오므로 AI가 코드를 생성할 때 일관성이 높아집니다. 이전의 바이브코딩에서는 프롬프트만으로 지시하다 보니 AI가 맥락을 잃어버리기 쉽고 대화가 길어질수록 이전에 어떤 패턴으로 코드를 작성했는지 기억하지 못해 여기저기 다른 스타일의 코드가 생성되는 문제가 있었습니다.
보안이나 테스팅 같은 일관성이 중요한 요소들을 constitution 에 명확히 정의하고 tasks에 작업을 넣는지 안넣었는지 바로 알 수 있고 추가할 수 있습니다.

제가 정말 좋다고 느낀 점은 회사에서 팀단위로 일을 할 때 예전보다 더 체계적으로 개발을 할 수 있게 되었다는 점입니다. 앞으로 AI가 코드를 대신 작성해 주는 시대가 본격화되면 개발자의 역할은 ‘코드를 작성하는 사람’에서 ‘스펙을 검증하고 테스트를 설계하는 사람’으로 점점 변화할 것이라고 생각합니다. SDD를 통해 팀 생산성이 향상되길 기대하며 비슷한 고민을 하고 계신 분들께 이 글이 도움이 되었으면 합니다.