spec-kit으로 명세부터 쓰는 개발 흐름 만들기

구현은 빨랐는데 결과가 엉뚱한 이유

코딩 에이전트는 구현이 빠릅니다. 문제는 요구사항이 흐릿하면 틀린 방향으로도 아주 빠르게 간다는 거예요.

깃허브의 spec-kit은 순서를 바꿉니다. 먼저 “무엇을 만들지”를 문서로 확정하고, 그 문서에서 작업 목록과 구현을 차례로 내려보냅니다. 코드를 잘 쓰게 만드는 도구라기보다, 엉뚱한 코드를 쓰기 전에 방향부터 맞추는 도구에 가까워요.

크게 보기

명세는 오랫동안 코딩이 시작되면 버려지는 발판이었습니다. 결정을 파일로 남겨 다음 세션이 읽게 만든다는 점에서 DESIGN.md 워크플로와 같은 발상입니다. 명세 주도 개발은 그 순서를 뒤집습니다. 명세가 실행 가능해지고, 구현을 안내하는 게 아니라 직접 만들어냅니다.

1단계 — 설치

uv가 필요합니다. 아래는 2026년 9월 14일 확인한 릴리스 v1.0.6을 고정한 설치 명령입니다. 새 버전으로 바꿀 때는 해당 릴리스의 명령을 다시 확인하세요. 이 글에서는 에이전트의 전체 구현 단계를 실행했다고 주장하지 않습니다.

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

버전 관리는 자체 명령으로 합니다. specify self check 는 새 릴리스가 있는지만 확인하고 아무것도 바꾸지 않습니다. specify self upgrade --dry-run 은 무엇이 실행될지 보여줍니다. specify self upgrade 는 바로 올립니다.

크게 보기

2단계 — 프로젝트 초기화

specify init my-project --integration copilot
cd my-project

3단계 — 일곱 단계 워크플로

에이전트를 프로젝트 디렉토리에서 띄우고 슬래시 명령을 순서대로 씁니다.

명세에서 구현까지

핵심

1. 1. constitution 원칙
2. 2. specify 무엇을·왜
3. 3. plan 스택·아키텍처
4. 4. tasks 작업 목록
5. 5. implement 구현

선택

1. 2. clarify 덜 정해진 곳 되묻기
2. 4. analyze 산출물 정합성
3. 5. converge 남은 일 추가

specify 단계에서는 기술 스택을 쓰지 않는다. 요구사항과 구현 수단을 분리하는 것이 이 도구의 핵심이다.

순서	명령	하는 일
1	/speckit.constitution	프로젝트를 지배할 원칙과 개발 지침을 만든다
2	/speckit.specify	무엇을 만들지 정의한다. 요구사항과 사용자 스토리
3	/speckit.clarify (선택)	덜 정해진 부분을 되묻는다. plan 전에 권장
4	/speckit.plan	기술 스택과 아키텍처를 정한 구현 계획
5	/speckit.tasks	계획에서 실행 가능한 작업 목록 생성
6	/speckit.analyze (선택)	산출물 간 일관성과 커버리지 분석
7	/speckit.implement	계획대로 모든 작업 실행

2단계에서는 기술 스택을 쓰지 않습니다. 무엇을, 왜에 집중합니다.

/speckit.specify 공개 블로그에서 독자가 누르는 내부 링크를 검사한다.
사이트맵 밖 강의 링크도 포함하고, 오류 응답이나 다른 페이지로의 이동을 보고한다.
비공개 글의 주소는 결과에 노출하지 않는다.

기술 선택은 4단계로 미룹니다.

/speckit.plan Node.js의 fetch로 응답 코드와 최종 URL을 검사한다.
로컬 HTTP 서버에서 500 응답과 강의 목록으로의 리다이렉트를 재현한다.
검사 실패가 있으면 종료 코드 1을 반환한다.

