Spec이 대체 뭔가요? — 초보자를 위한 Spec Kit 명세 작성법

Spec Kit을 처음 켜고 specs/ 폴더를 열면, 많은 분들이 비슷한 표정을 짓습니다. spec.md, plan.md, tasks.md, research.md, data-model.md, contracts/, checklists/ … 파일이 줄줄이 쏟아지는데, 정작 "spec(명세)이 뭔지"부터 아리송합니다. 시리즈 글을 읽어도 막막한 이유는, 보통 완성된 산출물(결과물)을 먼저 보기 때문입니다. 결과물은 규칙이 많아 보이지만, 그 규칙들은 사실 아주 단순한 한 가지 생각에서 출발합니다.

이 글은 그 출발점으로 돌아가, "무엇을 왜 적는 것인가" 를 비유로 잡고, specs/ 디렉터리가 왜 그렇게 생겼는지 해부한 뒤, 명세 한 장을 실제로 채우는 순서까지 따라가 봅니다. 명령어를 외우기보다 "왜 이렇게 하는가"를 이해하는 데 초점을 맞췄으니, 천천히 읽어 보시면 좋겠습니다.

이 글에서 배우는 것

• spec이 코드가 아니라 "무엇·왜"를 적은 합의 문서라는 것 (집 짓기 비유)
• specs/ 디렉터리가 복잡해 보이는 진짜 이유와, 누가 어떤 파일을 만드는지
• 명세 한 장에 들어가는 6가지 구성요소를 초보자 언어로 번역
• 빈 화면 앞에서 막히지 않는 5단계 작성 순서
• 아주 작은 "연락처 폼" 예제로 보는 명세 한 장 통째

이 글은 Spec Kit 시리즈의 입문 보조편입니다. 시리즈(① 왜 SDD인가 → ⑦ 실전 회고)가 전체 흐름을 다룬다면, 이 글은 그중 가장 막히기 쉬운 "명세 쓰기" 한 단계를 초보자 눈높이로 다시 풀어 씁니다.

1. Spec이 대체 뭔가요? — 집을 짓는다고 생각해 보세요

가장 먼저 오해를 풀어야 합니다. 명세(spec)는 코드가 아닙니다. 설계도도 아닙니다. 명세는 "내가 무엇을, 왜 원하는가"를 사람의 말로 적어 둔 합의 문서입니다.

집을 짓는 과정에 빗대면 이렇습니다.

여기서 핵심은 1단계(요구사항서)에는 "어떻게"가 들어가지 않는다는 점입니다. 집주인은 "방 3개, 재택 공간"이라고 말하지, "2×4 목조에 단열재는 글라스울로"라고 말하지 않습니다. 그건 설계자(plan)의 몫이니까요.

spec.md도 똑같습니다. "사용자가 무엇을 할 수 있어야 하고, 그게 왜 필요한가" 만 적습니다. "PostgreSQL에 저장하고 React로 보여준다" 같은 문장은 명세가 아니라 설계이고, 그건 다음 단계인 plan으로 미룹니다.

한 문장으로: spec = "무엇(What) · 왜(Why)", plan = "어떻게(How)". 이 경계가 Spec Kit의 거의 모든 규칙의 뿌리입니다.

왜 이렇게까지 나눌까요? 두 가지 때문입니다.

• 해법을 너무 일찍 못 박지 않기 위해서. "Kafka로 처리한다"를 명세에 적는 순간, 정작 필요한 게 5초마다 한 번 확인하는 단순 폴링이었다는 사실은 영영 검토되지 않습니다.
• "다 됐다"를 판단할 기준을 만들기 위해서. 명세는 나중에 "이 코드가 원하던 걸 만족하나?"를 대조할 잣대입니다. 잣대에 구현이 섞이면 잣대가 흐려집니다.

2. specs/ 디렉터리가 복잡해 보이는 진짜 이유

이제 폴더를 다시 봅시다. 복잡해 보이는 이유는 딱 하나입니다 — 하나의 기능이 위 4단계로 나뉘고, 단계마다 파일이 생기기 때문입니다. 즉 파일이 많은 게 아니라, 한 기능의 "생각의 흐름"이 파일로 박제된 것입니다.

실제 디렉터리는 대략 이렇게 생깁니다.

specs/
└── 001-내-기능-이름/
    ├── spec.md          ← ① 무엇·왜 (여기서 시작!)
    ├── plan.md          ← ② 어떻게 (기술 설계)
    ├── tasks.md         ← ③ 할 일 목록
    ├── research.md      ← (보조) 기술 선택의 근거
    ├── data-model.md    ← (보조) 데이터 구조
    ├── contracts/       ← (보조) API 약속
    └── checklists/      ← (보조) 품질 점검표

겁먹을 필요 없습니다. 초보자가 처음 직접 손으로 쓰는 파일은 사실상 spec.md 하나입니다. 나머지는 다음 단계 명령들이 만들어 줍니다.

