Claude Code를 위한 Spec Kit 명세 주도 개발 가이드

Claude Code를 잘 쓰는 팀과 그렇지 않은 팀의 차이는 프롬프트 실력보다 프로세스에 있습니다. GitHub Spec Kit 기반의 명세 주도 개발은 바로 그 차이를 만드는 운영 방식이에요.

이 가이드의 목적은 단순합니다. AI에게 코드를 한 번에 맡기는 대신, 명세 → 기술계획 → 작업분해 → 구현 → 검증의 흐름을 강제해 결과물의 예측 가능성과 재현성을 높이는 것. GitHub도 이 방식을 통해 명세가 구현, 체크리스트, 작업 분해의 중심이 되도록 설계했다고 설명합니다.

먼저 핵심만 짚으면 이렇습니다.

• Spec Kit의 핵심은 AI를 더 똑똑하게 만드는 일이 아니라, AI가 추측할 여지를 줄이는 일입니다.
• 좋은 구현은 좋은 프롬프트보다 좋은 명세에서 나옵니다.
• Claude Code는 강력하지만, spec, plan, tasks 없이 쓰면 과설계와 누락이 함께 커지기 쉽습니다.

왜 Claude Code에 명세 주도 개발이 필요한가

일반적인 프롬프트 기반 개발은 빠른 프로토타이핑에는 유리합니다. 문제는 요구사항이 많아지는 순간부터 시작돼요. 예를 들어 “사진 공유 기능을 추가해줘” 같은 요청은 얼핏 충분해 보이지만, 실제로는 수많은 숨은 요구사항을 품고 있습니다.

권한은 어떻게 나뉘는지, 업로드 제한은 있는지, 삭제 정책은 무엇인지, 모바일에서도 같은 UX를 보장해야 하는지 같은 조건이 빠져 있으면 AI는 그 빈칸을 추측으로 채웁니다. 그 결과는 대개 겉보기엔 그럴듯하지만, 실제 요구와는 미묘하게 빗나간 구현입니다.

GitHub가 Spec Kit으로 풀려는 문제도 정확히 여기에 있습니다. 무엇을 만들지 spec으로 정리하고, 어떻게 만들지 plan으로 분리하고, 어떤 순서로 만들지 tasks로 쪼개면 AI가 임의 가정을 덧붙일 공간이 줄어듭니다.

요약하면, 명세 주도 개발은 Claude Code의 성능을 끌어올리는 기법이 아니라 Claude Code의 추측 비용을 줄이는 운영 체계입니다.

Spec Kit의 핵심 개념은 여섯 단계로 이해하면 쉽다

Constitution: 먼저 프로젝트의 원칙을 고정한다

가장 먼저 만드는 것은 기능 명세가 아니라 원칙 문서입니다. Spec Kit은 /speckit.constitution 명령으로 코드 품질, 테스트 기준, UX 일관성, 성능 요구사항 같은 프로젝트의 헌법을 정의하도록 권장합니다.

이 결과는 .specify/memory/constitution.md에 저장되고, 이후 spec, plan, implement 전 과정의 기준점이 됩니다. 이 문서가 약하면 뒤 단계가 모두 흔들립니다.

실무에서는 아래처럼 적는 것이 좋습니다.

Specify: 무엇을 왜 만드는지 명세한다

/speckit.specify는 기능 명세를 만드는 단계입니다. 여기서 중요한 것은 기술 스택보다 의도입니다. GitHub도 이 단계에서는 가능한 한 구체적으로 요구사항과 사용자 시나리오를 쓰되, 아직 기술 선택으로 너무 빨리 들어가지 말라고 안내합니다.

즉, 이 단계의 질문은 “무슨 프레임워크를 쓸까”가 아니라 “누가 어떤 상황에서 무엇을 해야 하는가”입니다.

예시는 이렇게 잡을 수 있습니다.

Clarify: 초안 명세의 빈칸을 질문으로 메운다

초안 명세는 거의 항상 비어 있는 구석이 있습니다. 그래서 /speckit.clarify 단계가 중요합니다. README도 plan 전에 clarify를 수행할 것을 권장하고, 그 답변은 명세의 Clarifications 섹션에 누적됩니다.

이 단계의 목적은 구현을 빨리 시작하는 것이 아니라, 잘못된 전제로 빠르게 달리지 않게 만드는 것입니다.

예를 들면 이렇게 질문을 뽑을 수 있습니다.

Plan: 기술 계획을 문서로 만든다

/speckit.plan은 구현 계획 단계입니다. 여기서부터 데이터 모델, 계약 문서, 리서치 문서, 빠른 실행 가이드 같은 산출물이 생성될 수 있습니다.

예시 디렉터리에는 plan.md, data-model.md, research.md, quickstart.md, contracts/ 등이 포함됩니다. 이제부터는 “무엇을 만들까”보다 “어떤 제약과 구조로 만들까”가 중요해집니다.

Tasks: 구현 가능한 단위로 쪼갠다