이 분리가 이 도구의 핵심입니다. 요구사항과 구현 수단을 같은 문장에서 정하면 나중에 스택을 바꿀 때 요구사항까지 흔들립니다.

크게 보기

나머지 명령도 있습니다. /speckit.taskstoissues 는 작업 목록을 깃허브 이슈로 바꾸고, /speckit.converge 는 현재 코드베이스를 명세·계획·작업과 대조해 남은 일을 새 작업으로 덧붙입니다. /speckit.checklist 는 요구사항의 완결성과 명확성을 검사하는 체크리스트를 만듭니다. 저장소는 이걸 “영어로 쓴 단위 테스트”라고 부릅니다.

4단계 — 팀 표준으로 굳히기

세 층으로 커스터마이즈합니다. 템플릿은 실행 시점에 위에서부터 훑어 첫 매치를 씁니다.

우선순위	층	위치
1	프로젝트 로컬 오버라이드	.specify/templates/overrides/
2	프리셋 — 핵심과 확장을 덮어씀	.specify/presets/templates/
3	확장 — 새 기능 추가	.specify/extensions/templates/
4	spec-kit 코어	.specify/templates/

• 확장은 무엇을 할 수 있는지를 넓힙니다. Jira 연동, 구현 후 코드 리뷰, V-모델 테스트 추적성, 프로젝트 건강 진단 같은 것들입니다
• 프리셋은 어떻게 하는지를 바꿉니다. 규제 추적성을 요구하는 명세 양식, 계획에 필수 보안 검토 게이트, 테스트 우선 작업 순서, 워크플로 전체의 다른 언어 현지화
• 번들은 확장·프리셋·단계·워크플로를 묶어 역할 단위로 한 번에 설치합니다. bundle.yml 로 각 구성요소의 버전을 고정합니다

크게 보기

specify bundle search
specify bundle info <bundle-id>     # 설치될 구성요소를 미리 확인
specify bundle install <bundle-id>
specify bundle remove <bundle-id>   # 이 번들 것만 제거

프로덕트 매니저·비즈니스 분석가·보안 연구자·개발자처럼 역할별 세팅을 한 명령으로 프로비저닝하는 용도입니다.

흔한 실패

상황	원인	대응
명세가 두루뭉술해 계획이 흔들린다	clarify 를 건너뜀	/speckit.plan 전에 /speckit.clarify 를 넣는다
구현 결과가 계획과 어긋난다	산출물 간 정합성 미검사	tasks 뒤 implement 앞에 /speckit.analyze
커뮤니티 확장이 예상과 다르게 동작	독립적으로 만들어지고 관리됨	저장소가 직접 경고한다. 설치 전 소스 확인
명령이 겹쳐 어느 게 도는지 모르겠다	프리셋·확장이 같은 명령 제공	우선순위 높은 쪽이 이긴다. 제거하면 다음 순위가 자동 복원

spec-kit을 도입할 프로젝트

요구사항에 여러 사람이 관여하거나 기술 스택을 나중에 바꿀 수 있는 프로젝트라면 효과가 큽니다. 조직의 명세 양식을 모든 팀에 적용할 때도 쓸 만합니다.

크게 보기

요구사항이 한 문장으로 끝나는 수정이나 혼자 만드는 작은 스크립트에는 절차가 더 무거울 수 있습니다.

spec-kit은 요구사항의 복잡도로 도입 여부를 고릅니다

가벼운 작업

1. 1. 한 문장 요구사항
2. 2. 작은 수정·스크립트
3. 3. 바로 구현

복잡한 작업

1. 1. 여러 이해관계자
2. 2. 요구사항·계획 분리
3. 3. 검증 뒤 구현

명세 비용보다 재작업 비용이 큰 프로젝트에서 효과가 커집니다.

작은 기능 하나로 워크플로를 시험하는 방법