그래서 "specs 규칙이 어렵다"는 느낌의 90%는 spec.md 한 장만 이해하면 풀립니다. 나머지는 그 한 장에서 파생됩니다.

명령 이름이 문서마다 다르게 보일 수 있습니다. 예전 자료는 점 표기(/speckit.specify), 최신 설치본은 하이픈 표기(/speckit-specify)를 씁니다. 둘은 같은 명령이니 설치된 쪽을 쓰면 됩니다.

3. 명세 한 장에 뭐가 들어가나 — 6가지를 쉬운 말로

spec.md를 열면 낯선 용어(FR, SC, Acceptance Scenario…)가 나옵니다. 하나씩 초보자 언어로 번역하면 이렇습니다.

① User Story (사용자 이야기) — "누가 / 무엇을 / 왜"

기능을 사용자 입장의 한 문장으로 적습니다.

방문자로서, 문의 폼으로 회사에 연락하고 싶다.
왜냐하면 이메일 주소를 일일이 찾지 않고 바로 문의하기 위해서다.

스토리는 우선순위(P1, P2…) 를 붙여 나열합니다. P1 하나만 만들어도 가치가 있도록 쪼개는 게 요령입니다.

② Acceptance Scenario (수용 시나리오) — "이러면 성공"

스토리가 "됐다"고 말할 수 있는 구체적 상황을, Given–When–Then(주어진 상황–행동–결과)으로 적습니다.

Given 방문자가 이름·이메일·내용을 올바르게 채웠을 때,
When  전송 버튼을 누르면,
Then  성공 메시지가 보이고 담당자에게 메일이 도착한다.

이게 나중에 "테스트"가 됩니다. 테스트로 옮길 수 없는 모호한 문장은 명세로서 실패입니다.

③ Functional Requirement (기능 요구사항, FR) — "시스템은 ~해야 한다"

스토리를 시스템이 지켜야 할 검증 가능한 규칙으로 풀어 번호를 매깁니다.

FR-001: 시스템은 이름·이메일·문의 내용을 필수로 받아야 한다.
FR-002: 시스템은 잘못된 이메일 형식을 거부해야 한다.
FR-003: 시스템은 봇 제출을 차단해야 한다.

번호(FR-001…)를 매기는 이유는, 나중에 plan·tasks·코드가 "이건 FR-002를 위한 것" 이라고 추적할 수 있게 하기 위해서입니다.

④ Success Criteria (성공 기준, SC) — "측정 가능한 완료의 정의"

"잘 됐다"를 숫자나 관찰 가능한 사실로 적습니다. 기술 용어 없이.

SC-001: 방문자는 3분 안에 문의를 완료할 수 있다.
SC-002: 봇 스팸 제출은 모두 차단된다.

FR이 "무엇을 해야 하나"라면, SC는 "어느 정도면 충분한가"입니다.

⑤ Edge Cases (예외 상황) — "이럴 땐 어쩌지?"

- 같은 사람이 같은 내용을 연달아 10번 보내면?
- 메일 서버가 꺼져 있으면?

⑥ Assumptions (가정) — "이건 이렇다고 치고 갑니다"

명세에 일일이 안 적은 합리적 기본값을 적어 둡니다. "문의 데이터는 DB에 저장하지 않고 메일로만 전달한다" 같은 것.

6가지가 많아 보이지만, ①②만 제대로 적어도 절반은 끝입니다. ③④는 ①②에서 자연스럽게 풀려 나오고, ⑤⑥은 빈틈을 메우는 메모입니다.

4. 빈 화면 앞에서 막히지 않는 5단계 작성 순서

막막함의 정체는 "한 번에 완벽하게 쓰려는 마음"입니다. 명세는 위에서 아래로 한 번에 쓰는 게 아니라, 좁게 시작해 넓혀 가는 것입니다.

1단계 — 한 문장으로 시작. "방문자가 문의 폼으로 연락할 수 있게 한다." 이 한 줄이면 충분합니다.

2단계 — 사용자 스토리 1~3개. 가장 중요한 것(P1)부터. 욕심내지 말고 P1 하나로 시작해도 됩니다.

3단계 — 각 스토리에 수용 시나리오 1~3개. Given–When–Then으로. "성공하면 어떻게 보이지?"만 떠올리면 됩니다.

4단계 — 시나리오를 FR로 풀기. 시나리오를 만족시키려면 시스템이 뭘 해야 하는지 규칙으로.

5단계 — SC로 "끝"의 기준 박기. 숫자·사실로.

그리고 전 과정에서 단 하나의 황금률만 지키면 됩니다.

"어떻게(How)"가 손끝에서 나오려 하면 멈추세요. 프레임워크·DB·API 모양은 전부 plan 단계로. 명세에는 "무엇·왜"만.

Claude(또는 Spec Kit)에게 시킬 때

직접 빈 화면을 채우는 대신, 초안을 생성시키고 다듬는 방식이 초보자에게 훨씬 쉽습니다.

