3장. 기획과 명세 — 인터뷰받고 SPEC.md 쓰기
필수 이 단계를 따라가려면 꼭 읽으세요.한 줄 요약: 무엇을 만들지 아직 흐릿하면, 혼자 다 정리하려 하지 말고 Claude에게 나를 인터뷰하게 하세요. 인터뷰가 끝나면 Claude가 그 내용을 SPEC.md(명세서)로 씁니다. 명세는 "어떻게 만들지"가 아니라 "무엇이 되어야 하는지"의 약속입니다. 이 약속이 4~6장에서 만들고, 확인하고, 리뷰하는 기준이 됩니다.
이 장은 2026년 11월 1일에 확인한 Claude Code·GitHub 공식 문서와 spec-kit·OpenSpec 저장소의 설명을 바탕으로 썼습니다. 무엇을 맡길지 구체적으로 말하는 요령은 Claude Code 5장에서 배웠습니다. 이 장은 그 요령을 "만들기 전 단계"로 넓힙니다.
왜 기획부터 하나
1장에서 본 것처럼, AI가 내 머릿속과 다른 것을 만드는 흔한 이유는 저장소만 읽어서는 알 수 없는 정보가 빠졌기 때문입니다.[1] 그 정보는 내 머릿속에만 있습니다. 누가 쓰는지, 무엇이 불편한지, 무엇은 하지 않을지 같은 것들입니다.
GitHub의 입문 튜토리얼도 코드를 쓰기 전에 만들 것을 적어 두고 진행을 추적하라고 합니다.[2]
구체적으로 말할수록 고치는 왕복이 줄어듭니다. 공식 문서는 파일을 짚고, 증상을 말하고, "다 됐다"가 어떤 모습인지 처음에 말하라고 합니다.[3]
| 아쉬운 예 | 나은 예 |
|---|---|
| 할 일 보여 주는 페이지 만들어 줘 | 회의록의 할 일 표를 모아 담당·기한별로 보여 주는 페이지. 다 되면 메모의 할 일 5개가 모두 보여야 해 |
출처: 이 가이드의 예(요령은 공식 문서)[3:1]
확인 퀴즈
AI가 내 머릿속과 다른 것을 만드는 흔한 이유로 공식 문서가 꼽는 것은 무엇일까요?
인터뷰받고 SPEC.md 쓰기
원하는 것이 아직 분명하지 않아도 괜찮습니다. 공식 문서는 프롬프트를 쓰기 전에 다 정리할 필요 없이, Claude에게 나를 인터뷰하게 하라고 합니다.[4] 문서의 예시를 우리말로 옮기면 이런 모양입니다.
이런 걸 만들고 싶은데 아직 깊이 생각해 보지 않았어. 스펙을 쓸 수 있을 때까지 나를 인터뷰하고, 다 되면 SPEC.md에 써 줘.
그러면 Claude는 아직 정하지 않은 부분을 객관식 질문(보기 중에서 고르는 질문)으로 되묻습니다.[5] 예를 들어 "할 일을 담당별로 묶을까요, 기한별로 묶을까요?"처럼 고르기만 하면 되는 질문입니다. 실제 질문은 그때그때 다르니, 보기 중 하나를 고르거나 내 말로 답하면 됩니다.
할 일 보드라면 이런 요청이 됩니다.
3단계 정리도구가 만든 회의록의 할 일 표를 모아서 보여 주는 웹 페이지를 만들고 싶어. 아직 깊이 생각해 보지 않았어. 스펙을 쓸 수 있을 때까지 나를 인터뷰하고, 다 되면 SPEC.md에 써 줘.SPEC.md가 생기면 새 세션에서 그 파일을 보고 만들게 합니다. 깨끗한 맥락과, 글로 적힌 "완료의 정의"로 시작하기 위해서입니다.[6] 인터뷰하며 오간 긴 대화가 만들기에 섞이지 않게 하는 것입니다.
다 만든 뒤에는 SPEC.md와 대조해 확인합니다. 이 이야기는 6장 리뷰에서 다시 합니다.
확인 퀴즈
무엇을 만들지 아직 흐릿할 때 공식 문서가 권하는 방법은 무엇일까요?
좋은 명세의 모양
명세에는 밖에서 보이는 동작을 적습니다. 화면을 보는 사람이 알아챌 수 있는 것만 적는다는 뜻입니다. 할 일 보드의 SPEC.md라면 이런 줄이 들어갑니다.
| 좋은 줄 | 아쉬운 줄 |
|---|---|
| 회의록의 할 일이 하나도 빠짐없이 보인다 | 자바스크립트로 표를 읽는다 |
| 기한이 지난 할 일은 표시가 다르다 | 예쁘게 보인다 |
| 개인 이름 대신 역할만 보인다 | 깔끔한 코드로 만든다 |
출처: 이 가이드의 예
왼쪽 줄은 예/아니오로 확인할 수 있습니다. 5장에서 이 줄들이 그대로 확인 장치가 됩니다.
오른쪽 줄은 어떻게 만들지(기술)나 막연한 느낌입니다. 다음 절에서 볼 명세 도구들의 설명서도 같은 말을 합니다. OpenSpec 설명서는 명세를 "구현 계획이 아니라 동작의 약속"이라고 하고, 겉으로 보이는 동작을 바꾸지 않는 구현 이야기는 보통 명세에 넣지 않는다고 합니다.[7] spec-kit도 명세 단계에서는 기술이 아니라 무엇을, 왜에 집중하고, 기술 선택은 다음 계획 단계로 미루라고 합니다.[8]
확인 퀴즈
할 일 보드 SPEC.md에 넣기 좋은 줄은 무엇일까요?
스펙 주도 개발 도구
명세를 중심에 두고 개발하는 방식을 스펙 주도 개발(Spec-Driven Development)이라고 합니다. 무엇을 왜 만들지 먼저 정하고, 그 명세를 계획·작업·코드로 바꾸는 방식입니다.[9] 이를 돕는 도구로 spec-kit과 OpenSpec이 있습니다.
이 가이드는 두 도구를 설치하지 않습니다. 위에서 배운 "인터뷰 → SPEC.md → 새 세션" 흐름만으로도 같은 생각을 실천할 수 있습니다. 이 절은 이름만 알아 두고 넘어가도 됩니다.
두 도구 모두 사람이 중간에 확인하는 자리를 둡니다.
- spec-kit(GitHub이 만든 도구): 명세 → 계획 → 작업 목록 → 구현을 한 단계씩 실행하고, 결과를 검토한 뒤 넘어가라고 합니다.[10]
- OpenSpec(Fission-AI가 만든 도구): AI가 문서를 쓰고, 사람은 코드가 쓰이기 전에 계획을 검토하게 합니다.[11]
이 가이드의 흐름에서 SPEC.md를 읽고 승인하는 것과 같은 생각입니다.
두 도구 더 알아보기 (눌러서 펼치기)
| 도구 | 만든 곳 | 하는 일 |
|---|---|---|
| spec-kit | GitHub | 명세 → 계획 → 작업 목록 → 구현을 단계별로 |
| OpenSpec | Fission-AI | 변경마다 제안·명세·설계·작업 폴더를 만들기 |
출처: 각 도구의 설명(일부만 옮김)[12][11:1]
설치에는 개발 도구가 따로 필요합니다. spec-kit은 Python 3.11 이상과 uv라는 도구가 필요하고[13], OpenSpec은 터미널 설치(또는 Node.js 22.12 이상)가 필요합니다.[14] Python·uv·Node.js는 프로그램을 돌리는 데 쓰는 개발용 도구입니다. 이 가이드를 따라 하는 데는 하나도 필요 없습니다. 더 큰 프로젝트를 하게 되면 그때 살펴보세요.
확인 퀴즈
이 가이드가 spec-kit과 OpenSpec을 다루는 방식은 무엇일까요?
직접 해 보기
- 2장에서 만든
할일보드폴더를 Claude Code 앱에서 연다. - 위의 인터뷰 요청을 보내고, Claude의 질문에 답한다. 모르면 "추천해 줘"라고 해도 된다.
- 만들어진 SPEC.md를 읽고, 줄마다 "예/아니오로 확인할 수 있나?"를 묻는다. 아니면 고쳐 달라고 한다.
- SPEC.md에 실명·연락처가 들어가지 않았는지 확인한다(공개 저장소이기 때문).
- 마음에 들면 기록(커밋)한다.
이어지는 과제: 4장에서는 새 세션에서 SPEC.md를 바탕으로 계획을 받고, 브랜치에서 첫 화면을 만듭니다.
정리
- AI가 엉뚱한 것을 만드는 흔한 이유는 내 머릿속 정보가 빠졌기 때문이다. 만들기 전에 적는다.
- 모르겠으면 Claude에게 나를 인터뷰하게 하고, 결과를 SPEC.md로 받는다.
- SPEC.md가 생기면 새 세션에서 만든다. 다 만든 뒤 SPEC.md와 대조한다.
- 명세에는 밖에서 보이는 동작을, 예/아니오로 확인할 수 있게 적는다.
- spec-kit·OpenSpec은 같은 생각을 돕는 도구다. 이 가이드는 설치하지 않는다.
용어 정리
| 용어 | 읽는 법 | 한 줄 뜻 |
|---|---|---|
| Spec | 스펙 | 무엇이 되어야 하는지 적은 약속(명세) |
| SPEC.md | 스펙 엠디 | 명세를 적은 파일 |
| Spec-Driven Development | 스펙 드리븐 디벨롭먼트 | 명세를 먼저 정하고 그것으로 만드는 방식 |
| Definition of done | 데피니션 오브 던 | "다 됐다"의 기준 |
이 장을 다 읽었나요?
기록은 이 브라우저에만 저장됩니다. 진행 현황은 전체 목차에서 볼 수 있어요.
다음 장: 4장. 만들기
참고 자료 (14개)
Claude Code 공식 문서, 「Best practices for Claude Code」. "Claude built something different from what you had in mind, or it has to rediscover the same fact at the start of every session. It's missing information it can't get from reading the repo." code.claude.com (확인일 2026-11-01) ↩︎
GitHub 공식 문서, 「Planning your work」. "Before you write code, capture what you want to build and track your progress." docs.github.com (확인일 2026-11-01) ↩︎
Claude Code 공식 문서, 「Best practices for Claude Code」. "If you name the file, describe the symptom, and say what "fixed" looks like up front, you usually save yourself a round of corrections later." code.claude.com (확인일 2026-11-01) ↩︎
Claude Code 공식 문서, 「Best practices for Claude Code」. "When you don't know exactly what you want yet, you don't have to work it all out before you prompt. Ask Claude to interview you instead:" code.claude.com (확인일 2026-11-01) ↩︎
Claude Code 공식 문서, 「Best practices for Claude Code」. "Claude comes back with multiple-choice questions about the parts you haven't pinned down: per-user versus per-key limits, what happens to requests over the limit, what's out of scope." code.claude.com (확인일 2026-11-01) ↩︎
Claude Code 공식 문서, 「Best practices for Claude Code」. "Once
SPEC.mdexists, start a fresh session to build from it, so the build begins with a clean context and a written definition of done." code.claude.com (확인일 2026-11-01) ↩︎OpenSpec 문서, 「Concepts」. "A spec is a behavior contract, not an implementation plan." / "If implementation can change without changing externally visible behavior, it likely does not belong in the spec." github.com (확인일 2026-11-01) ↩︎
spec-kit 문서, 「Spec-Driven Development Quickstart」. "Creates the feature specification from a natural-language description. Focus on the what and why, not the tech stack." github.com (확인일 2026-11-01) ↩︎
spec-kit README. "Define what to build and why, then turn the specification into a plan, tasks, and working code." github.com (확인일 2026-11-01) ↩︎
spec-kit README. "Create a constitution once per project and repeat the remaining steps for each feature. Run these skills in your agent's chat, not your terminal, one at a time, reviewing each result before continuing." github.com (확인일 2026-11-01) ↩︎
OpenSpec README. "Stay organized — each change gets its own folder with proposal, specs, design, and tasks" / "Your AI writes these; you review the plan before any code is written." github.com (확인일 2026-11-01) ↩︎
spec-kit README. "Spec Kit is an open source toolkit that gives AI coding agents structured processes, reusable templates, and documented outcomes." github.com (확인일 2026-11-01) ↩︎
spec-kit README. "You need Python 3.11+, uv, and a supported AI coding agent on Linux, macOS, or Windows." github.com (확인일 2026-11-01) ↩︎
OpenSpec README. "Install OpenSpec. On macOS or Linux, in your terminal:" / "(needs Node.js 22.12.0 or higher)" github.com (확인일 2026-11-01) ↩︎