Don't Panic
in Claude ☕ 6분 읽기

[Claude] Claude 시대의 제품 명세 문서 — 화면흐름도·기능명세·와이어프레임·ERD·API

#Claude#Claude Code
목차

📚 Claude Code 정리 노트 (2026-07) — 4부작

  1. 제품 명세 문서 ← 지금 읽는 글 2. 멀티 에이전트와 Ralph 3. 자율 연구·개발 자동화 4. 브라우저 자동화

들어가며 — AI 에이전트 시대, 사람은 무엇을 할 것인가?

AI가 코드를 대신 짜주는 시대가 되면서 자연스럽게 드는 질문: 그럼 사람은 이제 뭘 하나?

답은 대체로 한 방향으로 수렴한다 — 사람의 일은 “코드를 손으로 치는 것”에서 무엇을·어떻게 만들지 명세하고, 여러 AI를 조율하는 것으로 옮겨간다. 이번 노트는 그 두 축을 다룬다.

축질문이번 노트에서
A. 제품 문서”무엇을 만들 것인가”를 어떻게 정확히 적을 것인가1~7번
B. 멀티 에이전트 오케스트레이션”어떻게 여러 AI를 굴려 그것을 만들게 할 것인가”8~17번

🔗 이 두 축은 이전 노트의 SDD(2026-06-27 노트 2번) — “명세가 먼저, 코드는 명세에서 파생” — 를 실무 문서(A)와 실행 방식(B)으로 구체화한 것에 가깝다.

1. 화면 흐름도 (User Flow / Screen Flow)

화면과 화면 사이의 이동·분기를 그린 다이어그램. 코드도 디자인도 아니고, “사용자가 어디서 어디로 가는지”만 다룬다.

개념 한 줄

“이 화면 다음엔 뭐가 나오는가”를 박스와 화살표로 미리 정하는 지도.

담는 내용

항목예시
화면(노드)로그인, 홈, 상세, 결제
전환(엣지)버튼 클릭, 폼 제출, 뒤로가기
분기로그인 성공/실패, 권한 있음/없음
진입·이탈점앱 시작 지점, 외부 링크로 들어오는 지점

왜 필요한가 (AI 시대 맥락)

막연히 “쇼핑몰 만들어줘”라고 하면 AI는 화면 개수·이동 경로를 임의로 정해버린다. 화면 흐름도로 경로를 먼저 확정해두면 AI가 추측할 여지가 줄어든다 — 이전 노트의 goal drift(2026-06-27 노트 2번 배경)를 화면 구조 단계에서 미리 막는 것.

한 줄 요약: 화면 흐름도 = “사용자가 화면 사이를 어떻게 이동하는가”를 코드 짜기 전에 확정하는 지도. 이후 나올 기능 명세·와이어프레임의 뼈대가 된다.

2. 기능 명세서 (Functional Specification)

각 화면·기능이 무엇을 하는지를 서술한 문서. “어떻게 구현하는지(기술 설계)“는 다루지 않는다.

개념 한 줄

“이 버튼을 누르면 무슨 일이 일어나야 하는가”를 빠짐없이 적은 문서.

담는 내용

항목내용
기능 ID·이름FR-01: 회원가입
입력/출력입력: 이메일·비밀번호 / 출력: 계정 생성, 인증 메일 발송
검증 규칙이메일 형식, 비밀번호 길이·중복 체크
예외·엣지케이스이미 가입된 이메일일 때 동작
연관 화면1번 화면 흐름도의 어느 화면과 연결되는지

PRD와 뭐가 다른가

구분PRD(2026-06-27 노트 4번)기능 명세서
관점왜·무엇을·누구를 위해 (상위)각 기능이 정확히 무엇을 하는지 (하위)
상세도서술형, 목표·시나리오 중심기능 단위로 조각내 입출력·규칙까지

실무 흐름: PRD(상위 목표) → 기능 명세서(기능 단위 상세) → 와이어프레임/설계.