/speckit-specify 방문자가 문의 폼으로 회사에 연락할 수 있어야 한다.
이름·이메일·내용을 받고, 잘못된 이메일과 봇 제출은 막는다.
문의는 담당자 메일로 전달한다(별도 저장은 하지 않음).

이렇게 "무엇·왜"만 한 문단 불러주면, /speckit-specify가 위 6요소를 갖춘 spec.md 초안을 만들어 줍니다. 당신의 진짜 일은 그 초안을 읽고, 틀린 가정을 고치고, 빠진 시나리오를 더하는 것입니다. 백지에서 시작하는 것보다 열 배 쉽습니다.

초안에 [NEEDS CLARIFICATION] 표시가 보이면, 그건 "여기 결정이 필요해요"라는 신호입니다. 너무 많으면 가장 중요한 2~3개만 정하고 나머지는 합리적 기본값으로 넘어가세요. 완벽보다 진도가 중요합니다.

5. 초보자가 자주 하는 실수 5가지

1. 명세에 "어떻게"를 적는다. "Redis로 캐시한다" → 그건 plan. 명세에는 "조회는 즉시 응답해야 한다"처럼 결과만.
2. 테스트로 옮길 수 없는 문장. "빠르고 편리해야 한다" → 무엇이 빠른가? "검색 결과가 1초 안에 나온다"로.
3. [NEEDS CLARIFICATION] 남발. 모든 걸 물으면 진도가 안 나갑니다. 핵심만 묻고 나머지는 가정으로.
4. 범위가 너무 크다. "사이트 전체"를 한 명세에 담으려다 지칩니다. 기능 하나로 좁히세요.
5. 코드부터 짜고 명세를 끼워 맞춘다. 이미 다 만든 코드를 역으로 명세화(역스펙)하는 것도 가능하지만, 그건 별도의 목적(기존 코드 정리)이 있을 때 이야기입니다. 새 기능이라면 명세 → 코드 순서가 정석입니다.

6. 미니 실습 — "연락처 폼" 명세 한 장

위 내용을 아주 작은 예제로 합쳐 봅니다. 실제 spec.md의 축약판입니다.

# Feature Specification: 연락처 폼
 
## User Scenarios
 
### User Story 1 - 문의 보내기 (P1)
방문자로서, 문의 폼으로 회사에 연락하고 싶다.
왜: 이메일을 따로 찾지 않고 바로 문의하기 위해.
 
**Acceptance Scenarios**
1. Given 이름·이메일·내용을 올바르게 채웠을 때,
   When 전송을 누르면, Then 성공 메시지가 뜨고 담당자에게 메일이 간다.
2. Given 이메일 형식이 틀렸을 때,
   When 전송을 누르면, Then "이메일을 확인하세요" 오류가 뜬다.
 
## Requirements
- FR-001: 시스템은 이름·이메일·내용을 필수로 받아야 한다.
- FR-002: 시스템은 잘못된 이메일을 거부해야 한다.
- FR-003: 시스템은 봇/스팸 제출을 차단해야 한다.
 
## Success Criteria
- SC-001: 방문자는 3분 안에 문의를 완료할 수 있다.
- SC-002: 봇 스팸 제출은 모두 차단된다.
 
## Edge Cases
- 같은 내용을 연달아 반복 제출하면? → 중복은 조용히 무시한다.
- 메일 서버가 꺼져 있으면? → 사용자에게 실패를 알린다.
 
## Assumptions
- 문의 데이터는 DB에 저장하지 않고 메일로만 전달한다.

보시면 기술 이야기가 한 줄도 없습니다. 프레임워크도, DB도, API 모양도 없습니다. 오직 "무엇을, 왜, 어느 정도면 됐는지"뿐입니다. 이 한 장이 잘 서 있으면, 그다음 /speckit-plan이 "그럼 어떻게 만들지"를 책임지고, /speckit-tasks가 "그럼 무슨 일부터"를 쪼갭니다.

마무리 — 명세는 "합의"이지 "문서 작업"이 아닙니다

specs/ 디렉터리가 어렵게 느껴졌다면, 그건 규칙이 많아서가 아니라 결과물부터 봤기 때문입니다. 출발점은 단순합니다 — "무엇을 왜 원하는가"를, 누구나 읽고 같은 그림을 떠올릴 수 있게 적는 것. 그게 spec입니다.

처음 한 장은 어설퍼도 괜찮습니다. 한 문장 → 스토리 → 시나리오 → FR → SC 순서로, "어떻게"가 튀어나오면 plan으로 미루며 적어 보세요. 그리고 /speckit-specify에게 초안을 시키고 다듬는 사람이 되면, 생각보다 빠르게 익숙해집니다.

다음 단계: 명세가 섰다면 /speckit-plan으로 "어떻게"를 설계할 차례입니다. specify → plan → tasks → implement로 이어지는 전체 흐름과 실전 예제는 **Spec Kit 시리즈(①~⑦)**에서 이어집니다.