스펙킷이란 무엇이고 어떻게 쓰는가

해당 문서는 스펙킷을 쓰면서 정리했던 내용을 옮긴 글입니다..
코덱스 CLI 기준으로 작업했고, 다른 AI를 붙여도 흐름은 크게 다르지 않겠지만 여기서는 그 부분까지 넓히진 않습니다.

스펙킷이 뭔가요?

Spec Kit은 사양 기반 개발을 위한 오픈 소스 툴킷입니다.
뭔가를 만들 때 그냥 바로 달려들어서 코드부터 치는 게 아니라, 먼저 짧은 사양서로 의도를 적고, 애매한 걸 정리하고, 구현 방법을 계획하고, 작업 단위로 쪼갠 다음, 그 가이드라인 안에서 에이전트가 구현하도록 돕는 흐름에 가깝습니다.

사양 중심 개발은 구현보다 의도를 먼저 둡니다.
무엇을 왜 해야 하는지는 사양서에 적고, 어떻게 만들지는 별도 계획에 둡니다.
그래서 사양서는 사람과 에이전트가 같이 보는 기준점이 되고, 뭔가 어긋났을 때도 코드를 바로 뜯기보다 사양부터 다시 보는 쪽이 더 맞습니다.

왜 쓰나요?

개발을 하다 보면 문서를 안 남기게 되는 상황이 거의 무적권 생깁니다.
개발하는 것만으로도 시간이 부족하고, 요구사항은 끝까지 바뀌고, 코드가 곧 문서 아니냐는 말도 계속 나오거든요. 별로 상관없습니다..

그래도 저는 매번 대화의 맥락을 까먹는 고지능 치매 머신을 상대한다고 생각하면, 이런 문서 흐름이 꽤 가치 있다고 봅니다.

• 왜 이렇게 구현했는지
• 어떤 제약을 보고 판단했는지
• 중간에 무엇이 바뀌었는지
• 이후 작업자가 어디서부터 손대야 하는지

이런 걸 빠르게 복구할 수 있다는 것만으로도 충분히 쓸 만합니다.
나중에 이거 누가 고친 거지?, 왜 이렇게 된 거지? 같은 질문에 답하기 훨씬 쉬워집니다.

어떤 상황에서 쓰나요?

주로 두 가지 상황에서 많이 얘기합니다.

그린필드

말 그대로 깡통에서 우주선 만드는 경우입니다.
기획 퀄리티가 낮을수록 결과물도 금방 흔들립니다. 잘못 들어가면 쓰레기로 완성되기 딱 좋습니다..

있는 프로젝트에서 기능 추가

이미 코드베이스와 컨벤션이 어느 정도 있는 상태에서 시작하는 경우입니다.
이쪽은 그린필드보다 훨씬 안정적입니다. 기존 파일과 패턴을 참조할 수 있어서, 적당한 요구사항만 있어도 그나마 결과가 잘 나오는 편입니다.

기능 추가만 놓고 보면 그냥 AI랑 대화하면서 구현하는 방식과 아주 극적인 차이가 나는 건 아닐 수도 있습니다.
근데 문서가 남습니다. 이후 작업자가 해당 기능이 어떤 식으로 개발됐고, 어디서 수정됐는지 따라가기 쉬워진다는 것만으로도 꽤 값어치가 있습니다.

스펙킷 플로우

기본 흐름은 5단계에 옵션 2단계를 더한 정도로 보면 됩니다.
스펙킷이 알잘딱 뭔가를 만들어주는 건 아닙니다. 입력한 내용을 템플릿 프롬프트에 넣어서 산출물을 계속 정리해 나가는 파이프라인에 더 가깝습니다.

그래서 입력이 부실하면 결과도 금방 무너집니다.
기가 막힌 청사진을 넣어도 페달 없는 자전거가 튀어나올 수 있습니다. 아래 내용은 코덱스 CLI 기준입니다.

/constitution

스펙킷 프롬프트를 날릴 때 항상 지켜야 하는 헌법을 만드는 단계입니다.
여기에 적어둔 내용은 계속 기준으로 작동하니까, 필수 규칙은 꼭 넣어야 됩니다.

