트랙 A — 새 앱을 처음부터 만들기
코딩을 몰라도 됩니다. 문장을 복사해서 AI에게 붙여넣는 것이 전부입니다.
- 위에서부터 순서대로, 한 단계씩만 하세요.
- 각 단계의 파란 박스를 [복사] → AI 대화창에 붙여넣기 → 엔터.
- 초록 박스(✅ 이렇게 나오면 성공)를 확인한 뒤에 다음 단계로. 확인 안 하고 넘어가면 세 단계 뒤에 원인을 못 찾습니다.
- 박스 안 노란 [대괄호] 부분은 지우고 본인 앱에 맞게 바꿔 넣으세요.
이 길이 맞나요?
30초잘못된 트랙으로 가면 처음부터 다시 해야 합니다. 30초만 확인하고 갑니다.
| 지금 상황 | 갈 곳 |
|---|---|
| 아직 아무것도 없다 / 새로 만든다 | 트랙 A — 이 페이지 |
| 이미 돌아가는 앱이 있다 | 트랙 B로 가세요 |
| 화면 디자인을 Google Stitch로 먼저 뽑았다 | 트랙 A로 진행하되 STEP 4에서 (B) 선택 |
스타터 킷 받기★
5분토큰(= 회사 색·글꼴·간격의 값 이름표)이 이미 연결된 빈 프로젝트를 받습니다. 직접 세팅하면 사람마다 조금씩 달라지고, 그 차이가 나중에 전부 문제가 됩니다.
| 어느 것을 받나 | 언제 |
|---|---|
| 순수 HTML 킷 | 잘 모르겠으면 이것. 설치 없이 파일을 더블클릭하면 브라우저에서 열립니다 |
| Next.js 킷 | 나중에 로그인·데이터베이스를 붙일 계획이면 |
압축을 풀고 폴더 전체를 쓰고 계신 AI 도구에서 열기.
- 폴더 안에
index.html(또는app/)과 AGENTS.md가 보인다 - HTML 킷이면
index.html을 더블클릭 → 브라우저에 표·버튼이 있는 예제 화면이 뜬다 - 버튼이 먹색(짙은 회색)이다 — 파란 버튼이면 킷이 잘못 열린 것
킷 안에는 이미 들어 있습니다 — 토큰 링크 2줄, 뷰포트 메타 설정, 예제 화면(표·검색·배지·모바일 탭바·다크 전환), 그리고 AGENTS.md.
AI에게 규칙 심기★
3분AI는 규칙을 안 주면 자기가 아는 색(대부분 파란색)을 씁니다. 그 순간 브랜드 통일은 끝납니다. 이 3분을 아끼면 나중에 며칠을 씁니다.
프로젝트 루트에 규칙 파일(AGENTS.md · CLAUDE.md · GEMINI.md 중 이 도구가 읽는 것)이 있어.
이게 우리 회사 디자인 규칙 문서야. 이 파일은 절대 고치지 마.
(폴더를 읽을 수 없는 대화형 도구라면, 이 메시지 맨 아래에 규칙 문서 전체를 붙여넣을게.)
지금부터 아래를 지켜줘.
1. 먼저 그 규칙 문서를 읽고, 규칙을 몇 조 읽었는지 나에게 말해줘.
읽지 못했다면 읽지 못했다고 말해. 읽은 척하지 마.
2. https://ds.janytree.app/llms.txt 도 읽어줘. 우리가 쓸 수 있는
토큰과 컴포넌트 목록이 전부 들어 있어.
3. 앞으로 색·크기·간격에 숫자나 hex(#305CDE 같은 것)를 직접 쓰지 마.
반드시 var(--color-...) 같은 토큰 이름을 써.
4. 버튼·입력칸·표 같은 부품은 새로 만들지 말고 .jt-btn, .jt-input,
.jt-table 같은 기존 클래스를 써.
5. jt-tokens.css 와 jt-utilities.css 파일은 수정 금지.
모양을 바꿔야 하면 --jt-* 값만 덮어써.
6. 토큰에 없는 값이 필요하면 지어내지 말고 나에게 물어봐.
다 읽었으면 "규칙 확인 완료"라고 말하고, 규칙 중 가장 중요한 3개를
네 말로 요약해줘. 아직 코드는 만들지 마.- AI가 규칙 확인 완료라고 답한다
- 요약 3개 안에 hex를 직접 쓰지 않기와
.jt-*클래스 쓰기가 들어 있다 - 아직 파일을 만들지 않았다 — 만들었으면 규칙을 안 읽은 것이니 다시 시키세요
AGENTS.md 를 못 찾는다고 할 때
AGENTS.md 파일을 못 찾겠으면, 프로젝트 루트에 어떤 파일들이 있는지 목록으로 보여줘.그래도 없으면 → jt-core 규칙 페이지의 원본 파일을 내려받아 프로젝트 루트에 AGENTS.md로 저장하세요.
AI 도구의 「프로젝트 규칙(Rules)」 기능에 등록해 두세요. 매번 붙여넣지 않아도 됩니다. 등록 방법 → AI 규칙 · 프롬프트
앱의 성격 3가지 정하기
3분나중에 바꾸면 화면을 다시 그려야 하는 3가지입니다. 용어는 몰라도 됩니다. 가운데 질문에만 답하세요.
| 정할 것 | 쉬운 질문 | 답이 이러면 | 고를 것 |
|---|---|---|---|
| 글자 분위기 | 이 앱에서 사용자가 “일을 처리”하나요, “읽고 구경”하나요? | 일을 처리 | Productive (업무형·기본) |
| 읽고 구경 | Expressive (홍보형) | ||
| 본문 폭 | 화면에 표·데이터가 많나요? | 글 위주 문서 | narrow 720 |
| 보통 업무 앱 | max 1200 (기본) | ||
| 표가 아주 넓음 | wide 1440 | ||
| 휴대폰 | 공장·창고에서 폰으로 볼 일이 있나요? | 있다 | 주요 메뉴 5개 이하 → 하단 탭바 |
| 없다 | PC만 |
[대괄호] 부분은 지우고 본인 내용을 넣으세요.
내가 만들 앱은 [예: 원료 입고 검사 결과를 기록하고 판정하는 앱]이야.
주 사용자는 [예: 공장 품질팀 3명]이고, 주로 [예: PC, 가끔 휴대폰]으로 봐.
이 앱에 맞는 조판(Productive/Expressive), 컨테이너 폭(720/1200/1440),
모바일 하단탭 필요 여부를 추천해주고, 왜 그런지 한 줄씩 이유를 알려줘.
아직 코드는 만들지 마.뼈대 만들기
15분상단바·왼쪽 메뉴·본문이 있는 집의 골조를 세웁니다. 내용은 아직 가짜 데이터입니다.
(A) 스티치를 안 쓴 경우 — 대부분 이쪽입니다
[대괄호] 부분은 지우고 본인 내용을 넣으세요.
이제 앱의 기본 뼈대를 만들어 줘.
- 앱 이름 : [앱 이름]
- 하는 일 : [한 줄 설명]
- 조판 : [Productive / Expressive]
- 본문 폭 : [720 / 1200 / 1440]
- 모바일 : [하단 탭바 있음 / PC만]
- 왼쪽 메뉴에 들어갈 것 : [메뉴1], [메뉴2], [메뉴3]
지킬 것:
- 화면 골격은 처음부터 그리지 말고
https://ds.janytree.app/develop/patterns 의 패턴과
https://ds.janytree.app/develop/templates 의 템플릿에서 골라서 써.
어떤 것을 골랐는지 이유와 함께 알려줘.
- 클래스는 .jt-shell / .jt-sidebar / .jt-topbar / .jt-main 을 쓴다.
- 색·간격에 직접 값을 쓰지 않는다. 토큰 이름만 쓴다.
- 지금은 뼈대만. 개별 화면과 기능은 다음 단계에서 한다.
끝나면 (1) 만든 파일 목록 (2) 고른 패턴 이름과 이유를 알려줘.(B) Google Stitch로 디자인을 먼저 뽑은 경우
[대괄호] 부분은 지우고 본인 내용을 넣으세요.
스티치 MCP에서 공통 뼈대(상단바, 왼쪽 메뉴, 본문 영역)를 읽어와서 구현해 줘.
중요 — 스티치가 준 코드를 그대로 붙이지 말고 반드시 아래를 정리한 뒤 넣어 줘.
- 임의 색(#305CDE 같은 hex)은 var(--color-*) 토큰으로 바꾼다.
- 임의 크기(p-[13px], text-[15px] 같은 대괄호 표기)는 토큰으로 바꾼다.
- Tailwind 기본 색(bg-blue-500, text-gray-600 등)은 뜻이 같은 우리 이름으로 바꾼다.
- 어느 이름으로 바꿔야 할지 애매하면 임의로 정하지 말고 먼저 나에게 물어봐.
끝나면 바꾼 것을 표로 보여 줘. (바꾸기 전 → 바꾼 후 → 이유)- 브라우저에 상단바 + 왼쪽 메뉴 + 본문이 보인다
- 버튼이 먹색이다 — 파란 버튼이면 STEP 2로 돌아가세요
- (B의 경우) 변환표가 출력됐다. 표가 없으면 정리를 안 한 것입니다
화면 하나씩 만들기 — 화면 개수만큼 반복★
화면당 20~40분한 번에 화면 여러 개를 요청하지 마세요. 하나 만들고 → 실제로 눌러 보고 → 다음. 이것이 가장 흔한 실패 원인입니다.
[대괄호] 부분은 지우고 본인 내용을 넣으세요.
"[화면 이름]" 화면을 만들어 줘.
[이 화면이 하는 일]
[한두 줄 설명]
[화면에 들어가는 것]
1. [항목] — [예: 표, 검색창, 등록 버튼]
2. [항목] — [입력 방식]
지킬 것:
- 버튼·입력칸·표·배지는 새로 만들지 말고 .jt-* 기존 컴포넌트를 가져다 쓴다.
목록: https://ds.janytree.app/components
- 색·크기·간격에 직접 값을 쓰지 않는다. 토큰만 쓴다.
- 빈 상태(데이터가 없을 때)와 로딩 상태도 함께 만든다.
- 지금은 화면(보이는 부분)만. 데이터 연결과 기능은 다음 단계.
가짜 데이터를 5줄 정도 넣어서 화면이 어떻게 보이는지 볼 수 있게 해줘.
끝나면 어떤 .jt-* 컴포넌트를 썼는지 목록으로 알려줘.- 화면이 보이고, 가짜 데이터가 5줄 들어 있다
- AI가 쓴 컴포넌트 목록을 보고했다 (새로 만든 부품이 있으면 왜 필요했는지 물어보세요)
- 데이터를 다 지웠을 때 “내용이 없습니다” 같은 빈 상태가 보인다
기능 붙이기 — 화면마다
화면당 30분~[대괄호] 부분은 지우고 본인 내용을 넣으세요.
"[화면 이름]" 화면에 기능을 붙여 줘.
[이 화면에서 되어야 하는 일]
- [예: 목록을 데이터베이스에서 불러온다]
- [예: 검색창에 글자를 넣으면 이름으로 걸러진다]
- [예: 추가 버튼을 누르면 입력창이 뜨고, 저장하면 목록에 반영된다]
- [예: 삭제는 확인창을 거친 뒤에만 실행된다]
[주의할 것]
- 화면 모양은 바꾸지 말고, 기능만 붙여줘.
- 확인창은 브라우저 기본 팝업(alert, confirm) 대신 앱 안의 모달로 만들어줘.
- 저장에 실패했을 때 사용자에게 보여줄 문구도 만들어줘.
문구 원칙: https://ds.janytree.app/develop/ux-writing
- 무엇이 잘못됐는지 나에게도 알려줘.직접 눌러봅니다. 저장·삭제·검색이 되고, 브라우저 기본 팝업이 뜨지 않는다.
눈으로 확인
10분지금 화면을 아래 4가지로 점검하고, 문제가 있으면 어디인지 알려줘. 아직 고치지는 마.
1. 다크 모드 — document.documentElement.dataset.theme='dark' 로 바꿨을 때
글자가 안 보이는 곳이 있는지
2. 모바일 — 폭 390px 에서 가로 스크롤이 생기는 곳이 있는지
3. 글자 팽창 — 버튼 글자를 3배 길게 넣었을 때 깨지는 곳이 있는지 (번역 대비)
4. 판정·상태를 색만으로 표시한 곳이 있는지 (글자가 함께 있어야 함)내 눈으로도 이 3가지만 확인합니다
| 확인 | 어떻게 |
|---|---|
| 다크 모드 | 앱에서 다크로 전환 → 글자가 배경에 묻히지 않는가 |
| 휴대폰 | 브라우저 창을 손가락 두 개 폭까지 줄이기 → 좌우로 밀리면 실패 |
| 회색 글자 | 아주 연한 회색 글자가 있으면 → 읽을 수 있는가 |
배포 전 점검 + 기록
10분배포 전 점검을 해줘.
https://ds.janytree.app/develop/checklist 의 16항목을 기준으로
프로젝트 전체를 검사하고, 파일 이름과 줄 번호를 표로 보여줘.
특히 이 3개는 실제로 사고가 났던 것이니 반드시 확인해줘.
1. --color-text-tertiary 를 글자 색으로 쓴 곳 (대비 부족)
2. 아이콘 폰트를 display=block 으로 로드했는지
(swap 이면 아이콘 대신 settings 같은 영어 원문이 보입니다)
3. 판정·상태를 색만으로 전달한 곳
아직 고치지 말고, 무엇부터 고칠지는 내가 정할게.배포 후 홈의 적용 현황 표에 앱 이름 · 채택 레벨 · DS 버전을 추가하세요. 안 하면 다음 버전업 때 어떤 앱이 뒤처졌는지 아무도 모릅니다.
나중에 화면을 추가할 때★
며칠 뒤·몇 주 뒤AI는 지난주에 정한 규칙을 기억하지 못합니다. 이 문장 없이 새 화면을 시키면 그 화면만 모양이 다릅니다. 가장 흔한 실수입니다.
[대괄호] 부분은 지우고 본인 내용을 넣으세요.
새 화면 "[화면 이름]" 을 추가하려고 해.
시작하기 전에 반드시 아래 순서로 확인하고, 확인한 내용을 나에게 요약해줘.
1. 프로젝트 루트의 규칙 파일(AGENTS.md · CLAUDE.md · GEMINI.md)을 읽어서 디자인 규칙 확인
2. 이 프로젝트가 쓰는 토큰 목록 확인 (jt-tokens.css)
3. 이미 만들어 둔 공용 부품이 무엇인지 확인
4. 비슷한 기존 화면 하나를 열어서 구조와 여백 쓰는 법 확인
그다음 기존 화면들과 똑같은 결로 새 화면을 만들어 줘.
[이 화면이 하는 일]
[설명]
[화면에 들어가는 것]
1. [항목] — [입력 방식]
2. [항목] — [입력 방식]
새 버튼 모양이나 새 색을 만들지 마. 기존 것으로 안 되면 먼저 나에게
"이런 게 필요한데 새로 만들어도 될까요?" 라고 물어봐 줘.디자인이 흐트러진 느낌이 들 때
한 달에 한 번[대괄호] 부분은 지우고 본인 내용을 넣으세요.
프로젝트 전체를 점검해 줘.
1. 색을 직접 박아 넣은 곳을 전부 찾아줘 (#305CDE 같은 hex, rgb())
2. 크기를 직접 박아 넣은 곳을 찾아줘 (p-[13px], text-[15px] 같은 대괄호 표기)
3. Tailwind 기본 색을 쓴 곳을 찾아줘 (bg-blue-*, text-gray-*, bg-slate-* 등)
4. style={{ }} 로 색이나 간격을 직접 지정한 곳을 찾아줘
5. .jt-* 공용 부품을 안 쓰고 따로 만든 버튼·입력칸이 있는지 찾아줘
6. jt-tokens.css 나 jt-utilities.css 를 수정한 흔적이 있는지 확인해줘
파일 이름과 줄 번호를 표로 보여 주고, 아직 고치지는 마.
무엇부터 고칠지는 내가 정할게.막혔을 때 — 그대로 붙여넣는 문장
뭘 하고 있는지 모르겠다
지금 무엇을 하고 있는지, 어떤 파일을 고칠 계획인지
코딩을 모르는 사람이 이해할 수 있게 한국어로 설명해줘.
설명을 듣고 내가 진행 여부를 정할게.스타일이 아예 안 먹는다 (색도 글꼴도 그대로)
jt-tokens.css 와 jt-utilities.css 링크가 제대로 들어가 있는지 확인해주고,
개발자도구에서 실제로 불러와졌는지 검사하는 방법을 알려줘.개발할 땐 되는데 배포하면 깨진다
Tailwind 를 쓰고 있다면 content 경로 설정 때문에 클래스가 빠졌을 수 있어.
설정 파일을 확인하고 문제를 알려줘.→ 툴체인
스티치에서 못 읽어온다
스티치 MCP가 연결되어 있는지 확인해 주고, 지금 쓸 수 있는 도구 목록을 보여 줘.만든 화면이 스티치 디자인과 다르다
지금 만든 화면이 스티치 디자인과 좀 다른 것 같아.
스티치 MCP로 그 화면을 다시 읽어서 어디가 다른지 비교해 주고,
디자인 쪽에 맞춰서 고쳐 줘.화면이 뒤틀렸다 / 그 밖의 증상
- 레이아웃이 흔들렸다 → 안전 적용 규칙
- 에러 문구가 뜬다 → 도움말 · 에러 사전
- 자주 나오는 함정 → 자주 깨지는 곳 10가지
이 페이지의 모든 프롬프트를 한곳에서
며칠 뒤에 “그 문장이 어디 있었지” 하고 찾게 됩니다. 즐겨찾기는 이쪽으로 하세요.
→ 프롬프트 지갑 — 이 페이지와 트랙 B의 프롬프트를 카드 11장으로 모아 둔 곳
용어 사전
| 사이트 용어 | 쉬운 말 |
|---|---|
| 토큰 | 회사가 정한 색·크기·간격의 값 이름표. #305CDE 대신 --color-link 라고 부르는 것. |
| 컴포넌트 | 미리 만들어 둔 부품. 버튼, 입력칸, 표, 배지 같은 것. |
| 하드코딩 | 값을 코드에 직접 박아 넣는 것. 나중에 한꺼번에 못 바꿔서 문제가 됩니다. |
| 노브 | 부품에 달린 조절 손잡이(--jt-* 값). 부품을 뜯어고치지 말고 이것만 돌립니다. |
| 스코프 | 시스템이 적용되는 울타리 범위(.jt-scope). 좁게 시작해 넓혀갑니다. |
| 채택 레벨 | 어디까지 입혔는지 나타내는 단계. L1 색 → L2 글꼴 → L3 부품 → L4 간격. |
| Productive | 업무형 조판. 일을 처리하는 앱에 씁니다. (기본값) |
| Expressive | 홍보형 조판. 읽고 구경하는 페이지에 씁니다. |
| 컨테이너 | 본문이 차지하는 최대 가로 폭. 720 / 1200 / 1440 중에 고릅니다. |
| 텍스트 팽창 | 번역하면 글자가 길어지는 현상. 한글 3자가 영어 12자가 됩니다. |
| 뷰포트 메타 | 휴대폰에서 화면이 축소돼 보이지 않게 하는 <head> 안의 한 줄 설정. |
| 전역 리셋 | 브라우저가 기본으로 넣는 여백을 0으로 초기화해 두는 것. |
| MCP | AI가 다른 프로그램(스티치 등)을 직접 읽어오게 해주는 연결 통로. |
| 스타터 킷 | 세팅이 이미 끝난 빈 프로젝트. 받아서 열기만 하면 됩니다. |
| 컴포넌트 계약 | 부품을 쓸 때 앱이 지켜야 할 4가지 약속. 이것만 지키면 버전이 올라가도 안 깨집니다. |
| AGENTS.md | 프로젝트 루트에 두는 AI용 규칙 파일. AI가 대화 시작 때 읽습니다. |