첫 도입은 결제나 권한처럼 위험한 핵심 기능보다, 요구사항이 분명하면서도 예외가 몇 개 있는 기능이 좋습니다. 예를 들어 사진 정리 화면이라면 날짜별 묶기, 드래그 이동, 중첩 앨범 금지처럼 성공 여부를 눈으로 확인할 수 있습니다.

크게 보기

specify 단계에서는 사용자가 무엇을 할 수 있어야 하는지만 씁니다. 데이터베이스와 프레임워크는 plan으로 미룹니다. clarify에서는 날짜가 없는 사진, 중복 파일, 드래그 취소처럼 빠진 조건을 찾습니다. 이후 tasks가 만든 목록이 사용자 스토리를 모두 덮는지 analyze로 확인합니다.

크게 보기

완료 뒤에는 구현 속도보다 되돌아간 횟수를 기록하세요. 요구사항 변경 때문에 코드를 다시 짠 횟수, 리뷰에서 처음 발견된 조건, 명세와 다른 구현을 고친 시간을 비교하면 이 절차가 팀에 이득인지 판단할 수 있습니다.

크게 보기

지시를 늘리는 대신 덜어내는 방향의 근거는 컨텍스트 엔지니어링 편에 있습니다.

체크리스트

• uv 설치 확인
• specify integration list 로 우리 에이전트가 지원되는지 확인
• /speckit.specify 에서 기술 스택을 언급하지 않았다
• /speckit.plan 전에 /speckit.clarify 실행
• /speckit.implement 전에 /speckit.analyze 실행
• 커뮤니티 확장·프리셋은 설치 전 소스 확인
• 팀 표준이 필요하면 번들로 묶어 버전 고정

사진 앨범 예제 대신 블로그 검사를 명세해 봅시다

다음은 이번 블로그 점검에서 나온 요구사항을 바탕으로 정리한 작은 예제입니다. 위 사진 앨범 명령은 공식 문서의 사용 예시이고, 아래 자료는 같은 분리 원칙을 우리 문제에 적용한 명세입니다. spec-kit이 자동으로 구현해 준 결과는 아닙니다.

요청: “게시 전 깨진 링크를 찾아줘.” 이 문장만으로 구현하면 비공개 글의 정상 404까지 오류로 처리하거나, 화면이 보이는 500을 놓칠 수 있습니다.

크게 보기

명확히 한 조건: 홈과 글에서 실제 연결된 내부 URL을 검사한다. 리다이렉트의 최종 목적지도 검사한다. 의도적인 비공개 주소는 공개 링크에서 발견됐을 때만 문제로 기록한다. 외부 API를 호출하거나 로그인하지 않는다. 출력에는 출발 페이지·목적지·상태 코드가 있어야 한다.

크게 보기

입력 사례	기대 결과	요구사항이 막는 실수
공개 메뉴가 #로 연결	미완성 목적지로 보고	상태 200만 보고 정상 처리
공개 강의 URL이 500 반환	오류로 보고	일부 화면이 보인다고 정상 처리
어디에서도 연결하지 않은 비공개 글이 404	공개 링크 오류에 포함하지 않음	비공개 글을 억지로 되살리기

spec·plan·tasks 예제에는 요구사항과 구현 수단을 분리해 넣었습니다. Python 대신 Node로 바꾸더라도 위 기대 결과는 같아야 합니다. 이처럼 출력과 예외를 먼저 정하면 “완료”의 의미를 코드 작성 전에 합의할 수 있습니다.

출처

• github/spec-kit — GitHub README. 설치·업그레이드 명령, 슬래시 명령 목록, 확장·프리셋·번들 구조와 우선순위, 지원 에이전트 30개 이상은 이 문서 기준입니다.
• Spec Kit 문서 사이트

확인 날짜: 2026년 9월 14일. 기존 문서 설명과 이번 검증 범위는 본문에서 구분했습니다. 원문이 갱신되면 이 글의 내용도 달라질 수 있습니다.