/speckit.tasks는 AI가 실제로 움직일 수 있는 작업 단위를 만드는 단계입니다. README에 따르면 생성된 tasks.md에는 사용자 스토리별 작업 구분, 의존성 순서, 병렬 처리 표식 [P], 구현 파일 경로, TDD 순서, 각 단계의 검증 체크포인트가 포함됩니다.

이 단계의 핵심은 AI가 “한 번에 크게” 구현하지 못하게 만드는 데 있습니다. 대신 작고, 검증 가능하고, 리뷰 가능한 단위로 움직이게 해야 합니다.

Analyze / Checklist / Implement: 구현 전후의 품질 게이트를 세운다

현재 Spec Kit은 선택 명령으로 /speckit.analyze와 /speckit.checklist도 제공합니다. analyze는 산출물 간 일관성과 커버리지를 점검하고, checklist는 요구사항 완성도, 명확성, 일관성을 검증하는 맞춤 체크리스트를 만듭니다.

마지막 /speckit.implement는 constitution, spec, plan, tasks를 모두 확인한 뒤 작업 순서와 의존성에 맞게 구현을 수행합니다.

Spec Kit README에 따르면 implement 단계는 prerequisite를 검증하고, tasks.md를 읽고, 의존성과 병렬 표시에 따라 작업을 수행합니다. TDD 구조가 있다면 그 순서를 따르며, npm, dotnet 같은 로컬 CLI 도구를 실제로 호출할 수 있으므로 개발 환경 준비가 선행돼야 합니다.

Claude Code와 결합할 때는 초기 설정부터 확인해야 한다

GitHub README 기준으로 프로젝트 초기화는 specify init으로 시작합니다. Claude Code 대상으로는 아래 두 형태가 대표적입니다.

설치 없이 바로 쓰고 싶다면 uvx --from git+https://github.com/github/spec-kit.git specify init ... 방식을 사용하면 됩니다.

현재 README는 Claude, Gemini, Copilot 외에도 여러 에이전트를 지원한다고 안내합니다. 다만 Claude Code 환경에서는 /speckit.constitution, /speckit.specify, /speckit.plan, /speckit.tasks, /speckit.implement 명령이 보이면 설정이 완료된 것으로 보면 됩니다.

초기화가 끝나면 feature 브랜치와 명세 디렉터리가 생성됩니다. README 예시에서는 001-create-taskify 같은 브랜치와 폴더 구조가 사용되며, .specify/ 아래에는 scripts, templates, memory, specs가 만들어지고, feature 디렉터리 안에 spec.md가 먼저 생성됩니다.

실무에서는 이 순서대로 운영하는 편이 안전하다

1단계: 프로젝트 원칙을 먼저 고정한다

Claude Code에 품질, 성능, 테스트, 보안 기준을 먼저 박아 넣어야 합니다. 이 단계가 흐리면 이후 plan과 implement가 쉽게 흔들립니다.

좋은 헌법 문서는 팀의 취향이 아니라 팀의 비가역 원칙을 담습니다. 예를 들어 테스트 우선, API 계약 우선, 작은 단위 PR, 성능 예산 명시 같은 항목은 이후 AI의 선택을 안정화합니다.

2단계: 기능 명세는 기술이 아니라 의도로 쓴다

이 단계에서는 “무엇을 만들고 싶은가”와 “왜 필요한가”를 적어야 합니다. 특히 사용자 역할, 핵심 흐름, 지원 환경, 권한 차이 같은 내용이 빠지면 이후 계획 문서가 정교해 보여도 실제 요구에서 멀어질 수 있습니다.

3단계: 명세가 나온 직후 반드시 보정한다

명세를 만든 직후 구현으로 넘어가면 가장 위험합니다. 누락된 정책이 아직 살아 있기 때문이에요. clarify를 돌려 권한 규칙, 예외 흐름, 데이터 보존 정책, 삭제 정책, 감사 로그 요구사항 같은 항목을 질문으로 드러내야 합니다.

4단계: 기술 계획은 제약과 운영 기준까지 포함한다

이제 스택, 제약, 운영 환경을 Claude Code에 전달합니다. 여기서 중요한 것은 최신 기술을 나열하는 일이 아니라, 어떤 트레이드오프를 우선할지 분명히 하는 것입니다. 예를 들어 대량 트래픽보다 운영 단순성을 우선한다는 한 줄은 설계 방향을 크게 바꿉니다.

5단계: 작업은 독립 검증 가능한 크기로 나눈다

작업 단위가 크면 AI는 다시 큰 덩어리로 구현하려고 합니다. 그래서 파일 경로, 테스트 순서, 의존성 순서가 드러나는 수준까지 쪼개야 합니다. 병렬 처리 가능한 작업은 [P]로 표시해 팀과 에이전트 모두가 같은 순서를 보게 만드는 것이 좋습니다.

6단계: 구현 전 마지막 품질 게이트를 둔다

analyze와 checklist는 선택 명령이지만, 실무에서는 거의 필수에 가깝습니다. 명세, 계획, 작업 간 누락이나 충돌이 있는지 구현 전에 확인해두면 Claude Code가 잘못된 전제를 바탕으로 빠르게 달리는 상황을 줄일 수 있습니다.

7단계: 구현은 문서를 읽고 움직이게 한다