예를 들면 이런 것들이다.

• 보안 규칙
• 컨벤션과 가이드라인
• 아키텍처
• 조직 정책이나 권한 구조
• 협업할 때 모두가 지켜야 하는 공통 원칙

잘 다듬을수록 고지능 치매 머신을 그나마 좀 더 잘 다독일 수 있습니다.

/specify

무엇을 만들지 보내는 단계입니다.
얼마나 자세히 써야 할지 몰라도 괜찮습니다. 어차피 산출물은 Markdown이라서, 결과를 보고 계속 고치면 되거든요.

그래도 이 단계에서 디테일을 꽤 넣어두면 좋습니다.
이미 정리해 둔 Markdown 문서가 있다면 참고하게 붙여도 되고, 개인적으로는 기능을 Jira와 연계해서 쓰는 흐름이 제일 괜찮다고 생각합니다.

예를 들면:

1. Jira에 일감을 만든다.
2. 일감에 요구사항과 기능 정의를 적는다.
3. 그 내용을 스펙킷에 던진다.

스펙을 던지고 나면 그 기준으로 브랜치와 폴더 구조가 잡힙니다.

/clarify

이 단계는 옵션입니다. 안 해도 되지만, 이전 단계 산출물을 한 번 더 검토해 보기에 좋습니다.

• 틀린 내용 수정
• 애매한 표현 정리
• 생각 못 한 예외 케이스 보강
• 부족한 정책 추가

산출물을 읽어보면서 직접 수정하거나, 대화로 고치면 됩니다.

/plan

어떻게 구현할지 정리하는 단계입니다.
이미 쓰고 있는 기술 스택, 써야 할 라이브러리, 재사용할 모듈, 관련 경계 같은 걸 여기서 구체화합니다.

결국 plan.md가 만들어지고, 마음에 들 때까지 수정과 검토를 계속 돌리면 됩니다.

/tasks

플랜을 바탕으로 실제 작업 단위를 만드는 단계입니다.
여기서 tasks.md가 나오고, 이것도 마찬가지로 마음에 들 때까지 다시 다듬는 편이 좋습니다.

산출물은 꼭 꼼꼼히 읽는 편이 좋습니다. 잘못 구현되는 경우는 대부분 산출물을 대충 읽고 넘어가면서 생깁니다.

/analyze

구현 전에 한 번 더 검증하는 단계입니다.
산출물이 많아질수록 제대로 검토하지 않을 확률이 높기 때문에, 여기서 충돌하는 정책이나 빠진 부분, 잘못된 가정들을 다시 점검해 줍니다.

구현 전에 한 번 더 걸러낼 수 있다는 점에서 꽤 유용합니다.

/implement

실제 구현 단계입니다.
tasks.md에 있는 내용을 구현하기 시작하는 시점인데, 시간도 오래 걸리고 토큰 소모도 커서, 간단한 작업은 사실 스펙킷을 쓰기 애매한 경우도 많습니다.

그래서 구현 범위를 잘게 나누는 편이 낫습니다.

• phase 1만 구현
• 검토
• 수정
• phase 2 구현
• 다시 검토

이런 식으로 순차적으로 가는 흐름이 보통 더 안정적입니다.
한 번에 너무 많은 페이즈를 몰아 구현시키면 응답 시간도 길어지고, 헌법이나 정책을 덜 지키는 경우도 꽤 생깁니다.

마무리

위 문서들은 스펙킷이 기본으로 잡고 가는 템플릿 흐름을 설명합니다.
입력에 따라 산출물이 달라지고, 영어 기본 템플릿을 그대로 써도 별로 상관없습니다.

저는 읽기 편하게 한국어로 바꾸고, 프로젝트에 맞춰 조금씩 손본 버전을 쓰고 있습니다.
결국 중요한 건 템플릿 자체보다, 구현 전에 의도와 제약을 문서로 남겨 놓는 습관 쪽에 더 가깝다고 생각합니다.