디발사전 · Debal Dictionary
디발러를 위한 실무 지식 사전
디자이너·기획자가 개발 협업에 필요한 개념을 짧은 정의, 시각화, 실무 사례로 익히는 웹 서비스입니다.
영문명 Debal Dictionary (debal-dictionary) — Design과 Developer의 공통된 앞부분 De를 살려, 디자인과 개발을 잇는다는 뜻을 담았습니다.
이 저장소는 허들링 클럽 4차 사이클 2차 실험인 커스텀 AI 디자인 하네스의 결과물입니다. Claude Code 위에 규칙·게이트·검수 에이전트를 만들고, 그 하네스로 2개 화면(홈, API란 무엇일까? 상세)을 G1 → G2 → G3 순서로 한 바퀴 완주했습니다.
1. 프로젝트 목적
서비스
- 디발러는 디자인과 개발을 겸하거나 개발 지식을 바탕으로 협업하는 사람, 또는 개발을 이해하고 싶은 디자이너·기획자를 말합니다.
- 개념 상세는 7개 모듈로 구성됩니다. Hero → 한눈에 보는 정의 → 그림으로 이해하기 → API가 쓰이는 곳 → 개발자가 이렇게 말한다면 → 실무에서 이렇게 활용해요 → 함께 보면 좋은 학습.
- 제품 원칙은 두 가지입니다.
- PG-01 즉시 접근: 로그인이나 학습 이수 없이 바로 핵심 정의를 볼 수 있습니다.
- PG-02 학습 유형 분리: 플래시카드는 용어 Q/A만 다루고, 실무 판단 3지선다는 시나리오 퀴즈에서만 다룹니다.
하네스 실험
- 기존 방식(AS-IS)의 문제: AI 도구로 화면을 만들고 프롬프트로 고치는 방식을 반복하면 일관성이 무너졌습니다. 같은 역할의 컴포넌트·색·간격이 화면마다 다르게 생성됐습니다 (
docs/decisions.md Round 2).
- 이번 방식(TO-BE):
- 사전 차단: 토큰을 코드로 먼저 고정하고, AI가 그 안에서만 조립하게 합니다.
- 사후 검사: 그래도 새어 나간 위반은 Hook과 검수 에이전트가 적발합니다.
- 사람 승인: 화면 승인(G2)은 사람만 할 수 있습니다.
2. 기술 스택
| 구분 | 사용 |
|---|
| 프레임워크 | Next.js 16.4.2 (App Router, cacheComponents), React 19.3, TypeScript |
| 스타일 | Tailwind CSS v4 (CSS-first @theme, tailwind.config.ts 없음) |
| UI 컴포넌트 | shadcn/ui (radix 기반, radix-nova 스타일), 클래스 병합 cn |
| 폰트 | SUIT Variable v2.0.5 (self-host, SIL OFL 1.1 — public/fonts/SUIT-OFL.txt) |
| 아이콘 | lucide-react |
| 콘텐츠 | content/ 아래 TypeScript 데이터 (CMS·DB 없음) |
| 테스트 | playwright-core 1.56.1 + 설치된 Chrome (tests/e2e/) |
| AI 하네스 | Claude Code — CLAUDE.md + .claude/ (commands · agents · hooks) |
3. 하네스 구조
CLAUDE.md 불가변 원칙·확정 토큰·게이트 규칙 — 모든 세션에 자동 로드
.claude/
settings.json Hook 등록 (PostToolUse: Write|Edit)
hooks/token-guard.sh 토큰 위반 사후 탐지 (차단·수정하지 않음)
commands/
tokens.md /tokens — Phase 0: 토큰을 코드로 생성
g1.md /g1 — 요구사항 게이트: PRD → docs/screens.md
g2.md /g2 — 화면 리뷰 게이트: 사람 승인 전용
g3.md /g3 — 일관성 게이트: 검수 에이전트 병렬 실행 → 일괄 수정
agents/
design-auditor.md 토큰·재사용·접근성 기계 검사 (읽기 전용)
content-reviewer.md 기술 정확성 1차 검수 (읽기 전용)
docs/
prd.md · design.md 제품 요구사항 · 디자인 기준 (기준값의 단일 출처)
screens.md G1 산출물 — 화면별 섹션·인터랙션·데이터 정의
decisions.md 결정 기록 (Round 1~8 인터뷰, 게이트별 승인)
review.md 이슈·수정·QA 결과 누적 (G2 1~5차, G3, 회귀)
story-service.md · story-work.md 서비스·작업 방식 스토리
| 구성 요소 | 역할 | 설계 이유 |
|---|
CLAUDE.md | 위반하면 작업을 멈추는 원칙 8개를 둡니다. 토큰 외 값 금지, shadcn 우선, PRD 범위 고정, PROVISIONAL 보존, G2 사람 승인 전용 등입니다 | 대화 중 요청으로 완화되지 않는 규칙이 필요했습니다 |
| 토큰 파일 | raw 값(HEX 등)은 app/globals.css, lib/tokens.ts에만 둡니다 | 값을 고를 여지를 없애는 사전 차단입니다 |
token-guard.sh | 파일이 저장된 뒤 HEX·임의값·9단계 밖 spacing·비허용 radius를 보고합니다. 파일당 2회만 알리고, 고치지 않습니다 | 탐지와 수정을 분리해 "수정 → 재탐지" 루프를 구조적으로 없앴습니다 |
/g1 /g2 /g3 | 단계별 절차와 판정 기준을 명령으로 실행합니다 | 게이트를 문서 권고가 아닌 실행 가능한 절차로 만들었습니다 |
| 검수 에이전트 2개 | 디자인 지적과 콘텐츠 지적을 독립된 두 에이전트가 따로 검사합니다 | 생성한 주체가 자기 결과물을 검사하면 놓치는 것이 많습니다 |
AskUserQuestion | 사람이 판단할 항목은 질문 UI로 선택받습니다 | 피드백을 글로 정리해야 하는 부담을 클릭 선택으로 줄였습니다 |
4. G1 → G2 → G3 진행 과정
| 단계 | 내용 | 결과 |
|---|
Phase 0 /tokens | 팔레트 5색·spacing 9단계·radius·타입 스케일·SUIT를 코드화했습니다. 미확정 기능성 토큰은 PROVISIONAL로 비워 두었습니다 | 대비비 실측 (ink/canvas 11.27:1 등), SUIT 실제 로드 확인 |
G1 /g1 | PRD에서 2화면을 docs/screens.md로 정의했습니다. PRD로 정할 수 없는 8가지는 질문으로 결정했습니다 (카드 수, 시각화 방식, 검색 동작, accent 위치, border·ring 값 등) | PASS |
| Phase 2 구현 | 홈과 API 상세를 데스크톱·모바일로 구현했습니다. 콘텐츠는 content-reviewer 1차 검수를 거쳤습니다 | 자동 테스트 통과 ≠ G2 |
G2 /g2 | 1~5차 피드백 (아래), 콘텐츠 권고 분류·처리, 항목별 사람 승인 4/4 | PASS → 커밋 524884e |
G3 /g3 | design-auditor ∥ content-reviewer를 병렬로 실행했습니다. BLOCKER 2건을 실측으로 확인해 처리하고, 사람 판정 항목을 질문으로 결정했습니다 | PASS |
| G3 최종 화면 검토 | 사람이 회귀 이슈 3건(R-09~R-11)을 발견해 수정·재검증했습니다 | 최종 승인 → 커밋 cf4e47d |
G2 피드백 이력 (docs/review.md)
| 차수 | 내용 |
|---|
| 1차 | 카드에 읽기 시간 표시, 카드 hover/focus 상태, Developer Talk 정보 위계 정리. 질문 목록이었던 모듈 6을 실무 사례로 재설계하자는 제안 → PRD 변경이라 비교표를 먼저 제시하고 승인 후 구현 |
| 2차 | 실무 사례에 '함께 준비하면 좋은 것들' 추가, 관련 학습 칩 정렬, 섹션 제목 리듬 점검 |
| 3~5차 | 시각화 단계를 넘길 때 카드 높이가 바뀌는 문제를 고정 → 4·5단계 패널을 다이어그램과 같은 좌우 배치로 → 사용자 레퍼런스 이미지 기반 1:1 그리드로 재구성 |
5. 발견하고 해결한 주요 문제
| # | 문제 | 해결 | 배운 점 |
|---|
| H-01 | Hook의 보고 상한(8건)이 작동하지 않았습니다. 줄 수로 잘라서 카테고리 헤더 수에 따라 결과가 흔들렸습니다 | 위반 건수(N: 줄)로 자르도록 수정하고 12개 테스트로 재검증했습니다 | 하네스 도구 자체도 테스트가 필요합니다 |
| H-04 | /g1은 G1 통과 후 커밋하라고 하고, CLAUDE.md는 G2·G3 통과 때만 커밋하라고 해서 충돌했습니다 | 상위 규칙을 따르고 사용자 확인을 받은 뒤 명령 문서를 고쳤습니다 | 규칙 문서끼리 충돌하면 임의로 고르지 말고 기록한 뒤 묻습니다 |
| R-03 · R-07 → G3-01 | '다음' 버튼 글자가 사라지고 카드 제목이 18px이 아닌 16px로 렌더됐습니다. 클래스 병합 도구가 커스텀 타입 토큰(text-body 등)을 색으로 오인했습니다 | 처음엔 호출부에서 우회했습니다. G3에서 lib/utils.ts의 createCn으로 토큰을 font-size 그룹에 등록해 근본 원인을 해결했습니다 | 우회는 같은 원인의 다음 증상을 막지 못했습니다 (G3 BLOCKER B-1·B-2) |
| R-09 | G3 수정 직후, 카드 hover 시 배지 글자가 ink 배경 위의 ink로 사라졌습니다 | 병합이 고쳐지자 원본의 text-foreground가 남아, 그동안 우연히 상속받던 색이 끊긴 것이 원인이었습니다. 상태별 글자색을 명시했습니다 | 근본 수정이 숨어 있던 의존을 드러낼 수 있습니다. 사람이 최종 화면에서 발견했습니다 |
| F-09~F-11 | 시각화 단계에 따라 카드 높이와 버튼 위치가 흔들렸습니다 | 단계별 내용을 같은 그리드 칸에 겹쳐 그려, 고정 px 없이 가장 큰 단계에 높이를 맞췄습니다. 재사용 기준으로 design.md §5 「단계형 시각화 패턴」을 정리했습니다 | 측정 기반 레이아웃 검증(단계별 높이·위치 실측)이 효과적이었습니다 |
| E-01 | 일반 Chrome에서만 Hydration Mismatch가 발생했습니다 | 확장 프로그램이 없는 환경에서는 재현되지 않았고, Grammarly가 넣는 속성이 원인이었습니다. 앱 코드는 수정하지 않았습니다 | 환경 이슈와 코드 이슈를 분리해 기록했습니다 |
| D-06 | Hook이 text-xs/sm/base와 크기 유틸을 검사하지 않아 B-1·B-2를 "위반 0건"으로 보고했습니다 | G3에서는 design-auditor의 전역 스캔과 실측을 기준으로 삼았습니다. Hook 개선은 후보로 기록했습니다 | Hook이 침묵한다고 위반이 없는 것은 아닙니다 |
콘텐츠 검수:
content-reviewer 권고 C-01C-58과 확인 질문 C-Q1C-Q11을 분류했습니다. 분류는 중복 / 해결됨 / 사실관계 / 표현 / 제품 결정입니다.- 사람이 수용·보류를 결정한 것만 반영했습니다. 보류한 항목은 사유를 기록했습니다.
- 대표 예시: "API = 약속, 서버 = 주체" 층위를 일관되게 정리한 것, "모든 화면 데이터가 API에서 오지는 않는다"를 명시한 것입니다.
정리하면:
- 자동 테스트·타입체크·린트를 모두 통과해도 G2 통과가 아닙니다. 실제로 사람의 화면 검토가 테스트로 잡지 못한 문제(배지 hover, 패널 배치, 빈 공간)를 찾았습니다.
- 미확정 값은 PROVISIONAL로 두고 후보와 실측 대비비를 함께 제시해 승인받았습니다 (
border #848382, muted-foreground #676665 등).
6. 로컬 실행
요구 사항: Node.js 20 이상, npm. E2E 테스트에는 Chrome이 필요합니다.
npm install
npm run dev # http://localhost:3000
| 주소 | 화면 |
|---|
/ | 홈 — 검색, 카테고리 필터, 개념 카드 |
/concepts/api | API란 무엇일까? — 개념 상세 7모듈 |
그 밖의 명령:
npx tsc --noEmit # 타입체크
npm run lint # 린트
npm run build # 프로덕션 빌드
E2E 테스트
개발 서버를 띄운 상태에서 실행합니다.
npm run test:e2e
| 파일 | 내용 |
|---|
tests/e2e/functional.mjs | 1440·390px 기능 회귀 138항목 — 검색·카테고리·카드 상태, 7모듈, 시각화 5단계(버튼 표시 규칙·높이·위치 고정·키보드 포커스), 실무 사례, 토큰 실측(글자 크기·색·대비) |
tests/e2e/responsive.mjs | 1440·768·390px 스모크 18항목 — 가로 넘침, PG-01, 키보드 Tab 도달, 콘솔 오류 + 전체 페이지 스크린샷 |
tests/e2e/setup.mjs | 공통 설정 |
| 환경 변수 | 기본값 | 설명 |
|---|
BASE_URL | http://localhost:3000 | 테스트할 서버 |
CHROME_PATH | (없음) | Chrome/Chromium 실행 파일 경로. 없으면 설치된 Chrome 안정 채널을 자동으로 찾습니다 |
브라우저 준비: playwright-core는 브라우저를 내려받지 않습니다. 다음 중 하나가 필요합니다.
-
Google Chrome 안정 채널을 설치합니다. 기본 경로에 설치되어 있으면 자동으로 찾습니다.
-
또는 Chrome·Chromium 실행 파일 경로를 CHROME_PATH로 지정합니다. 예: CHROME_PATH=/usr/bin/chromium npm run test:e2e
-
다른 서버를 테스트할 때는 BASE_URL=http://localhost:4000 npm run test:e2e처럼 지정합니다.
-
스크린샷은 tests/e2e/screenshots/에 저장되며 git에는 포함되지 않습니다.
-
하나라도 실패하거나 서버에 연결할 수 없으면 종료 코드 1을 반환합니다.
-
이 테스트는 참고 자료입니다. 전부 통과해도 G2 승인을 대신하지 않습니다 (CLAUDE.md §5).
검증 범위:
| 구분 | 내용 |
|---|
| 실제로 통과를 확인한 환경 | macOS 26.6 · Node.js 24.18 · Google Chrome 155 · npm run dev(localhost:3000)에서 functional 138/138, responsive 18/18 통과 (2026-10-24) |
| 다른 환경을 위해 정리한 것 | 브라우저 경로·서버 주소를 환경 변수로 분리, 스크린샷 경로를 테스트 파일 기준으로 고정, 실패 시 종료 코드 1. 다른 작업 디렉터리에서 실행해도 통과하는 것은 확인했습니다 |
| 아직 확인하지 않은 것 | Windows·Linux, Chromium, CI 환경에서의 실행. 렌더링 차이로 일부 픽셀 측정값(카드 높이·버튼 위치 등)이 달라질 수 있습니다 |
7. 현재 구현 범위와 향후 계획
현재 (1차 하네스 검증 범위)
- 홈: 서비스 소개, 검색(제목·기술 용어·태그), 카테고리 칩, 개념 카드 1장
- API 상세: 7모듈 전체
- 5단계 요청·응답 시각화 (예시 응답 데이터와 화면 갱신이 연동됨)
- 프로필 사진 미표시 실무 사례 (화면·데이터 비교, 확인 질문, 직무별 준비사항)
- 관련 학습은
준비 중으로 표시
- 실행 환경: 로컬 dev 서버만, 라이트 모드 전용
향후 (Phase 4 — 새 화면마다 G2·G3 재적용)
- PRD MVP의 나머지 범위
- 플래시카드(용어 Q/A), 실무 시나리오 퀴즈(3지선다·해설)
- 개념 라이브러리, 학습 상태 로컬 저장
- 콘텐츠 계획치: 개념 15개, 카드 30장, 퀴즈 10문항 (제작 완료가 아닌 계획)
- 승인 대기(PROVISIONAL) 항목
- 모바일·태블릿 경계값, 페이지·상세 본문 최대 너비, slug
muted(배경)·destructive 토큰- 배포 도메인·SEO
- G3 이후 디자인 개선 후보 D-01~D-06: 섹션 아이콘 시스템, radius 용도 정리, 다이어그램 요소 비버튼화, Hook 검사 범위 확장 등
자세한 결정과 근거는 docs/decisions.md, 이슈와 검증 기록은 docs/review.md에 있습니다.
