Make Product Spec

• 한국어: README.md
• English: README.en.md
• Install guide: INSTALL.md · INSTALL.en.md

make-product-spec은 아이디어를 개발자가 바로 바이브코딩을 시작할 수 있는 수준의 기획/디자인 문서로 정리해 주는 CLI입니다.

개발을 대신하는 도구가 아니라, 개발 전에 기획자와 디자이너가 해야 할 질문과 정리를 Claude 또는 Codex 안에서 대신 진행하게 해 주는 도구입니다.

Who This Is For

• 개발 전에 기획 문서를 제대로 닫고 싶은 팀
• Claude 또는 Codex에서 같은 product spec surface를 쓰고 싶은 팀
• PRD, UX-IA, screen spec, design까지를 개발 가능한 최종 spec으로 정리하고 싶은 팀
• 아이디어는 있지만 어떤 기능, 화면, 디자인 방향으로 시작해야 할지 아직 흐릿한 사람

처음 보는 사람을 위한 설명

사용자는 처음에 만들고 싶은 것만 말하면 됩니다.

예:

동네 빵집을 지도에서 찾고, 사람들이 직접 빵집을 제보할 수 있는 앱을 만들고 싶어.

그러면 Claude 또는 Codex가 기획자/디자이너처럼 먼저 추론안을 만들고, 꼭 필요한 결정만 단계별로 질문합니다. 사용자는 선택지를 고르거나, 마음에 들지 않는 부분을 직접 고쳐서 답하면 됩니다.

결과적으로 아래를 정리합니다.

• 누구를 위한 제품인지
• 어떤 문제를 풀려는지
• 지금 사용자가 쓰는 대안은 무엇인지
• 경쟁 서비스와 차별점은 무엇인지
• 첫 버전에 어떤 기능을 넣을지
• 기능을 어떤 UX 흐름과 화면으로 제공할지
• 어떤 디자인 레퍼런스를 참고할지
• Stitch 또는 vibe design에 넘길 디자인 방향은 무엇인지
• 최종적으로 개발자가 구현을 시작할 수 있는 문서는 무엇인지

사용 흐름

설치 후 Claude 또는 Codex에서 이렇게 시작하면 됩니다.

make-product-spec 시작해줘.
내 아이디어는 [여기에 아이디어 입력].
기획부터 디자인까지 단계별로 도와줘.

더 짧게 시작해도 됩니다.

product spec 만들어줘. 아이디어는 [아이디어].

기본 흐름은 아래처럼 진행됩니다.

1. 아이디어와 문제 정리
   • 만들고 싶은 것, 해결하려는 문제, 첫 사용자군을 러프하게 잡습니다.
2. 문제/시장/사용자 확인
   • 무거운 시장 검증이 아니라, 빠르게 만들어보기 전에 과신을 막는 수준으로 확인합니다.
3. 경쟁 서비스 분석
   • 비슷한 서비스, 사용자가 지금 쓰는 대안, 차별화 포인트를 정리합니다.
4. 서비스 콘셉트 정의
   • 이 서비스가 누구에게 어떤 가치를 주는지 한 문장으로 정리합니다.
5. MVP 기능 정의와 상세 설계
   • 첫 버전에 제공할 기능과 기능별 동작을 정리합니다.
6. UX 흐름과 와이어프레임
   • 기능을 사용자가 어떤 화면과 흐름으로 쓰게 될지 정리합니다.
7. 디자인 레퍼런스 조사
   • 비슷한 유형의 좋은 제품/페이지를 찾아 디자인 판단 자료로 만듭니다.
8. 디자인 방향과 생성 준비
   • DESIGN.md, Stitch prompt, 또는 vibe design 지시사항으로 정리합니다.
9. 디자인 리뷰와 최종 정리
   • 디자인 결과가 보기 좋고, UX가 편하고, 처음 기획 의도를 유지하는지 점검합니다.

