📑 이 챕터에서 다룰 내용
새 4장에서 5파일+ 사이클의 7단계 흐름을 봤습니다. 이번 장부터 5파일을 차례로 "어떻게 실제로 작성하는가"를 깊게 들어갑니다. 첫 번째는 SPEC.md — "무엇을 만들 것인가"를 결정하는 자리입니다.
| 사전 지식 체크 | 이 장의 목적 | 완료 후 결과물 |
|---|---|---|
| 새 2장 5파일 구조 생성 / 새 3장 Claude Code 설치 완료 / 새 4장 5파일+ 사이클 이해 | SPEC.md v1 → v2를 완성. "무엇을 만들 것인가" 7항목 + E1 회색지대 결정을 한 파일에 박는다 | SPEC.md 파일 (Gemini 1차 검토 반영 v2 + E1 섹션 포함) |
조지 도란이 제안한 SMART 기준: Specific (구체적) · Measurable (측정 가능) · Achievable (달성 가능) · Relevant (관련성) · Time-bound (기한 있음). 이 기준을 충족한 목표는 그렇지 않은 목표보다 성취율이 3배 이상 높습니다.
SPEC.md의 성공 기준이 반드시 숫자여야 하는 이유가 여기 있습니다. "사용자가 만족한다"는 측정 불가능합니다. "배포 2주 내 가입자 50명"은 측정 가능합니다. 달성 여부를 정확히 알 수 있어야 Phase 1을 끝낼 수 있습니다.
중요한 수술을 앞두고 의사 한 명의 의견만 듣는 사람은 없습니다. 다른 병원 의사에게 두 번째 의견을 구합니다. 같은 의료 시스템에서 교육받은 의사도 서로 다른 관점을 가질 수 있기 때문입니다.
Gemini 검토가 필요한 이유도 같습니다. Claude가 만든 SPEC.md를 Claude에게 다시 검토해달라고 하면, 같은 AI이기 때문에 같은 맹점을 가집니다. Gemini는 다른 회사의 AI이기 때문에 Claude가 놓친 것을 발견할 가능성이 높습니다.
→ SPEC.md는 Opus로 만들고 Gemini로 검토합니다.
SPEC.md는 7가지 항목을 반드시 포함해야 합니다. 이 중 하나라도 빠지면 나중에 반드시 막히는 항목이 있습니다. 특히 성공 기준과 수익화는 Phase 1에 반드시 있어야 합니다.
| # | 항목 | 내용 | 없으면 생기는 문제 |
|---|---|---|---|
| 1 | 앱 이름 | 짧고 기억하기 쉬운 이름 | 없으면 CLAUDE.md 설정 불가 |
| 2 | 해결하는 문제 | 한 문장으로 명확하게 | 없으면 기능 선택 기준 없음 |
| 3 | 사용자 정의 | A (주 사용자) · B (부 사용자) 구분 | 없으면 UX 방향 잃음 |
| 4 | Phase 1 핵심 기능 | 최대 3가지만 | 많으면 Phase 1이 끝나지 않음 |
| 5 | 성공 기준 ★ | 숫자로 명시 필수 | 없으면 완성 기준이 없어 무한 확장 |
| 6 | 수익화 방법 ★ | Phase 1에 반드시 포함 | 없으면 Phase 1에 돈 받을 방법 없음 |
| 7 | 기술 스택 | Expo / Next.js · Supabase · Stripe 등 | 없으면 CLAUDE.md 규칙 설정 불가 |
7항목 외에 E1 회색지대 결정 섹션이 5-5절에서 추가됩니다. 모든 프로젝트에 필요한 건 아니지만, 회색지대 (법적·윤리적·시장적)가 있는 프로젝트라면 본문에 명시되어야 합니다. 줍줍·TotalSportsView 두 프로젝트 모두 이 섹션이 있습니다.
SPEC.md를 작성하기 전에 반드시 거쳐야 하는 단계가 하나 있습니다. 내 앱이 어떤 유형인지 정하는 것. 같은 7가지 항목이라도 앱 유형에 따라 강조점이 완전히 달라집니다.
유형 1: B2C 앱 (소비자가 직접 사용)
피트니스·식단·습관·가계부·일기 같은 개인용 앱. 사용자가 곧 결제자입니다.
| 관점 | B2C 앱 SPEC.md 작성 시 |
|---|---|
| 성공 기준 | DAU · 재방문률 · 완주율 (예: "7일 연속 사용 30%") |
| 수익화 | 프리미엄 (₩4,900~9,900) / 광고 / 인앱결제 |
| Phase 1 핵심 | 온보딩 5분 이내 완료 + 첫 가치 제공 30초 안에 |
| 주의 | 무료 사용자 비중 95%+ 가능. 광고 모델 처음부터 고려 |
| 적합한 모델 | Sonnet 위주 (Opus는 알고리즘만) |
줍줍이 여기에 가까움 (개인 복지 탭). 다만 소상공인 탭은 B2B에 가까워서 "혼합형".
유형 2: B2B SaaS (기업이 사용)
CRM · 프로젝트관리 · HR · 회계 · 예약 시스템 같은 기업용 도구. 결제자는 기업이고, 사용자는 직원입니다.
| 관점 | B2B SaaS SPEC.md 작성 시 |
|---|---|
| 성공 기준 | 유료 기업 수 · MRR · 시트당 단가 |
| 수익화 | 월 구독 (₩30,000~₩300,000) / 시트당 가격 |
| Phase 1 핵심 | 조직 (Org) 단위 데이터 격리 + 관리자 권한 분리 (RBAC) |
| 주의 | tenant_id 컬럼 + RLS 처음부터. 나중에 추가 불가능에 가까움 |
| 적합한 모델 | Opus 비중 높음 (복잡한 권한·청구 로직) |
유형 3: 마켓플레이스 (양면 시장)
숙박 · 중고거래 · 재능 · 외주 · 강사 매칭 등. 가장 어려운 유형. 양쪽이 모두 있어야 가치가 생기는 "닭과 달걀" 문제입니다.
| 관점 | 마켓플레이스 SPEC.md 작성 시 |
|---|---|
| 성공 기준 | 공급자 (Supply) 수 + 수요자 (Demand) 수 + 거래 성사율 |
| 수익화 | 거래 수수료 (5~15%) / 광고 노출 |
| Phase 1 핵심 | 공급자 확보가 우선. 수요는 그 다음 |
| 주의 | "닭과 달걀" 문제. Phase 1에서 한쪽 사이드부터 집중 |
| 적합한 모델 | Sonnet + Opus (매칭 알고리즘) |
유형 4: 교육·학습 앱
언어 학습 · 수능 인강 · 코딩 부트캠프 · 자격증 앱. 콘텐츠와 학습 흐름이 핵심입니다.
| 관점 | 교육 앱 SPEC.md 작성 시 |
|---|---|
| 성공 기준 | 완강률 · 진도율 · 학습 시간 (예: 평균 30일 완강 60%) |
| 수익화 | 강의 단건 / 월 구독 / 라이브 수업 |
| Phase 1 핵심 | 콘텐츠 제공 + 진도 추적 + 동기 부여 (스트릭) |
| 주의 | 처음부터 콘텐츠 100개 만들지 말고 10개로 시작 |
| 적합한 모델 | Sonnet (콘텐츠 표시) + Haiku (퀴즈 생성) |
유형 5: 콘텐츠·미디어 앱
뉴스 · 블로그 · 매거진 · 뉴스레터 · 팟캐스트. 검색 노출이 생존을 좌우하는 유형입니다.
| 관점 | 콘텐츠 앱 SPEC.md 작성 시 |
|---|---|
| 성공 기준 | 구독자 수 · 이메일 오픈율 · 재방문률 |
| 수익화 | 유료 구독 · 후원 · 광고 · 스폰서십 |
| Phase 1 핵심 | 무료 콘텐츠 30%로 가치 증명 → 70% 유료 |
| 주의 | SEO 처음부터. 메타데이터 · sitemap · OG 태그 |
| 적합한 모델 | Sonnet + Haiku (요약 생성) |
TotalSportsView가 여기에 가까움. 다만 "AI 페르소나가 콘텐츠를 자동 생성"이라는 차별점 — E5 (콘텐츠 SSOT)가 새 11장에서 적용됩니다.
어떤 앱을 만들지 정해지지 않은 상태라면 가장 안전한 선택은 B2C 앱입니다. 이유: 사용자 1호가 자신이 될 수 있어 동기 부여가 강하고, Phase 1 검증이 빠르고, 진입 장벽이 낮습니다.
B2B SaaS는 영업력과 기업 네트워크가 필요하고, 마켓플레이스는 양쪽 모두를 모아야 해서 솔로 개발자에게 어렵습니다. Phase 1은 B2C로 시작하고, 검증되면 Phase 2~3에서 B2B 또는 마켓플레이스로 확장하는 것도 가능합니다.
SPEC.md는 반드시 Opus 모델로 작성합니다. SPEC 작성은 복잡한 비즈니스 로직과 장기 일관성이 필요한 작업입니다. Sonnet으로 시작하면 나중에 PLAN.md와 충돌이 생깁니다.
claude # Claude Code 실행 /model claude-opus-4-6 # Opus로 전환 (필수) /effort high # 고품질 출력
SPEC.md 파일을 작성해줘. 아래 정보를 기반으로 7가지 항목을 모두 채워줘: 앱 이름: [이름] 해결하는 문제: [한 문장] 사용자 A: [주 사용자 설명] 사용자 B: [부 사용자 설명] Phase 1 핵심 기능: [기능1 / 기능2 / 기능3 (최대 3가지)] 수익화: [방법 — 구독/거래수수료/프리미엄 중 선택] 기술 스택: [Expo/Next.js + Supabase + Stripe 등] 성공 기준은 반드시 숫자로 명시해줘. DB 스키마 초안도 포함해줘 (테이블 이름과 핵심 컬럼만). 파일 크기는 300줄 이하로 유지해줘.
cat SPEC.md # 7가지 항목이 모두 있는지 직접 확인 # 성공 기준에 숫자가 있는지 확인 # 수익화가 Phase 1에 포함됐는지 확인
SPEC v1 작성에서 가장 중요한 것: "v1을 완벽하게 만들려고 하지 말 것". 7항목이 모두 채워졌고 검토 가능한 형태가 되면 v1입니다. 누락이 있어도 됩니다 — 그게 5-4 외부 검토와 5-5 회색지대 결정에서 보완됩니다.
이 원칙은 표준 도구도 같습니다. GSD의 /gsd-new-project도 "질문 → 1차 답변 → 자동 보완" 흐름. Spec-Kit의 /speckit.specify도 "NEEDS CLARIFICATION" 명시적 누락 표시. 불완전을 두려워하지 않는 것이 SDD 사상의 공통 출발점입니다.
SPEC.md 초안이 완성되면 반드시 Gemini로 외부 검토를 받습니다. 이 단계를 건너뛰면 BUILD 중간에 설계가 틀렸다는 것을 발견하고 처음부터 다시 해야 하는 상황이 발생합니다.
이 단계는 새 1장에서 정의한 E3의 첫 번째 적용입니다. Claude가 만든 SPEC.md를 다른 회사 모델 (Gemini)이 검토 → 다른 사각지대로 빠진 것 발견.
두 번째 라운드는 새 8장 REVIEW에서 등장합니다. 그때 "Claude 시뮬레이션 검토 + 외부 Gemini" 두 검토자가 동시 작동하고, 12건 발견 패턴 (Claude만 4 + Gemini만 6 + 둘 다 2)이 데이터로 입증됩니다.
gemini.google.com에 접속해서 아래 프롬프트에 SPEC.md 내용을 붙여넣어 실행합니다.
아래 앱 Spec을 5가지 관점에서 검토해줘: 1. 보안: 악용할 수 있는 구멍이 있는가? 2. 수익화: Phase 1에서 실제로 돈을 받을 수 있는가? 3. 범위: 혼자 30일 안에 완성 가능한 규모인가? 4. 누락: 없으면 앱이 작동 안 되는 필수 기능이 빠진 게 없는가? 5. DB: N+1 쿼리나 보안 취약점이 생길 수 있는 설계가 있는가? [SPEC.md 내용 전체 붙여넣기]
Gemini 1차 검토에서 자주 발견되는 패턴 — 두 사례
| 프로젝트 | Gemini가 잡은 발견 | 종류 |
|---|---|---|
| 줍줍 | 통계 조작 가능 (한 사용자가 같은 지원금에 여러 번 "줍줍" 클릭) | 보안 |
| 줍줍 | LLM 분류 신뢰성 (confidence 임계값 부재) | DB 설계 |
| 줍줍 | 개인정보 수집 범위 불명확 (IDFA 처리 미명시) | 보안 |
| 줍줍 | Phase 1 수익 모델 부재 (0~6개월 무수익이 의도적인가 누락인가) | 수익화 |
| 줍줍 | 정부 API 호출 한도 (무한 호출 시 제한 있음) | 누락 |
| TSV | 법적 회색지대 명시 부재 (사행행위법 "조장" 두 요건) | 보안 (법적) |
| TSV | 페르소나 사실 환각 위험 (LLM이 통계를 추정) | DB 설계 |
| TSV | 다관점 가설 검증 미명시 (페르소나 4가 실재하는지) | 누락 |
| TSV | 외부 API 비용 폭주 가능 (Cloudflare WAF 부재) | 보안 |
| TSV | SEO 키워드 분리 부재 (cannibalization) | 누락 |
| TSV | 운영자 비상 정지 도구 부재 | 누락 |
v1이 일부러 불완전하게 작성됐기 때문입니다. 발견이 없다면 검토가 제대로 안 된 것이에요.
여기가 1탄 v2에서 추가된 자리입니다.
Gemini 검토 결과 중 일부는 단순 기술 누락이지만, 일부는 회색지대 결정입니다 — "이 사용자에게 어떻게 노출할 것인가, 단속에 어떻게 변호할 것인가, 표현을 어떻게 정제할 것인가". 이게 5확장 E1입니다.
법적 · 윤리적 · 시장적 "회색지대"에서 "안전하고 솔직한 자기 위치"를 명세적으로 정하는 작업.
9개 표준 도구 모두 이 영역을 "비즈니스 요구사항"으로 받지만, "법적 안전 위치를 명세적으로 결정"하는 프레임을 제공하지 않습니다. 사용자에게 떠넘깁니다.
5파일+의 SPEC.md는 이 영역을 본문에 명시적으로 흡수합니다.
E1의 4단계 결정 프레임
| 단계 | 내용 | 시간 |
|---|---|---|
| ① 영역 식별 | 회색지대가 어디인지 (법적 · 윤리적 · 시장적) | 30분 |
| ② 포함 / 배제 결정 | "이건 포용한다" + "이건 명확히 배제한다" | 1시간 |
| ③ 표현 정제 | 외부 노출 텍스트 작성 (About 페이지·약관·콘텐츠 정책) | 1시간 |
| ④ SPEC 명시 | SPEC.md "§ 회색지대 결정" 섹션에 박음 | 30분 |
총 약 3시간. 이 작업이 6개월 후 "단속 시 변호 논리"와 "동업자가 펼쳤을 때 왜 이 결정인지 답"이 됩니다.
사례 1 — 줍줍의 회색지대 두 가지
(a) "줍줍" 표현의 정직한 위치
## ⚖️ 회색지대 결정 — "줍줍" 표현의 정직한 위치 문제: "줍줍"은 "공짜로 줍는다"는 뉘앙스. 정부 지원금 공식 신청 절차와 거리가 있어 단속 또는 사용자 항의 발생 가능. 본 SPEC의 결정: - 본 서비스가 약속하는 것: 정보 격차를 줄인다 - 본 서비스가 약속하지 않는 것: 무조건 받게 해준다, 신청 보장 [표현 정제 규칙] - 브랜드명: "줍줍" 그대로 (사용자 친근감) - 본문 표현: "신청·수혜" 일관 사용 (공식 절차 인지) - About 페이지: 위 결정의 정직한 노출 - 약관: "본 서비스는 정보 제공을 목적으로 하며, 신청 결과를 보장하지 않습니다" 명시 [변호 논리] "줍줍은 정부 공식 정보를 정리하고 사용자 후기를 공유하는 미디어이며, 신청 결과를 보장하거나 대행하지 않는다."
(b) 개인정보 처리 위치
## ⚖️ 회색지대 결정 — 개인정보 최소 수집 정체성 문제: 정부 지원금 앱은 사용자의 민감 정보 (소득·가구 형태· 업종·매출) 가 가까이 있음. 어디까지 수집할 것인가. 본 SPEC의 결정: - IDFA (광고 식별자): 미수집 → 애플 심사 통과 가속 - 익명 닉네임 자동 부여: 실명 노출 차단 - 카카오 로그인만: 추가 개인정보 최소화 - 소득·가구 정보: 사용자가 자발적 입력하는 "필터"만 수집, 외부 노출 없음 - 개인정보 판매 없음: 수익 모델에서 명시적 제외 [변호 논리] "줍줍은 PIPA (개인정보 보호법) 의 최소 수집 원칙을 적극 준수 하며, IDFA 같은 추적 식별자를 수집하지 않는다."
사례 2 — TotalSportsView의 Position C
## ⚖️ 회색지대 결정 — Position C 채택의 법적 근거 한국 사행행위 등 규제 및 처벌 특례법은 "도박을 조장하는 행위" 를 처벌한다. "조장"의 핵심 요건: ① 인지 — 도박 목적임을 알고 ② 설계 — 도박을 돕도록 의도적으로 만들었다 본 SPEC은 이 두 요건이 동시 성립하지 않는 포지션을 명시적으로 채택한다 (Position C — 솔직한 중립): > "TotalSportsView는 스포츠 분석 미디어다. 콘텐츠를 누가 어떻게 > 사용하는지 묻지 않는다. 다만 베팅 사이트로 연결하지 않고, > 베팅을 권유하는 콘텐츠를 만들지 않는다." [포함 5개] - 합법 스포츠토토 (정부 발행) 사용자 분석 정보 - 판타지 리그 사용자 - 데이터 마니아 (xG · 점유율 · 슈팅 수치) - 통계 분석 학습 콘텐츠 - 경기 미리보기 + 다관점 큐레이션 [명확한 배제 4개] - 베팅 사이트로의 직접 연결 (외부 URL 금지) - 배당률 → 한국식 배당으로 변환 표시 - 픽 (선택) 추천 형식 (예: "오늘의 픽") - 도박 관련 검색 키워드 SEO [변호 논리] "분석 콘텐츠 제공이 목적이며, 도박 조장 의도와 설계가 없었다" 가 사실로 성립.
두 사례의 공통 패턴
| 영역 | 줍줍 | TSV |
|---|---|---|
| 회색지대 종류 | 표현 (마케팅 vs 공식 절차) + 개인정보 (PIPA) | 법적 (사행행위법 "조장") |
| 포함 / 배제 | 정보 격차 줄임 (포함) / 신청 보장 안 함 (배제) | 분석 정보 (포함) / 베팅 직접 연결 (배제) |
| 외부 노출 위치 | About + 약관 + 콘텐츠 정책 | About + 콘텐츠 상단 면책 + Footer |
| 변호 논리 | "정보 제공 목적, 결과 보장 없음" | "분석 미디어, 도박 조장 의도·설계 없음" |
GSD의 /gsd-secure-phase가 "보안 강화" 영역을 다루지만, "법적 회색지대 변호 논리 명세화"까지는 다루지 않습니다. Spec-Kit의 /speckit.constitution이 "architectural rules" 위주이고 비즈니스 위치 결정은 사용자 책임. 5파일+의 E1은 표준 도구 모두 미점유 영역을 본문에 박는 것이 본질입니다.
Gemini 검토 결과와 회색지대 결정을 SPEC.md에 반영하고 v2로 저장합니다. 단순 수정이면 Sonnet으로 전환해도 됩니다.
# Gemini가 지적한 문제 + E1 회색지대 결정을 Claude Code에서 반영 /model claude-sonnet-4-6 # 수정 작업은 Sonnet으로도 충분 SPEC.md를 아래 내용으로 수정해줘: 1. [Gemini 발견 1번 반영] 2. [Gemini 발견 2번 반영] ... 5. (또는 6.) "§ 회색지대 결정" 섹션 추가: - 영역 식별: [법적/윤리적/시장적 중 어느 것] - 포함 / 배제: [구체 항목] - 표현 정제: [외부 노출 텍스트] - 변호 논리: [한 줄] # 수정 완료 후 파일 확인 cat SPEC.md | head -50 # SPEC.md v2 완성 → git commit git add SPEC.md git commit -m "SPEC.md v2: Gemini 검토 반영 + E1 회색지대 결정"
SPEC.md v2 완성 체크리스트
- ☐ 앱 이름이 있다
- ☐ 해결하는 문제가 한 문장으로 있다
- ☐ 사용자 A · B가 구분돼 있다
- ☐ Phase 1 기능이 3가지 이하다
- ☐ 성공 기준이 숫자로 있다 (예: 가입자 50명)
- ☐ 수익화 방법이 Phase 1에 포함돼 있다
- ☐ DB 스키마 초안이 있다
- ☐ ⭐ § 회색지대 결정 섹션이 있다 (해당 시)
마지막 ⭐ 항목은 회색지대가 있는 프로젝트만 해당합니다. 명백한 "비기술 비즈니스 결정"이 없는 프로젝트 (예: 단순 가계부 앱)는 이 섹션 없이 v2를 마무리할 수 있습니다. 하나라도 빠지면 SPEC.md를 먼저 보완하세요.
- 1️⃣ SPEC.md = 앱의 헌법: 7항목 (이름·문제·사용자·기능·성공기준·수익화·기술스택) + E1 회색지대 결정
- 2️⃣ 작성 순서: Opus + /effort high → SPEC v1 → Gemini 검토 (5~6건 발견) → E1 회색지대 결정 (3시간) → SPEC v2 → git commit
- 3️⃣ 5가지 앱 유형: B2C / B2B SaaS / 마켓플레이스 / 교육 / 콘텐츠 — 유형별 성공 기준·수익화·모델이 다릅니다
- 4️⃣ E1 4단계 프레임: ① 영역 식별 → ② 포함/배제 → ③ 표현 정제 → ④ SPEC 명시
- 5️⃣ 두 사례: 줍줍 (표현 정제 + IDFA 미수집) / TSV (Position C — 사행행위법 두 요건 회피)
SPEC.md는 "무엇을 만들 것인가" + "법적·윤리적 회색지대를 어떻게 항해할 것인가"가 한 파일에 박힌 앱의 헌법입니다.