요구사항의 빈칸을 Spec으로 바꾸기 | Shape
AI가 조사한 근거와 제안한 후보를 바탕으로 중요한 빈칸을 결정하고, 구현 가능한 동작과 완료 기준을 spec.md로 남깁니다
마지막 업데이트: 2026. 8. 8.
Overview
examples/requirements.md에는 핵심 사용자 동작만 적혀 있고, 구현 결과를 바꿀 중요한 결정은 비어 있습니다. 이를 정하지 않고 구현하면 AI의 추측이 그대로 코드가 됩니다.
이번 Lesson에서는 shape-idea와 대화해 빈칸을 결정하고, 구현할 동작과 완료 기준을 spec.md로 남깁니다.
학습 목표
- 요구사항에서 이미 정해진 내용과 구현 전에 결정해야 할 빈칸을 구분합니다.
- AI가 조사하거나 가정해도 되는 문제와 사람이 직접 판단할 문제를 나눕니다.
shape-idea를 실행해 구현 가능한 동작과 완료 기준이 담긴spec.md를 완성합니다.
요구사항의 빈칸 찾기
먼저 템플릿의 examples/requirements.md에서 이미 정해진 내용과 아직 결정해야 할 내용을 나눠 봅니다.
- URL을 입력하고 초기화한 뒤 Defuddle로 본문을 변환합니다.
- 제목, 저자와 렌더링된 Markdown을 보여줍니다.
- 결과를 복사하거나 내려받고, 프롬프트와 함께 ChatGPT 또는 Claude로 엽니다.
- 다크 모드를 지원합니다.
하지만 실제 동작을 구현하려면 다음 세 가지를 더 결정해야 합니다.
| 결정할 것 | 결정하지 않으면 생기는 차이 |
|---|---|
| 변환 대상과 실패 처리 | 지원할 페이지의 범위와 변환하지 못했을 때 보여줄 결과가 달라집니다. |
| 외부 LLM을 여는 방식 | 내용을 복사한 뒤 새 탭을 열지, 서비스에 직접 전달할지 달라집니다. |
| 입력과 결과의 보관 | 현재 작업에서만 사용할지, 브라우저나 서버에 기록할지 달라집니다. |
처음 받은 requirements.md는 그대로 보존하고, 새로 확정한 결정은 Spec에 남깁니다.
shape-idea: 요구사항을 함께 결정하는 과정
Lesson 1에서 만든 feedme-clone 저장소를 Claude Code로 열고 다음과 같이 실행합니다.
/shape-idea @examples/requirements.mdshape-idea는 곧바로 제품 코드를 작성하지 않습니다. 프로젝트의 기존 결정과 코드, 외부 근거를 먼저 조사한 뒤 구현 결과를 크게 바꾸는 결정부터 하나씩 질문합니다.
AI는 확인한 근거와 추천안을 제시하고, 사람은 자신의 의도에 맞게 선택하거나 바로잡습니다. 쉽게 되돌릴 수 있는 선택은 AI가 가정으로 남기고, 중요한 빈칸이 모두 정해지면 대화를 마치고 spec.md를 만듭니다.
AI에게 맡길 판단과 사람이 결정할 문제 나누기
모든 빈칸에 사람이 답할 필요는 없습니다. 누가 더 잘 판단할 수 있는지보다 틀렸을 때 결과가 얼마나 달라지고, 무엇으로 확인할 수 있는지를 기준으로 나눕니다.
| 문제 | 처리 방식 | Feedme 예시 |
|---|---|---|
| 이미 근거로 확인할 수 있는 사실 | AI가 공식 문서와 코드에서 조사합니다. | Defuddle가 입력으로 받는 데이터와 반환하는 메타데이터 |
| 되돌리기 쉽고 결과 차이가 작은 선택 | AI가 수정 가능한 가정으로 제안합니다. | 프롬프트 프리셋의 표시 순서 |
| 범위와 사용자 동작을 크게 바꾸는 선택 | AI가 후보와 추천 이유를 준비하고 사람이 결정합니다. | 동적 페이지 지원 여부, 외부 LLM을 여는 방식 |
| 직접 봐야 판단할 수 있는 경험 | 실행 가능한 결과나 비교안을 보고 사람이 결정합니다. | 결과 화면에 복사, 다운로드와 LLM으로 열기를 어떻게 배치할지 |
사람은 AI가 이미 확인할 수 있는 사실까지 대신 조사하지 않습니다. 반대로 되돌리기 어렵거나 제품의 범위를 바꾸는 선택을 “알아서 해줘”라고 넘기지 않습니다. AI는 근거와 후보를 준비하고, 사람은 의도와 수용 기준을 제공합니다.
build-prototype: 화면으로 결정하기
화면 구성이나 상태 변화를 말로만 결정하기 어려울 때 build-prototype을 사용합니다. 현실적인 더미 데이터로 필요한 화면과 상태를 조작할 수 있는 HTML 파일 하나를 만들며, 실제 API를 연결하거나 제품 코드를 구현하지는 않습니다.
사용자는 프로토타입을 직접 눌러보며 화면 구성과 동작을 확인합니다. 결정하지 못한 부분이 있다면 나머지 조건을 고정하고 두세 가지 안을 비교한 뒤 하나를 선택합니다.
프로토타입은 필수 단계가 아닙니다. 문장과 근거만으로 결정할 수 있다면 건너뜁니다. 전체 화면을 승인했을 때만 docs/specs/<slug>/prototype.html로 보존하고, 확정한 결정은 spec.md에 반영합니다.
완성된 spec.md 검토하기
중요한 결정이 모두 확정되거나 명시적으로 미뤄지면 shape-idea는 docs/specs/<slug>/spec.md를 만듭니다. 처음 받은 요구사항은 requirements.md에 보존하고, 대화에서 확정한 결정은 spec.md에 남깁니다.
Spec의 형식은 작업에 따라 달라질 수 있지만 다음 내용은 확인할 수 있어야 합니다.
- 목표: 어떤 문제를 해결하고 사용자에게 무엇이 달라지는지 설명합니다.
- 확정한 동작과 이유: 사용자가 할 수 있는 일과 그렇게 결정한 이유를 기록합니다.
- 완료 기준: 구현이 끝난 뒤 무엇을 실행하고 어떤 결과를 확인할지 적습니다.
- 가정과 제외 범위: 아직 검증하지 않은 전제와 이번 작업에서 다루지 않을 내용을 구분합니다.
- 미룬 결정과 위험: 지금 정하지 않은 문제와 구현에 영향을 줄 수 있는 불확실성을 남깁니다.
검토할 때는 새로운 대화가 requirements.md와 spec.md만 읽고도 무엇을 구현하고 어떻게 완료를 판단할지 이해할 수 있는지 확인합니다. 모호한 표현, 확정되지 않은 선택, 파일이나 컴포넌트 같은 구현 방법이 결정처럼 들어가 있다면 바로잡습니다.
[미션] 같은 저장소에서 spec.md 완성하기
Lesson 1에서 만든 feedme-clone 저장소에서 직접 요구사항의 빈칸을 결정합니다.
1. shape-idea 실행하기
Claude Code에서 다음 프롬프트를 실행합니다.
/shape-idea @examples/requirements.mdAI가 추천한 내용을 그대로 승인하지 말고, 추천 이유와 결과 차이를 확인해 자신의 의도와 다르면 바로잡습니다.
가능하면 이번 Mission에서 build-prototype도 한 번 사용해 보세요. 화면 구성을 말로 결정하기 어렵다면 프로토타입을 요청하고, 직접 눌러본 뒤 선택한 결과를 spec.md에 반영합니다. 문장과 근거만으로 충분히 결정할 수 있다면 만들지 않아도 됩니다.
2. 생성된 Spec 검토하기
대화가 끝나면 다음 구조가 생깁니다.
feedme-clone/
└── docs/
└── specs/
└── <slug>/
├── spec.md
└── prototype.html # 전체 화면을 승인했을 때만 생성spec.md를 열어 목표, 확정한 동작과 이유, 완료 기준, 가정과 제외 범위, 미룬 결정과 위험을 확인합니다. 구현 파일이나 내부 상태처럼 아직 결정할 필요가 없는 방법이 들어갔다면 제거합니다.
핵심 포인트 정리
- 요구사항과 빈칸 분리: 처음 받은 요구사항은 출발점으로 보존하고, 구현 전에 결과를 바꾸는 빈칸만 대화에서 결정합니다.
- 판단 역할 분담: AI는 공식 근거와 후보를 준비하고, 사람은 범위와 수용 기준처럼 의도가 필요한 선택을 결정합니다.
- 결정의 저장 위치: 확정한 사용자 동작과 완료 기준은
spec.md에 남기고, 직접 봐야 했던 전체 화면만 승인 후prototype.html로 보존합니다.
이어서 배울 내용
이제 무엇을 만들지와 무엇을 확인해야 완료인지가 정해졌습니다. 다음 Lesson에서는 각 부분을 따로 완성해도 사용할 수 있는지 살펴보고, 한 번에 구현할지 여러 Task로 나눌지 선택합니다. 첫 테스트 전에 AI와 테스트할 동작과 확인 방법을 정하고, 적용 가능한 동작은 TDD로 구현한 뒤 전체 검증과 자동 코드 리뷰까지 마칩니다.