각 단계 끝에서는 독립 평가 agent가 최소 조건을 확인합니다. PASS면 다음 단계로 가고, NO-PASS면 부족한 부분만 보완합니다. 질문은 많을수록 좋은 방식이 아닙니다. 내부 checklist는 agent가 먼저 추론하고, 사용자에게는 제품 방향을 바꾸는 blocker decision만 선택지로 보여주는 흐름을 기본으로 합니다.

중단 후 다시 시작하기

작업이 중간에 끊겼거나, 며칠 뒤 다시 이어서 하고 싶으면 프로젝트 루트에서 상태를 확인합니다.

make-product-spec status

이 명령은 PLANNING-RECORD.md와 주요 산출물 파일을 보고 현재 추정 상태, 다음 step, 이어서 시작할 때 쓸 프롬프트를 JSON으로 보여줍니다.

특정 host 기준으로 확인하려면:

make-product-spec status --host codex --scope local

주의할 점:

• status는 재개 위치를 추정하는 명령입니다. 품질 PASS 판정은 각 step의 평가 agent가 따로 합니다.
• 파일이 있어도 내용이 덜 끝났다면, 다음 step으로 넘기기 전에 해당 step 평가를 다시 돌리는 게 맞습니다.
• Claude에서 하다가 Codex로 바꿔도 같은 프로젝트 산출물을 읽고 이어갈 수 있습니다.

Install

npm install -g @ikseongjo/make-product-spec

make-product-spec install --host codex --scope local

make-product-spec install --host claude --scope local

권장 기본 경로:

• npm install -g ...
  • CLI 명령어를 전역 설치
• make-product-spec install --scope local
  • 실제 product-spec surface는 현재 프로젝트에만 설치
• --scope global
  • 여러 프로젝트에서 같은 surface를 공용으로 재사용할 때만 쓰는 advanced path

먼저 미리 보기만 하려면:

make-product-spec install --host codex --scope local --dry-run

Update Existing Project Install

이미 설치한 project surface를 최신 버전으로 올리려면:

npm install -g @ikseongjo/make-product-spec@latest

그 다음 기존에 설치했던 같은 host/scope/pack 조합으로 --force 재설치합니다.

make-product-spec install --host codex --scope local --force

확인:

make-product-spec doctor --host codex --scope local

주의:

• local install을 업데이트할 때는 각 프로젝트 루트에서 다시 실행합니다
• claude, global, planning을 쓰고 있었다면 같은 조합으로 다시 설치해야 합니다
• 기존 managed file을 교체하므로 필요한 로컬 수정이 있으면 먼저 백업해야 합니다

What Gets Created

기본 설치는 prebuild pack입니다. 설치 후 아래 루트가 생깁니다.

• Codex: .codex/product-spec/
• Claude: .claude/product-spec/

같이 설치되는 것:

• curated references/
• archetype별 actual page reference library
• templates/
• host-visible skills/
• host-visible agents/

기본적으로 아래 최종 spec 문서를 만들기 위한 surface입니다.

• PROJECT-THESIS.md
• PLANNING-RECORD.md
• RESEARCH.md
• PRD.md
• UX-IA.md
• SCREEN-SPECS.md
• BUSINESS-OPS.md
• EXECUTION-HANDOFF.md
• UX-PATTERN-SCAN.md
• WIREFRAME-DRAFT.md
• REFERENCE-BRIEF.md
• DESIGN.md

필요하면 아래 optional internal extension 문서까지 쓸 수 있지만, 기본 prebuild PASS에 필수는 아닙니다.

• ARCHITECTURE.md
• STATE-PERMISSIONS.md
• DATA-TRUTH.md
• INTEGRATIONS.md
• NON-FUNCTIONAL.md

Recommended Working Rhythm

npm으로 설치한 사용자 기준 기본 진행은 문서 하나씩이 아니라 큰 step 단위입니다. 사용자는 매 순간 모든 문서를 직접 알 필요가 없습니다. Claude/Codex가 필요한 문서를 읽고, 질문하고, 작성하고, 평가합니다.

