요구사항의 빈칸을 Spec으로 바꾸기 | Shape

Overview

Feedme 요구사항에는 핵심 사용자 동작만 적혀 있고, 구현 결과를 바꿀 중요한 결정은 비어 있습니다. 새 서비스를 시작할 때는 이 빈칸을 정하기 전에 누구의 어떤 문제를 푸는지 전체 방향도 공통 전제로 남겨야 합니다.

이번 Lesson에서는 서비스 전체 방향과 이번 작업의 범위를 구분하고, 요구사항의 빈칸을 결정해 구현할 동작과 완료 기준을 남깁니다.

학습 목표

• 요구사항에서 이미 정해진 내용과 구현 전에 결정해야 할 빈칸을 구분합니다.
• define-product를 실행해 서비스 전체 방향을 PRODUCT.md에 남깁니다.
• 서비스 전체 방향, 이번 작업의 결정과 다음 작업에서도 사용할 프로젝트 지식을 구분합니다.
• AI가 조사하거나 가정해도 되는 문제와 사람이 직접 판단할 문제를 나눕니다.
• shape-idea를 실행해 구현 가능한 동작과 완료 기준이 담긴 spec.md를 완성합니다.

define-product: 서비스 방향 정하기

요구사항은 이번에 만들 동작을 설명하지만, 서비스 전체가 누구의 어떤 문제를 풀고 어떤 변화를 약속하는지는 대신하지 않습니다. 이 방향이 없으면 작업이 바뀔 때마다 같은 제품 전제를 다시 설명해야 합니다.

define-product는 대략적인 서비스 방향에서 시작해 실제 사용자와 사용 상황, 현재 문제와 반복되는 사용자 흐름을 하나씩 확인합니다. 사용자가 정리된 방향을 확인하면 프로젝트 루트의 PRODUCT.md에 남깁니다.

Feedme는 웹페이지 본문을 Markdown으로 변환해 LLM으로 바로 넘기는 서비스라는 방향에서 시작합니다. 이어지는 shape-idea는 이 전체 방향을 읽고, 아래 요구사항에서 이번에 구현할 동작과 완료 기준을 구체화합니다.

shape-idea: 정해진 것과 정할 것 나누기

이번 Mission에서 shape-idea에 입력할 Feedme 요구사항은 다음과 같습니다.

웹 페이지 URL을 Markdown으로 변환해 LLM으로 바로 넘기는 서비스.

## 사용자 흐름