한 줄 요약: 기능 명세서 = “무엇을 하는가”를 기능 단위로 쪼개 입력·출력·규칙·예외까지 적은 문서. PRD보다 한 단계 더 구체적.

3. 와이어프레임 (Wireframe) — Low-Fi / High-Fi

화면의 레이아웃(무엇이 어디에 있는가)을 그린 시안. 색·폰트 같은 최종 디자인이 아니라 구조에 집중.

충실도(fidelity)에 따른 구분

구분Low-Fi (저충실도)High-Fi (고충실도)
표현 수준박스·회색조·자리표시(placeholder) 텍스트실제 색·타이포·컴포넌트에 가까움
목적레이아웃·정보 구조 합의최종 룩앤필 검증, 클릭 가능한 프로토타입
제작 비용낮음, 빠르게 여러 안 시도높음, 수정 비용 큼
적합 시점초기 아이디어 확정 단계개발 직전, 디자인 승인 단계

왜 순서가 중요한가

Low-Fi로 구조를 먼저 합의하지 않고 바로 High-Fi(또는 실제 코드)로 가면, 나중에 레이아웃이 잘못됐을 때 디자인·코드를 통째로 다시 만들어야 한다. 저비용 단계에서 먼저 걸러내는 게 핵심.

AI 시대 맥락

  • Low-Fi: AI에게 “이 화면 레이아웃 후보 3개 보여줘” 요청 → 2026-06-27 노트 11번 Visual Companion이 정확히 이 역할(코드 전에 브라우저로 시안 비교)
  • High-Fi: 실제 색·컴포넌트까지 가려면 DESIGN.md(2026-06-27 노트 19번, 디자인 토큰 명세)를 참조시켜야 AI가 일관되게 만듦
  • 캔버스에서 그려 바로 코드로 뽑는 도구로는 Pencil.dev(2026-06-27 노트 18번) 사례가 있음

한 줄 요약: 와이어프레임 = 레이아웃 시안. Low-Fi(박스 수준, 구조 합의용) → High-Fi(실제 색·컴포넌트, 승인용) 순으로 충실도를 높여가며 재작업 비용을 줄인다.

4. 권한 정책 (Permission / Authorization Policy)

누가 무엇에 접근·조작할 수 있는가를 정의한 문서. 흔히 역할 기반 접근 제어(RBAC, Role-Based Access Control) 형태로 정리.

개념 한 줄

역할(role) × 자원(resource) × 행동(action) 조합으로 접근 가능 여부를 표로 못 박은 것.

예시 표 (권한 매트릭스)

역할 \ 자원·행동게시글 조회게시글 작성게시글 삭제회원 관리
일반 사용자OO본인 글만X
운영자OOOX
관리자OOOO

왜 앞단에서 정해야 하는가

권한 정책이 없으면 AI가 “일단 다 열어두거나” “일단 다 막아버리는” 식으로 임의 판단한다. 특히 삭제·결제·개인정보 같은 민감 기능은 권한 누락이 곧 보안 사고로 이어짐 — 이전 노트의 **권한 모드(Permission Modes, 2026-06-27 노트 7번)**가 “AI 실행 권한”을 다루는 것과는 결이 다른, 애플리케이션 자체의 사용자 권한 개념임에 주의.

한 줄 요약: 권한 정책 = 역할별로 무엇을 할 수 있고 없는지를 명세한 문서. ERD의 사용자·역할 테이블, API 명세서의 인가(authorization) 규칙과 직접 연결된다.

5. ERD (Entity-Relationship Diagram, 개체-관계도)

데이터가 무엇으로 이루어져 있고 서로 어떻게 연결되는지를 그린 다이어그램. DB 설계의 기본 뼈대.

개념 한 줄

이 서비스가 다루는 데이터 개체들과, 그것들 사이의 관계를 도식화한 것.

구성 요소

