스펙 기반 개발
AI 코딩 에이전트에 프롬프트를 보내기 전에 스펙부터 쓰세요
GitHub의 Spec Kit는 GitHub가 직접 운영하는 오픈소스 프로젝트입니다. 이 가이드는 독립적으로 작성되었으며 GitHub와 제휴하거나 GitHub의 보증을 받은 것이 아닙니다.
AI 코딩 에이전트를 쓰며 겪는 답답함의 대부분은 같은 원인에서 나옵니다. 모호하게 요청하면 모호한 결과가 나오고, 내가 정말 원했던 것이 무엇인지는 기대와 다른 코드를 읽고 나서야 알게 됩니다. 스펙은 이 순서를 바로잡아 줍니다. 프롬프트를 한 번 보내기 전에, 쉬운 말로 짧게 세 가지를 적습니다. 무엇을 하는 것인지, 누구를 위한 것인지, 그리고 끝났는지를 가려 줄 구체적인 확인 조건입니다. 코딩을 몰라도 할 수 있습니다. GitHub의 Spec Kit는 GitHub 자체 저장소에서 관리되는 오픈소스 툴킷으로, 바로 이 습관을 중심으로 코딩 에이전트를 위한 구조적이고 반복 가능한 과정을 만들어 둡니다. 전용 명령줄 도구가 있고, 프로젝트의 기본 원칙에서 실제 빌드까지 이어지는 이름 붙은 단계들이 있습니다. 이 가이드는 5분이면 직접 쓸 수 있는 세 부분짜리 스펙, Spec Kit의 워크플로가 같은 아이디어를 어떻게 별도의 명령으로 나누는지, 그리고 전체 툴킷을 설치할 가치가 있는 때와 스펙만 직접 쓰면 충분한 때를 다룹니다.
스펙은 코딩 에이전트에 무언가를 만들어 달라고 요청하기 전에 쓰는 짧고 쉬운 말의 브리프입니다. 무엇을 하는지, 누구를 위한 것인지, 그리고 끝났음을 증명하는 완료 조건으로 이루어집니다. GitHub 자체 저장소에서 만들어지는 오픈소스 툴킷 GitHub Spec Kit는 이 습관을 반복 가능한 워크플로로 바꿔 줍니다. 원칙 설정, 스펙 작성, 계획, 작업 분해, 구현, 수렴 확인을 위한 전용 명령이 있고, 문서에는 Anthropic의 Claude Code와 GitHub Copilot을 포함해 연결되는 에이전트가 명시되어 있습니다. 이 툴킷이 없어도 효과는 얻을 수 있습니다. 같은 세 부분짜리 브리프를 첫 메시지로 입력하면 이미 쓰고 있는 어떤 코딩 에이전트에서도 통합니다.
게시일
무료 레슨 · 계정 필요 없음Claude 만나기왜 Claude인가?6분무료 레슨 시작하기핵심 요약
- 스펙은 첫 프롬프트 전에 적는 세 가지입니다. 에이전트가 무엇을 만들어야 하는지, 누구를 위한 것인지, 끝났음을 증명하는 완료 조건입니다.
- GitHub의 Spec Kit는 자체 저장소 기준으로 MIT 라이선스의 무료 오픈소스 툴킷이며, 이 습관을 여섯 개의 명령으로 구성합니다. 원칙(constitution), 스펙, 계획, 작업 목록, 구현, 수렴 확인입니다.
- 스펙의 효과를 보려고 Spec Kit가 꼭 필요하지는 않습니다. 같은 세 부분짜리 브리프를 첫 메시지로 입력하면 Claude Code, OpenAI의 Codex, Copilot, Anysphere의 Cursor 등 어떤 코딩 에이전트에서도 통합니다.
- Spec Kit의 설치 문서에는 연결되는 코딩 에이전트가 통합 키(integration key)와 함께 나와 있으며, Claude Code와 GitHub Copilot이 포함되고 다른 에이전트를 추가하는 방법도 안내되어 있습니다.
- 완료 조건을 빼먹는 것이 스펙이 조용히 실패하는 가장 흔한 경로입니다. 완료 조건이 없으면 나도 에이전트도 작업이 정말 끝났는지 알 수 없습니다.
복사해서 붙여넣기
오늘 바로 쓸 수 있는 프롬프트
첫 대화를 시작할 때 쓰는 세 부분짜리 스펙
제가 만들고 싶은 것의 스펙입니다. 하는 일: 내 Downloads 폴더의 파일을 파일 형식별로 날짜가 붙은 하위 폴더에 정리하는 스크립트. 누구를 위한 것인지: 나 혼자, 터미널에서 직접 실행하며 다른 사용자는 없음. 완료 조건: 샘플 파일 20개가 든 테스트 폴더에서 실행하면 모든 파일이 올바른 하위 폴더로 분류되고, 그 폴더 밖의 것은 전혀 건드리지 않으며, 명령 하나로 실행 전체를 되돌릴 수 있어야 함. 만들기 시작하기 전에 필요한 것이 있으면 먼저 물어봐 주세요.
어떻게 만들지에 대한 대화를 시작하기 전에, 가장 첫 메시지로 붙여 넣으세요.
모호한 아이디어를 스펙으로 바꾸도록 에이전트에 요청하기
무언가를 만들고 싶은데 아이디어가 아직 모호합니다. 대략 이런 모습을 떠올리고 있어요: 여기에 대략적인 아이디어를 한두 문장으로 적어 주세요. 코드를 쓰기 전에, 이것이 무엇을 하는지, 누구를 위한 것인지, 끝났는지 우리 둘이 어떻게 알 수 있는지를 세 부분으로 짧게 정리해 말해 줄 수 있을 때까지 저에게 질문해 주세요. 세 부분을 제가 모두 확인하기 전에는 만들기 시작하지 마세요.
문제의 윤곽은 알지만 세부 사항은 아직 정하지 못했을 때 유용합니다.
빌드를 승인하기 전에 완료 조건 점검하기
구현을 시작하기 전에, 이 작업이 끝났음을 증명하기 위해 실행할 구체적인 확인 항목을 나열해 주세요. 무엇을 테스트하는지, 각 항목의 기대 결과는 무엇인지, 무엇이 실패로 간주되는지를 적어 주세요. 이 세션 안에서 직접 확인할 수 없는 것이 필요한 항목이 있다면, 나중에 잘 될 거라고 가정하지 말고 지금 알려 주세요.
좋은 에이전트라면 코드를 한 줄 쓰기 전에 이 질문에 자세히 답할 수 있어야 합니다.
핵심 습관
스펙이 프롬프트보다 먼저인 이유
코딩 에이전트에 요청을 바로 입력하는 편이 먼저 무언가를 적는 것보다 빨라 보이고, 정말 사소한 작업이라면 실제로 그렇습니다. 문제는 합리적인 해석이 둘 이상 가능한 작업에서 시작됩니다. 에이전트가 하나를 골라 그쪽으로 만들고, 잘못 골랐다는 사실은 완성된 코드를 읽고 나서야 드러납니다. 그때부터는 왕복할 때마다 스펙을 쓰는 데 들었을 몇 분보다 더 많은 비용이 듭니다.
스펙은 일의 순서를 바꿉니다. 코드를 쓰기 전에 쉬운 말로 세 가지를 적습니다. 무엇을 하는 것인지, 누구를 위한 것인지, 제대로 동작함을 증명하는 완료 조건입니다. 기술 문서가 아닙니다. 나를 처음 만나는 유능한 조수에게 남기는 메모에 가깝습니다. 중요한 부분에서 추측하지 않아도 될 만큼의 정보를 담으면 됩니다.
이것이 효과적인 이유는 단순합니다. 채워야 할 빈칸이 줄어드니 에이전트가 자기 가정으로 빈칸을 메우지 않게 됩니다. 그리고 요청하기 전에 이미 적어 두었으니, 결과물을 읽고 나서야 내가 원한 것을 알게 되는 일도 사라집니다.
이는 특정 도구에만 해당하는 이야기가 아닙니다. Claude Code, Codex, Copilot, Cursor 등 모든 코딩 에이전트는 기본적으로 같은 방식으로 일합니다. 쉬운 말로 지시를 넣으면 코드와 명령이 나옵니다. 스펙은 들어가는 내용을 바꾸고, 그래서 어떤 에이전트와 대화하든 돌아오는 결과가 달라집니다.
세 부분짜리 스펙
5분이면 쓸 수 있는 스펙에 담을 내용
쉬운 말로 쓰는 짧은 네 가지 항목입니다. 코딩을 몰라도 됩니다.
하는 일
구현 방식이 아니라 동작을 한두 문장으로 설명합니다. 어떤 함수나 라이브러리를 쓸지가 아니라 "파일을 형식별로 날짜 폴더에 정리한다" 정도면 됩니다.
누구를 위한 것인지
나 혼자 직접 실행하는 건가요? 프로젝트를 한 번도 본 적 없는 동료가 쓰나요? 이 답이 기능 설명보다 더 크게 실제로 만들어야 할 것을 바꾸는 경우가 많습니다.
완료 조건
빌드가 끝났음을 증명하는 구체적이고 테스트 가능한 조건입니다. 대부분의 사람이 건너뛰는 부분이고, 문제가 생겼을 때 가장 중요한 부분입니다.
가드레일
선택 사항이지만 위험 부담이 클 때는 추가할 만합니다. 한 폴더 밖의 파일을 건드리거나 무언가를 자동으로 보내는 일처럼 에이전트가 절대 해서는 안 되는 것을 적습니다.
이를 위한 오픈소스 구조
GitHub의 Spec Kit가 스펙을 워크플로로 바꾸는 방식
GitHub의 Spec Kit는 GitHub 자체 저장소에서 MIT 라이선스로 관리되는 오픈소스 툴킷으로, 일회성 대화 대신 구조화된 프로세스, 재사용 가능한 템플릿, 문서화된 결과물을 AI 코딩 에이전트에 제공하도록 만들어졌습니다. 전용 명령줄 도구로 설치하며, README에서는 스펙 기반 개발, 또는 에이전트가 따르게 하고 싶은 다른 구조적 프로세스를 시작하기 위한 툴킷이라고 설명합니다.
프로젝트 문서에 따르면 핵심 스펙 기반 워크플로는 이름 붙은 여섯 개의 명령으로 이어집니다. 하나는 프로젝트의 기본 원칙을 정하고, 하나는 스펙 자체를 쓰고, 하나는 그 스펙을 기술 계획으로 바꾸고, 하나는 계획을 순서가 있는 작업 목록으로 나누고, 하나는 작업을 수행해 실제 코드를 쓰고, 마지막 하나는 결과가 스펙에 얼마나 수렴했는지 확인합니다. 프로젝트의 안내는 이 명령들을 한 번에 하나씩 실행하며 각 결과를 검토한 뒤 다음으로 넘어가고, 수렴 확인이 작업이 수렴했다고 알릴 때까지 구현과 수렴 단계를 반복하라는 것입니다. 전체 작업을 에이전트에 한 번에 맡기지 말라는 뜻입니다.
이 툴킷에는 핵심 워크플로 위에 추가하는 별도의 확장도 있습니다. 역시 문서에 따르면, 하나는 특정 버그를 평가하고 고치는 데 맞춘 명령 모음이고, 다른 하나는 만들지 말지 결정하기 전에 거친 아이디어를 조사하고 구체화하는 데 맞춘 명령 모음입니다.
연결되는 에이전트에 대해서는, Spec Kit의 설치 문서가 설치 시점에 전달하는 통합 키와 함께 여러 에이전트를 명시하고 있으며 Claude Code와 GitHub Copilot이 포함됩니다. 문서에 직접 나와 있지 않은 다른 에이전트를 연결하는 방법은 별도의 문서로 안내합니다. 이 글의 목록을 포함해 특정 에이전트 목록은 어느 시점의 스냅샷으로 보시고, 어떤 도구가 지금 지원되는지 단정하기 전에 Spec Kit의 최신 문서를 확인하세요.
명령별 워크플로
Spec Kit의 여섯 가지 핵심 명령
프로젝트 README에 따르면 스펙 기반 워크플로는 이 여섯 단계를 순서대로 거치며, 마지막 두 단계는 결과가 수렴할 때까지 반복합니다.
원칙(Constitution) 설정
이후 모든 작업에서 에이전트가 지켜야 할 프로젝트 전체의 원칙을 기록하는 명령입니다. 한 번 써 두면 이후 작업에서 계속 재사용됩니다.
스펙 작성
실제 스펙 문서를 만드는 명령입니다. 위에서 다룬 쉬운 말의 브리프와 같은 것이며, 일회성 메시지가 아니라 재사용 가능한 파일로 남습니다.
접근 방식 계획
스펙을 기술 계획으로 바꾸는 명령입니다. 코드를 쓰기 전에 접근 방식을 정하므로, 설계상의 결정이 구현 속에 묻히지 않습니다.
작업으로 나누기
계획을 구체적이고 순서가 있는 작업 목록으로 쪼개는 명령입니다. 각 작업은 따로 확인할 수 있을 만큼 작습니다.
구현
작업 목록을 수행하며 코드를 쓰는 명령입니다. 처음부터 다시 시작하지 않고, 앞선 단계의 결과물을 모두 가이드로 삼습니다.
수렴 확인
결과가 스펙과 얼마나 일치하는지 확인하는 명령입니다. 프로젝트의 안내에 따라, 수렴 확인이 작업이 수렴했다고 알릴 때까지 구현과 수렴 확인을 함께 반복합니다.
아무것도 설치하지 않고
툴킷 없이 스펙을 직접 쓰기
작은 것 하나를 만드는 비개발자에게는 Spec Kit의 전체 워크플로가 작업에 비해 과한 절차일 수 있습니다. 세 부분짜리 스펙만 이미 쓰고 있는 에이전트에 첫 메시지로 입력해도 설치할 것 없이 실질적인 역할의 대부분을 해냅니다.
스펙을 붙여 넣은 뒤, 에이전트가 코드를 쓰기 전에 확인 질문을 하도록 두세요. 유능한 에이전트는 불분명한 부분이 있으면 질문합니다. 스펙이 있으면 에이전트가 조용히 추측해서 자신 있게 엉뚱한 것을 만드는 대신, 구체적으로 물어볼 거리가 생깁니다.
이 단순한 형태의 습관은 어디서든 통합니다. Claude Code, Codex, Copilot, Cursor, 그 밖의 어떤 코딩 에이전트와 대화하든 같은 세 부분짜리 브리프가 통합니다. 어느 한 도구의 기능에 기대지 않기 때문입니다. 설치하는 플러그인이 아니라 몸에 익히는 습관입니다.
어디서 잘못되는가
스펙을 무력화하는 실수들
다음 중 하나가 끼어들면 스펙의 도움이 기대보다 줄어듭니다.
완료 조건이 없음
완료를 확인할 방법이 없는 스펙은 추측을 프롬프트 단계에서 검토 단계로 옮겨 놓을 뿐이고, 검토 단계에서는 잡아내기가 더 어렵습니다.
구현 세부 사항 섞기
그 기능이 정말 필요한지 정하기도 전에 프로그래밍 언어나 특정 알고리즘을 지정하면, 스펙이 성급한 설계가 되어 버립니다.
사후에 쓰기
이미 존재하는 코드에 맞춰 쓴 스펙은 만들어진 것을 기록할 뿐입니다. 자신이 동의하도록 쓰인 문제는 잡아낼 수 없습니다.
스펙 하나에 작업 여러 개
실제 작업이 둘 이상인 스펙은 정말 중요한 하나를 묻어 버립니다. 스펙 하나는 확인 가능한 작업 하나로 유지하세요.
툴킷을 꺼내 들 때
단순한 스펙과 전체 Spec Kit 중 고르기
작은 빌드 하나라면 세 부분짜리 단순한 스펙을 대화창에 바로 입력하는 것으로 충분하고, 무언가를 설치하는 것보다 빠릅니다. 이 가이드의 예시 대부분도 바로 그런 경우를 위해 쓰였습니다.
같은 프로젝트에서 이 작업을 반복하게 될 때, 새 기능마다 프로젝트 원칙이 자동으로 적용되기를 원할 때, 또는 버그 수정이나 아이디어 평가를 매번 직접 구조를 짜는 대신 확장이 제공하는 구조로 하고 싶을 때부터 Spec Kit는 설치 비용만큼의 값을 하기 시작합니다.
어느 쪽이든 실제 기술은 같습니다. 코드를 한 줄 쓰기 전에 무엇을 하는지, 누구를 위한 것인지, 끝났음을 어떻게 알 수 있는지를 말로 정리하는 것입니다. 툴킷은 이를 일관되게 적어 주는 일을 자동화할 뿐이며, 그 습관을 자주 꺼내 쓰게 되어 자동화할 만해졌을 때 의미가 있습니다.
만들기 전에 스펙 쓰는 연습하기
명확한 스펙을 쓰고 AI 코딩 에이전트에 프로젝트의 상시 지침을 주는 일은 이 가이드의 모든 도구에 통하는 기술입니다. Nightschool AI의 프로젝트 지침 파일에 관한 무료 레슨에서 Claude Code를 예로 들어 바로 이 내용을 다룹니다.
자주 묻는 질문
여기서 말하는 스펙이란 정확히 무엇인가요?
코딩 에이전트에 무언가를 만들어 달라고 요청하기 전에 쓰는 짧고 쉬운 말의 브리프입니다. 최소한 무엇을 하는 것인지, 누구를 위한 것인지, 끝났음을 증명하는 완료 조건을 담습니다. 기술 문서가 아니며 코딩을 알 필요도 없습니다.
스펙을 쓰려면 코딩을 알아야 하나요?
아니요. 스펙은 구현이 아니라 동작과 결과를 쉬운 말로 설명합니다. 도구가 무엇을 해야 하고 제대로 동작하는지 어떻게 알 수 있는지를 설명하는 데는 프로그래밍 지식이 필요하지 않습니다. 실제 코드는 만드는 에이전트가 씁니다.
GitHub의 Spec Kit는 무엇인가요?
GitHub 자체 저장소에서 관리되는 MIT 라이선스의 오픈소스 툴킷입니다. 스펙 기반 개발을 중심으로 AI 코딩 에이전트에 구조적이고 반복 가능한 프로세스를 제공하며, 전용 명령줄 도구와 프로젝트의 기본 원칙에서 구현과 수렴 확인까지 이어지는 이름 붙은 여섯 개의 명령을 갖추고 있습니다.
Spec Kit는 어떤 코딩 에이전트와 함께 쓸 수 있나요?
자체 설치 문서에 따르면 설치 시점에 통합 키로 에이전트를 연결합니다. 문서에는 Claude Code와 GitHub Copilot을 포함해 여러 에이전트가 이런 방식으로 명시되어 있고, 다른 에이전트를 연결하는 방법은 별도 문서로 안내합니다. 특정 도구가 지원된다고 단정하기 전에 Spec Kit의 최신 문서에서 전체 목록을 확인하세요.
이 가이드는 GitHub와 관련이 있나요?
아니요. 이 가이드는 독립적으로 작성된 교육 자료이며 GitHub가 발행하거나 보증한 것이 아닙니다. Spec Kit와 GitHub는 GitHub의 프로젝트이자 상표이며, 정확한 설명을 위해서만 언급했습니다.
스펙과 그냥 긴 프롬프트는 무엇이 다른가요?
긴 프롬프트도 결국 작업을 설명하는 하나의 메시지입니다. 스펙은 하는 일, 누구를 위한 것인지, 완료 조건이라는 세 가지 구체적인 부분으로 이루어진 구조화된 브리프로, 한 번 입력하고 잊는 것이 아니라 읽고, 확인하고, 재사용하기 위한 것입니다.
"완료 조건"이란 구체적으로 무엇인가요?
빌드가 끝났음을 증명하는 테스트 가능한 조건입니다. 무엇을 확인할지, 각 확인의 기대 결과가 무엇인지, 무엇이 실패로 간주되는지를 적습니다. 이것이 없으면 에이전트가 작업을 정말 끝낸 건지 그냥 멈춘 건지 판단할 합의된 방법이 없습니다.
이 습관의 효과를 보려면 Spec Kit를 꼭 설치해야 하나요?
아니요. 같은 세 부분짜리 스펙을 Claude Code, Codex, Copilot, Cursor 등 어떤 코딩 에이전트에든 첫 메시지로 입력하면 설치 없이도 효과의 대부분을 얻습니다. Spec Kit는 이 일을 자주 할 때를 위한 반복 가능한 구조이지, 이 습관을 갖기 위한 필수 조건이 아닙니다.
Spec Kit는 무료로 쓸 수 있나요?
네. 자체 저장소에 따르면 MIT 라이선스로 공개된 오픈소스 프로젝트이며, 무료 명령줄 도구로 설치합니다.
Spec Kit의 스펙 작성 명령은 실제로 무엇을 만들어 내나요?
프로젝트 문서에 따르면 스펙 문서 자체를 만듭니다. 이 가이드 전반에서 설명한 쉬운 말의 브리프와 같은 것이며, 매번 대화창에 새로 입력하는 대신 프로젝트 안에 재사용 가능한 파일로 저장됩니다.