1. **입력** — URL 붙여넣기, 지우기 버튼으로 리셋
2. **변환** — 본문을 Markdown으로 추출 *(defuddle 라이브러리 필수, https://defuddle.md/docs 참조)*
3. **결과 확인** — 페이지 제목·저자 헤더 + 렌더링된 Markdown
4. **내보내기**
   - 복사하기 / .md 파일 다운로드
   - ChatGPT·Claude로 열기 (프롬프트 선택적으로 앞에 붙이기)

## 프롬프트
- 프리셋: 요약해줘 / 한국어로 번역해줘 / 쉽게 설명해줘
- 직접 입력: 프리셋 옆 "직접 입력" 선택 시 텍스트 인풋 노출, 1회용(저장하지 않음)

## 기타
- 다크모드 토글

사용자 흐름은 정해져 있지만, 실제 동작을 구현하려면 다음 세 가지를 더 결정해야 합니다.

shape-idea는 AI가 빈칸을 추측으로 채우지 않도록 요구사항을 곧바로 구현하지 않습니다. 프로젝트의 기존 결정과 질문에 필요한 코드·외부 근거를 먼저 확인한 뒤 구현 결과를 크게 바꾸는 결정만 하나씩 질문합니다.

구현에 필요한 빈칸이 모두 정해지거나 명시적으로 미뤄지면 shape-idea는 대화를 마치고 spec.md를 만듭니다.

빈칸마다 처리 방식이 다릅니다

shape-idea는 결과가 얼마나 달라지는지와 무엇으로 확인할 수 있는지에 따라 빈칸의 처리 방식을 나눕니다.

사람은 AI가 이미 확인할 수 있는 사실까지 대신 조사하지 않습니다. 반대로 되돌리기 어렵거나 제품의 범위를 바꾸는 선택을 “알아서 해줘”라고 넘기지 않습니다. AI는 근거와 후보를 준비하고, 사람은 의도와 수용 기준을 제공합니다.

explain-visually: 이해한 뒤 결정하기

선택지가 무엇을 뜻하는지 이해되지 않으면 먼저 설명을 바꿔야 합니다. explain-visually는 구조는 다이어그램, 차이는 표, 실제 값의 흐름은 실행 추적, 코드의 역할은 주석 코드로 보여줍니다. 한 문장으로 충분하면 별도 시각 자료를 만들지 않습니다.

Feedme에서 프롬프트 선택과 외부 LLM으로 열기가 어떻게 이어지는지 잘 보이지 않는다면 다음처럼 요청할 수 있습니다.

프롬프트를 선택한 뒤 외부 LLM으로 열기까지 값이 어떻게 이어지는지 시각적으로 설명해줘.

시각적 설명은 선택을 대신하지 않고 프로젝트 문서에도 남지 않습니다. 관계를 이해한 뒤 shape-idea 대화로 돌아와 어떤 동작을 만들지 결정합니다.

build-prototype: 직접 써 보고 결정하기

화면 하나가 아니라 전체 화면 구성과 화면 사이의 관계를 말로 결정하기 어려울 때 build-prototype을 사용합니다. 화면 하나에 대한 질문이라면 shape-idea가 직접 후보를 보여주므로, 문장과 근거만으로 결정할 수 있다면 건너뜁니다.

더미 데이터로 전체 화면과 상태를 눌러볼 수 있는 HTML 파일 하나를 만들 뿐, 제품 코드는 구현하지 않습니다. 결정하지 못한 부분은 나머지 조건을 고정하고 두세 안을 비교해 고릅니다. 확정한 결정과 미룬 문제는 spec.md에 반영하고, 모든 화면을 승인했을 때만 docs/specs/<slug>/prototype.html로 남깁니다.

explain-visually는 관계를 이해하기 위한 설명이고, build-prototype은 사용 경험을 직접 판단하기 위한 임시 제품입니다.

project-knowledge: 이미 정한 것을 다시 결정하지 않기

새 작업을 시작할 때마다 서비스 방향, 프로젝트의 용어와 이전 결정을 처음부터 설명하면 같은 논의를 반복하게 됩니다. shape-idea는 질문하기 전에 PRODUCT.md를 읽고, project-knowledge를 통해 GLOSSARY.md와 이번 작업에 관련된 결정 문서를 확인합니다.

새 대화가 이어받아야 할 내용은 사용하는 범위에 따라 다음 위치에 나눠 남깁니다.

현재 코드와 결정 문서가 다르면 project-knowledge는 코드에 맞춰 문서를 고치지 않고 차이를 사람에게 확인합니다. 코드는 지금 구현된 동작을 보여줄 뿐, 어떤 방향이 의도였는지는 증명하지 못하기 때문입니다.

완성된 spec.md 검토하기

중요한 결정이 모두 확정되거나 명시적으로 미뤄지면 shape-idea는 docs/specs/<slug>/spec.md를 만듭니다. 처음 입력한 요구사항과 대화에서 확정한 결정을 현재 구현 기준으로 정리합니다.

Spec의 형식은 작업에 따라 달라질 수 있지만 다음 내용은 확인할 수 있어야 합니다.

1. 목표: 어떤 문제를 해결하고 사용자에게 무엇이 달라지는지 설명합니다.
2. 요구사항과 확정한 동작: 처음 입력한 요구사항과, 대화에서 확정한 사용자 동작을 그렇게 정한 이유와 함께 기록합니다.
3. 완료 기준: 구현이 끝난 뒤 무엇을 실행하고 어떤 결과를 확인할지 적습니다.
4. 가정과 제외 범위: 아직 검증하지 않은 전제와 이번 작업에서 다루지 않을 내용을 그 이유와 함께 구분합니다.
5. 미룬 결정과 위험: 지금 정하지 않은 문제와 구현에 영향을 줄 수 있는 불확실성을 남깁니다.

검토할 때는 새로운 대화가 spec.md만 읽고도 무엇을 구현하고 어떻게 완료를 판단할지 이해할 수 있는지 확인합니다. 모호한 표현과 아직 확정하지 않은 선택은 다시 정리하고, 파일 구성이나 내부 상태처럼 구현하면서 정할 내용이 들어가 있다면 뺍니다.

[미션] 같은 저장소에서 PRODUCT.md와 spec.md 완성하기

Lesson 1에서 만든 feedme-clone 저장소에서 서비스 전체 방향을 정리한 뒤 요구사항의 빈칸을 결정합니다.

Step 1: define-product 실행하기

feedme-clone 저장소를 Claude Code로 열고 다음 내용을 전송합니다.

/define-product

웹페이지 본문을 Markdown으로 변환해 LLM으로 바로 넘기는 서비스

질문에 답한 뒤 정리된 서비스 방향을 확인합니다. 승인이 끝나면 프로젝트 루트에 PRODUCT.md가 생깁니다.

Step 2: shape-idea 실행하기

같은 저장소에서 다음 코드 블록 전체를 한 번에 붙여넣어 전송합니다.

/shape-idea

웹 페이지 URL을 Markdown으로 변환해 LLM으로 바로 넘기는 서비스.

## 사용자 흐름

1. **입력** — URL 붙여넣기, 지우기 버튼으로 리셋
2. **변환** — 본문을 Markdown으로 추출 *(defuddle 라이브러리 필수, https://defuddle.md/docs 참조)*
3. **결과 확인** — 페이지 제목·저자 헤더 + 렌더링된 Markdown
4. **내보내기**
   - 복사하기 / .md 파일 다운로드
   - ChatGPT·Claude로 열기 (프롬프트 선택적으로 앞에 붙이기)

## 프롬프트
- 프리셋: 요약해줘 / 한국어로 번역해줘 / 쉽게 설명해줘
- 직접 입력: 프리셋 옆 "직접 입력" 선택 시 텍스트 인풋 노출, 1회용(저장하지 않음)

## 기타
- 다크모드 토글

AI가 추천한 내용을 그대로 승인하지 말고, 추천 이유와 결과 차이를 확인해 자신의 의도와 다르면 바로잡습니다.

질문이나 선택지의 영향이 이해되지 않으면 어떤 관계가 보이지 않는지 말하고 시각적으로 설명해 달라고 요청합니다. 설명을 이해한 뒤 원래 질문으로 돌아와 결정합니다.

화면 구성을 말로 결정하기 어렵다면 프로토타입을 요청하고, 직접 눌러본 뒤 선택한 결과를 spec.md에 반영합니다.

Step 3: 생성된 Spec 검토하기

대화가 끝나면 다음 구조가 생깁니다.

feedme-clone/
├── PRODUCT.md
└── docs/
    └── specs/
        └── <slug>/
            ├── spec.md
            └── prototype.html  # 모든 화면의 검토를 끝내고 승인했을 때만 생성

spec.md를 열어 목표, 처음 입력한 요구사항과 확정한 동작, 완료 기준, 가정과 제외 범위, 미룬 결정과 위험을 확인합니다. 빠진 항목이 있다면 Claude Code에 보완을 요청하고, 구현 파일이나 내부 상태처럼 아직 결정할 필요가 없는 방법이 들어갔다면 제거합니다.

project-knowledge가 GLOSSARY.md나 docs/decisions/를 만들거나 수정했다면 열어서 확인합니다. 두 곳에는 다음 작업에서도 그대로 쓸 용어와 결정만 남기고, 이번 작업에서만 쓰는 선택은 spec.md로 옮깁니다.

핵심 포인트 정리

1. 전체 방향과 작업 범위: define-product는 서비스 전체 방향을 PRODUCT.md에, shape-idea는 이번 작업의 동작과 완료 기준을 spec.md에 남깁니다.
2. 요구사항과 빈칸 분리: 처음 입력한 요구사항에서 출발해, 구현 전에 결과를 바꾸는 빈칸만 대화에서 결정합니다.
3. 지식의 저장 위치: 현재 용어는 GLOSSARY.md, 다음 작업에서도 쓸 결정은 docs/decisions/, 이번 작업의 동작과 완료 기준은 spec.md에 남깁니다.
4. 판단 역할 분담: 관계가 이해되지 않으면 시각적 설명을, 직접 써 봐야 하면 프로토타입을 요청합니다. AI가 근거와 후보를 준비해도 최종 선택은 사람이 결정합니다.

이어서 배울 내용

이제 무엇을 만들지와 무엇을 확인해야 완료인지가 정해졌습니다. 다음 Lesson에서는 이 Spec을 하나의 흐름으로 바로 구현할지, 독립된 결과로 나눠 구현할지 정하고 실제로 동작하는 Feedme를 만듭니다.