요소설명예시
엔티티(Entity)데이터 개체(=대략 테이블)User, Order, Product
속성(Attribute)엔티티가 가진 값User.email, Order.created_at
관계(Relationship)엔티티 간 연결과 다중성User 1 : N Order
키(Key)식별자·참조User.id (PK), Order.user_id (FK)

왜 API 명세서보다 먼저인가

API는 결국 데이터를 주고받는 창구다. 데이터 모델(ERD)이 흔들리면 API 스펙도 계속 바뀐다. 순서상 ERD → API 명세서가 자연스러운 이유.

한 줄 요약: ERD = 데이터의 뼈대. 권한 정책의 “역할·사용자” 테이블, API 명세서의 요청·응답 구조가 모두 여기서 파생된다.

6. API 명세서 (API Specification)

프론트엔드와 백엔드(혹은 서비스 간)가 주고받는 요청·응답의 계약서. 흔히 OpenAPI(Swagger) 같은 형식으로 작성.

개념 한 줄

“이 엔드포인트를 이렇게 부르면 이런 응답이 온다”를 정확히 약속한 문서.

담는 내용

항목예시
엔드포인트POST /api/orders
요청 스키마{ userId, productId, quantity }
응답 스키마{ orderId, status, createdAt }
상태 코드200(성공), 400(잘못된 요청), 401(미인증), 403(권한없음)
인증/인가 요구사항로그인 필요 여부, 필요한 역할(4번 권한 정책과 연결)

AI 시대 맥락

API 명세서는 사람과 사람 사이의 계약을 넘어, 이제 AI가 프론트/백엔드 코드를 각각 생성할 때 기준으로 삼는 명세가 된다. 명세가 명확하면 서로 다른 세션·에이전트가 만든 프론트/백엔드도 어긋나지 않고 맞물린다.

한 줄 요약: API 명세서 = 요청·응답의 계약. ERD(데이터)와 권한 정책(접근 규칙)을 실제 호출 가능한 인터페이스로 구체화한 최종 산출물.

7. 제품 문서들의 흐름 — 아이디어에서 API까지

1~6번 문서가 어떤 순서·관계로 이어지는지 한 번에 정리.

흐름도

막연한 아이디어
     │
     ▼
① 화면 흐름도(User Flow)        — 화면 간 이동 구조 확정
     │
     ▼
② 기능 명세서(Functional Spec)  — 각 화면·기능이 "무엇을" 하는지
     │
     ▼
③ 와이어프레임(Low-Fi → High-Fi) — 화면을 "어떻게 보여줄지" 레이아웃→룩앤필
     │
     ├──▶ ④ 권한 정책(Permission)   ─┐
     │                                 ├─▶ ⑥ API 명세서 — 최종 계약
     └──▶ ⑤ ERD(데이터 모델)       ─┘
     │
     ▼
구현(코드) — 사람 또는 AI 에이전트가 작성

SDD·이전 노트 개념과의 연결

SDD 단계(2026-06-27 노트 2번)대응하는 제품 문서
Specify (무엇을·왜)PRD(4번, 6/27 노트) + 화면 흐름도(1) + 기능 명세서(2)
Plan (어떻게, 기술 결정)ERD(5) + API 명세서(6) + 권한 정책(4)
(디자인 계층)와이어프레임(3) + DESIGN.md(6/27 노트 19번)
Tasks / Implement위 문서들을 근거로 AI/사람이 구현
  • planner·deep-interview(6/27 노트 13·16번)는 질문을 통해 이 문서들의 초안을 뽑아내는 도구
  • 즉, 1~6번 문서 전체가 SDD의 “명세(spec)” 산출물을 화면·데이터·API 관점으로 구체화한 것

한 줄 요약: 아이디어 → 화면 흐름 → 기능 명세 → 와이어프레임 → (권한 정책 + ERD) → API 명세 순으로 구체화하며, 이 전체가 SDD의 Specify/Plan 단계를 실제 문서로 채운 것이다.

관련 글