md 명세로 Claude에게 앱 맡기기
Claude에게 "쇼핑 앱 만들어 줘"라고만 하면 Claude는 화면 수, 버튼이 어디로 가는지, 배송 방법을 고르면 무엇이 바뀌는지를 추측해야 합니다. 추측이 많을수록 다시 고치는 일도 늘어납니다. 이 글은 ScreenPath에서 화면과 화면 사이의 길을 먼저 설계하고, 그 설계를 md 명세 한 파일로 Claude에게 넘기는 방법을 정리합니다.
왜 명세가 먼저인가
앱을 코드로 옮길 때 가장 자주 틀리는 것은 생김새가 아니라 흐름입니다.
- 로그인 버튼은 성공하면 어디로, 실패하면 어디로 가는가
- 셀렉터에서 "택배"를 고를 때와 "픽업"을 고를 때 다음 화면이 다른가
- 뒤로가기는 직전 화면인가, 홈인가
- 목록이 비었을 때, 불러오는 중일 때, 오류일 때 화면은 어떻게 보이는가
ScreenPath는 이것을 지도 위의 선과 화면 상태로 직접 그립니다. 그래서 내보낸 명세에는 "느낌"이 아니라 정해진 사실이 들어갑니다.
ScreenPath에서 설계하기
- 지도에 화면 놓기 — 화면 카드를 메뉴 묶음(예: 공통·쇼핑·주문)에 배치합니다. 예시 프로젝트로 시작해도 됩니다.
- 부품으로 화면 만들기 — 버튼·셀렉터·입력칸·목록·탭·모달 등 15종 부품을 놓습니다. 프로젝트의 디자인 규칙(색·글꼴·모서리·여백)이 자동으로 입혀집니다.
- 길 잇기 — 버튼에서 다음 화면으로 선을 잇습니다. 셀렉터는 값마다 갈 곳을 정할 수 있고, 지도에는 조건 선이 점선으로 나타납니다.
- 상태와 모션 — 화면마다 기본·빈 화면·로딩·오류 상태를 만들고, 화면 전환과 화면 안 반응에 모션 프리셋을 고릅니다.
- 재생으로 확인 — 재생 화면에서 직접 눌러 보며 길이 끊긴 곳이 없는지 봅니다.
md 명세에 들어가는 것
내보내기는 screenpath.export/1이라는 고정 형식을 따릅니다. 절 제목과 표 머리가 바뀌지 않고, 같은 프로젝트를 다시 내보내면 바이트까지 같은 글이 나옵니다. 그래서 Claude가 매번 같은 방식으로 읽을 수 있고, 바뀐 부분을 비교하기도 쉽습니다.
| 절 | 내용 |
|---|---|
| 디자인 규칙 | 색·글꼴·둥글기·그림자·여백·모션 토큰, 웹 CSS 변수, Tailwind 테마, 네이티브 JSON 토큰 |
| 메뉴 구조·흐름도 | 묶음과 화면 목록, Mermaid 흐름도 |
| 액션 표 | 어떤 부품을 누르면 어디로 가는지, 조건과 전환 |
| 셀렉터·변수 | 선택지와 기본값, 변수와 조건 |
| 화면별 명세 | 부품 배치, 상태, 액션, 계산된 픽셀 상자 |
| 부록 | 아직 해결되지 않은 댓글 |
프로젝트 전체뿐 아니라 묶음 하나, 화면 하나만 내보낼 수도 있습니다.
Claude에게 넘기기
내려받은 md 파일을 Claude 대화나 Claude Code 작업 폴더에 넣고, 이렇게 요청해 보세요.
이 설계서의 화면과 액션 표를 그대로 구현해 줘. 디자인 규칙 절의 토큰을 테마로 쓰고, 액션 표에 없는 이동은 만들지 마.
명세가 길을 정해 두었기 때문에 Claude는 "어디로 가야 하지?"를 추측하는 대신 표를 따라 구현합니다. 설계를 고쳤다면 다시 내보내 이전 파일과 비교하면 무엇이 바뀌었는지 바로 보입니다.
파일 대신 연결하고 싶다면
파일을 주고받는 대신 Claude를 ScreenPath에 MCP로 연결하면 Claude가 프로젝트를 직접 읽고, 필요하면 설계도 함께 고칩니다. 이어지는 글 MCP로 Claude와 화면 설계하기에서 다룹니다.