1. Planning 1: 아이디어와 문제 정리
2. Planning 2: 문제/시장/사용자 확인
3. Planning 3: 경쟁 서비스 분석
4. Planning 4: 서비스 콘셉트 정의
5. Planning 5: MVP 기능 정의와 상세 설계
6. Planning 6: UX 흐름과 와이어프레임
7. Design 1: 디자인 레퍼런스 조사
8. Design 2: 디자인 방향과 화면 정리
9. Design 3: Stitch 또는 vibe design 준비
10. Design 4: 디자인 리뷰와 최종 정리

각 step 안에서는 agent가 먼저 자료를 읽고, 필요하면 외부 reference를 모으고, 초안을 만들고, 셀프 평가 후 정리합니다. 사용자에게는 step 시작과 step 종료에서만 읽기 쉬운 STATUS BLOCK을 보여주고, 가능하면 Claude/Codex의 선택지 UI로 확인을 받습니다. 선택지 UI를 쓸 수 없는 환경에서는 번호 붙은 질문으로 대체합니다.

중요한 방향:

• Step 2는 시장 검증을 완전히 끝내는 단계가 아닙니다. 빠르게 만들어보기 전에 가장 위험한 가정을 가볍게 확인하는 단계입니다.
• 와이어프레임은 미려한 목업이 아니라 기능과 흐름을 확인하기 위한 초안입니다.
• 실제 시각 디자인은 Stitch 또는 vibe design 결과를 보고 Step 9에서 다시 평가합니다.
• 최종 목적은 예쁜 문서가 아니라, 개발자가 바로 구현을 시작할 수 있는 기획/디자인 spec입니다.

canonical guide:

• product-spec/prebuild/references/BIG-STEP-WORKFLOW.md
• product-spec/prebuild/references/PRODUCT-DESIGN-STEP-MAP.md
• product-spec/prebuild/references/STATUS-BLOCK-RULE.md
• product-spec/prebuild/references/START-HERE.md

Playwright MCP를 한 번 연결하려면:

make-product-spec setup-playwright-mcp

local install로 .codex/ 또는 .claude/가 하나만 있으면 host를 자동 감지합니다. 자동 감지가 안 되면 --host codex 또는 --host claude를 붙이면 됩니다.

mockup preview를 localhost로 띄우려면:

make-product-spec preview-serve

그다음 브라우저와 Playwright MCP로 http://127.0.0.1:4173을 열어 review하면 됩니다.

Pack Difference

• prebuild
  • 기본값
  • planning과 design을 묶은 final spec surface
  • 필요하면 optional architecture reference를 같이 읽을 수 있음
• planning
  • 더 작은 compatibility path
  • planning-only surface가 필요할 때만 사용

예:

make-product-spec install --host codex --scope local --pack planning

Supported Values

• --host: codex, claude
• --scope: local, global
• --pack: prebuild, planning

잘못된 값을 넣으면 CLI가 즉시 에러를 냅니다.

대부분의 사용자는 --scope local이면 충분합니다. --scope global은 여러 프로젝트에서 같은 surface를 공유하려는 경우에만 권장합니다.

What It Does Not Ship

아래 내부 검증 산출물은 설치되지 않습니다.

• loop log
• scenario matrix
• internal fixtures
• worked examples
• internal review artifacts
• implemented frontend UI audit surface

Docs

• install details: INSTALL.md
• shipped surface: product-spec/SHIPPING-SURFACE.md
• host-aware install rules: product-spec/HOST-AWARE-INSTALL-SURFACE.md
• pack registry: product-spec/PACK-REGISTRY.md

Repo Workspace Surface

이 저장소 자체를 Codex workspace로 열 때는 아래 로컬 surface를 씁니다.

• root AGENTS.md
• Codex supplement .codex/AGENTS.md
• project config .codex/config.toml