마지막 구현 단계에서는 AI가 임기응변으로 판단하지 않게 해야 합니다. constitution, spec, plan, tasks를 모두 전제로 실행되도록 만들면, 구현 순서와 검증 기준이 문서에 의해 통제됩니다.

실무에서 특히 중요한 운영 원칙 세 가지

명세는 보관용 문서가 아니라 실행 계약이어야 한다

Spec Kit의 핵심은 spec를 예쁘게 쓰는 데 있지 않습니다. 명세는 이후 plan과 tasks를 낳고, 그 산출물이 다시 implement를 지배해야 합니다.

즉, 명세는 설명문이 아니라 계약문이어야 합니다. 누가, 언제, 어떤 조건에서, 무엇을 할 수 있는지가 분명해야 합니다.

Claude Code의 과설계를 계속 경계해야 한다

GitHub README는 Claude Code가 지나치게 eager하게, 사용자가 요구하지 않은 컴포넌트를 추가할 수 있다고 경고합니다. 그래서 plan 단계에서는 “왜 이 구성요소가 필요한지”, “출처가 무엇인지”, “정말 요구사항에 포함되는지”를 되묻는 절차가 필요합니다.

이 원칙은 단순하지만 효과가 큽니다. AI의 성실함이 곧 정확함은 아니기 때문입니다.

조사는 넓게 말하지 말고 문제 단위로 좁혀야 한다

README는 빠르게 변하는 스택의 경우 research.md를 보강하도록 권장합니다. 하지만 막연하게 “이 프레임워크를 조사해”라고 지시하면 엉뚱한 방향으로 시간을 쓰기 쉽습니다.

대신 “이 버전에서 인증 미들웨어 호환성은 어떤가”, “이 배포 방식의 제한점은 무엇인가”처럼 문제 단위로 쪼개서 리서치를 시켜야 합니다. 리서치도 명세처럼 좁고 구체적일수록 품질이 올라갑니다.

권장 산출물 구조는 이 정도로 정리하면 충분하다

실무에서는 아래 구조를 기준으로 관리하면 안정적입니다.

이 구조는 공식 README 예시의 디렉터리 구성을 바탕으로 정리한 것입니다. plan 이후에는 contracts/, data-model.md, research.md, quickstart.md 등이 포함될 수 있고, tasks 단계 이후 tasks.md가 추가됩니다.

중요한 것은 파일 개수보다 흐름입니다. 문서가 많아지는 것이 목적이 아니라, 구현이 문서를 따라가게 만드는 것이 목적입니다.

이런 팀이라면 특히 잘 맞는다

Spec Kit 기반 명세 주도 개발은 아래 상황에서 특히 강합니다.

• 요구사항이 자주 바뀌지만, 변경 이력을 명세 중심으로 잡아야 할 때
• AI에게 큰 기능을 맡기되, 과설계와 누락을 줄이고 싶을 때
• 프론트엔드, 백엔드, 인프라가 얽혀 있어 작업 순서와 경계를 명확히 해야 할 때
• 한 번에 거대한 코드 덤프를 받기보다 작은 검증 단위로 리뷰하고 싶을 때

GitHub 블로그도 이 접근이 모호한 프롬프트보다 강한 이유를, AI가 마음을 읽는 것이 아니라 명세를 바탕으로 더 정확히 실행할 수 있기 때문이라고 설명합니다.

한계와 주의점도 분명하다

Spec Kit이 있다고 해서 요구사항 정리가 자동으로 좋아지는 것은 아닙니다. 명세 품질이 낮으면 이후 산출물도 그대로 흔들립니다.

또 Claude Code는 잘못된 전제를 바탕으로도 매우 그럴듯한 plan을 만들 수 있습니다. 스택이 빠르게 변하는 영역에서는 research.md 검증 없이 계획 문서를 신뢰하면 위험합니다.

구현 후에도 끝난 것이 아닙니다. 브라우저 콘솔 에러, 런타임 문제, 실제 UX 결함은 별도 확인이 필요합니다. README 역시 CLI 로그에 보이지 않는 런타임 오류를 별도 테스트로 잡으라고 안내합니다.

정의형으로 정리하면 이렇습니다. Spec Kit은 구현 품질을 자동 보장하는 도구가 아니라, 구현 품질을 검증 가능한 절차 안에 넣는 도구입니다.

결론: 잘 코딩하는 AI보다 먼저 잘 통제되는 프로세스를 만들어야 한다

Claude Code를 제대로 활용하려면 “잘 코딩하는 AI”보다 먼저 “잘 조종되는 개발 프로세스”를 만들어야 합니다. Spec Kit은 바로 그 프로세스를 제공합니다.

실무적으로는 이 한 줄이면 충분합니다.

좋은 결과를 원하면, 구현을 자세히 시키기 전에 명세를 먼저 통제하라.

Claude Code를 더 잘 쓰는 방법을 찾고 있다면, 프롬프트를 더 길게 쓰는 것보다 constitution, spec, clarify, plan, tasks, analyze, checklist, implement의 순서를 팀의 기본 운영 체계로 만드는 편이 훨씬 효과적입니다.