yunchan/designpaca
1
0
Fork 0
Code Issues Pull requests Projects Releases 5 Packages Wiki Activity Actions

feat(skill): absorb external design skills, restore interview gate, add review route

Browse source 
- Restore the step-0 interview as a mechanical gate the skill explicitly
  depends on; add harness.md (per-harness question tools, limits,
  fallbacks) and brief-interview.md (slots, question cards, rounds).
- Add 10 reference docs absorbed from external design skills
  (accessibility, interaction-feel, elevation, color, icons, product-copy,
  component-systems, critique, change-review, print-email) and extend
  existing references.
- Add a review-only route and two hard-gate clauses (truncated content
  reachability, three-flashes limit).
- design-gate: split tap targets into WCAG 2.5.8 and 44px contract layers,
  run axe-core when available, and fix false positives found on a real
  site (decorative alt="", stacked wordmark line count, url-only pages).
- lint-skill: fail if the interview gate section or its links disappear.
- Ship agents/openai.yaml and THIRD_PARTY_NOTICES.md.
This commit is contained in:
Yun Chan 2026-09-24 13:26:03 +09:00
parent 79e79c120b
commit 6805fb2be7
37 changed files with 5688 additions and 128 deletions
Download patch file Download diff file Expand all files Collapse all files

247
packages/skill/references/brief-interview.md Normal file
View file

@ -0,0 +1,247 @@
# brief interview — 브리프를 인터뷰로 확정하는 법
0단계에서 [SKILL.md](../SKILL.md)의 인터뷰 게이트를 실제로 어떻게 수행하는지 정한 문서다. 게이트의 여섯 규칙은 여기서 바뀌지 않는다 — 이 문서는 그 규칙을 슬롯표, 질문 카드, 라운드, 기록 형식으로 구체화한다. 하네스별 질문 도구 이름과 한도는 [harness.md](harness.md)를 따로 연다.
## 1. 왜 인터뷰가 필수 입력인가
브리프가 비어 있는 채로 시작하면 그 빈칸을 메우는 것은 모델의 기본값이고, 기본값의 총합이 AI 슬롭이다. "합리적으로 추측했다"는 것은 안전장치가 아니다 — 추측은 카테고리 평균으로 수렴하고, 카테고리 평균은 어떤 브리프에도 들어맞는 대신 이 브리프에만 맞는 이유가 없다.
실측 사례 — "꽃집 홍보 사이트 하나 만들어보자"를 받고 업종 성격·목표 행동·톤·이름을 전부 혼자 정했다. 실제로 물어보니 **넷 중 넷이 달랐다.**
| 내가 가정한 것 | 사용자의 실제 답 |
|---|---|
| 일상 꽃 · 정기구독 | **하이엔드 플로럴 스튜디오** |
| 문의 유도 하나 | 문의 · 구독 · 방문 · 인스타 **넷 다** |
| (묻지 않음) | **에디토리얼 · 잡지** |
| (내가 지어냄) | **목요일의 화원** |
이 상태로 1단계에 들어갔으면 레퍼런스 세 개를 전부 틀린 방향에서 골랐을 것이다. 가정한 네 축 중 하나도 맞지 않았다는 것은 "대개는 맞는다"는 전제 자체가 틀렸다는 뜻이다. 인터뷰는 판단으로 생략할 수 있는 예의가 아니라, 1단계 이후 전체 작업의 입력이다.
## 2. 스캔 → 가설 → 질문
순서는 항상 이렇다.
1. **스캔한다.** `design.md`, 프로젝트 토큰, 브랜드 자산(로고·색·패키지), README·기존 문서를 먼저 읽는다.
2. **가설을 세운다.** 스캔에서 읽은 값은 **가설이지 사용자 승인이 아니다.** 저장소에 "정기구독" 문구가 있다고 해서 그것이 사용자가 확정한 업종 성격은 아니다.
3. **질문한다.** 가설은 질문의 추천 선택지로 제시해 확인받는다 — 추천 선택지는 항상 맨 앞에 두고 "(추천)" 표기를 붙인다. 근거(무엇을 읽고 이렇게 추천하는지)를 한 줄로 곁들인다. 스캔 근거가 없는 축에는 추천을 붙이지 않는다 — 근거 없는 추천은 모델의 기본 미학을 선택지 맨 앞에 올리는 일이다. 도구 설명이 영어 표기("(Recommended)")를 예로 들어도 표기는 기본 언어를 따른다.
스캔 결과를 사용자 확인 없이 바로 확정으로 쓰지 않는다. "코드에 이렇게 되어 있으니 그대로 갑니다"는 인터뷰를 생략하는 것이 아니라 인터뷰의 첫 단계일 뿐이다.
## 3. 브리프 슬롯
아래 표가 채워야 할 전부다. "알려진 사실"은 **사용자 발화 또는 사용자가 준 자료에 명시된 것**만 뜻한다. 업종 평균이나 코드에서 추론한 값은 확정이 아니라 2절의 가설이다.
| 슬롯 | 필수 조건 | 확정 기준 | 모를 때 |
|---|---|---|---|
| 무엇을 (산출물·범위) | 항상 | 요청 문장 | 묻는다 |
| 누구에게·목표 행동 (복수면 우선순위) | 전체·연장 | 사용자 발화 | 묻는다(multiSelect 후 우선순위 확인) |
| 업종·성격 | 전체, 연장의 새 화면 | 사용자 발화·제공 문서 | 묻는다(스캔 결과는 추천 선택지로) |
| 톤 | 전체. 연장은 design.md에 없을 때 | 사용자 선택 | 묻는다(선택지마다 모션 강도·프리셋 영향을 적는다) |
| 고유명사·실제 값 | 화면에 나오면 항상 | 사용자 제공 | 묻고, 아직 없다고 하면 명시적 placeholder |
| 기존 브랜드 자산 (색·로고·서체·쓸 수 있는 사진) | 전체 | 파일 또는 사용자의 "없음" | 묻는다 |
| 좁은 화면 내비 | 내비가 있는 다중 화면 | 정보 구조·라벨이 정해진 뒤 | 2라운드에서 묻는다 |
| 기본 언어 | 항상 | OS 로케일 명령 | 읽지 못할 때만 묻는다 |
슬롯이 "필수 조건"에 해당하는데 "확정 기준"을 사용자 발화·자료로 채우지 못했으면 **묻는다.** "결과를 크게 바꾸는가"를 스스로 판정해서 생략하지 않는다 — 그 판단은 이 표가 이미 대신 내렸다.
## 4. 경로별 적용
| 경로 | 무엇을 묻는가 |
|---|---|
| **전체** | 슬롯 전부를 이 표의 조건대로 묻는다. 좁은 화면 내비는 정보 구조가 정해진 뒤 2라운드에서 묻는다. |
| **연장** | 무엇을·목표 행동·고유명사·기본 언어는 전체와 같다. 업종·성격은 **새 화면**일 때만 묻는다. 톤은 `design.md`에 없을 때만 묻는다. 브랜드 자산은 `design.md`가 이미 답했으면 묻지 않는다. |
| **국소** | `design.md`가 슬롯에 답하면 묻지 않는다. 브랜드나 톤을 새로 정해야 하면 그 순간 경로를 전체나 연장으로 올리고, 올린 경로의 규칙대로 묻는다. 화면에 고유명사가 나오면 국소여도 항상 묻는다. |
| **리뷰** | 범위와 입력(스크린샷·URL·diff)만 묻는다. 위 슬롯은 리뷰 대상이 아니라 리뷰 자체의 입력이므로 별도로 취급한다. |
국소 경로에서 조건이 깨지면(토큰을 새로 정의하게 됐거나 손댄 섹션이 늘었거나 방향을 바꿔야 하면) SKILL.md 0단계의 규칙대로 경로를 올렸다고 말하고, 그 순간부터는 이 표의 전체·연장 행을 따른다.
## 5. 질문 카드 작성법
- **결과를 크게 바꾸는 축부터 낸다.** 업종·성격과 목표 행동이 톤이나 고유명사보다 앞선다 — 앞의 답이 뒤의 질문 구성을 바꾸기 때문이다.
- **선택지마다 "이걸 고르면 무엇이 달라지는지" 한 줄을 붙인다.** 고르는 사람이 결과를 미리 예상할 수 있어야 한다. "A: 발랄한 느낌"처럼 형용사만 나열하지 않는다. 라벨 자체가 결과를 드러내는 행동형 선택지(목표 행동 등)는 "고르면:" 줄을 생략해도 된다.
- **multiSelect와 단일 선택을 구분한다.** 목표 행동은 대개 복수이므로 multiSelect로 내고, 답이 여럿이면 다음 질문이나 다음 라운드에서 우선순위를 확인한다. 톤과 성격은 주된 방향 하나를 단일 선택으로 받는다. 브리프가 요구하면 서로 보완하는 속성을 자유 답으로 덧붙일 수 있지만, 그때도 어떤 속성이 위계를 이끄는지(주 방향이 무엇인지)를 기록한다.
- **톤 선택지에는 모션 강도와 프리셋 영향을 적는다.** 톤은 2단계 프리셋과 3단계 모션 문법을 여기서 사실상 결정하므로, "이 톤을 고르면 모션이 어느 정도 세지는지·어떤 레이아웃 프리셋으로 가는지"를 선택지 설명에 넣는다.
- **구조화 도구가 preview를 지원하면(Claude Code의 AskUserQuestion) 톤·내비 선택지에 ASCII 목업 비교를 붙인다.** 문장으로 "여백이 넓다"고 말하는 것보다 실제 배치 차이를 보여주는 쪽이 오답을 줄인다. 예시:
```
A. 에디토리얼 · 잡지 (editorial) B. 대담 · 캠페인 (anti-grid)
+----------------------+ +----------------------+
| | | 거대한 [사진] |
| 큰 제목 | | 제목 ↘ |
| ------------ | | [사진] 짧은 문장 |
| 작은 캡션 | | [사진] |
+----------------------+ +----------------------+
```
선택지 이름 옆의 괄호는 [presets/README.md](presets/README.md)의 실제 프리셋 이름이다. 톤 선택지는 존재하는 프리셋(editorial · swiss-minimal · anti-grid · dark-instrument · quiet-commerce)이나 "새로 정의"로만 연결한다.
## 6. 질문 카드 템플릿 3종
수단은 판단이 아니라 도구 목록으로 기계적으로 정한다. 하네스별 정확한 도구명·한도는 [harness.md](harness.md)에 있다. 아래는 세 가지 대표 형태다.
### (a) 구조화 도구 4문항판 (Claude Code · Gemini · Copilot 계열)
```
질문 1 — 업종·성격 (단일 선택)
A. 하이엔드 플로럴 스튜디오 (추천 — README에 "맞춤 부케·상담 예약" 언급)
고르면: 포트폴리오형 갤러리와 예약 상담 CTA가 중심이 된다.
B. 데일리 플라워 · 정기구독형
고르면: 반복 구매를 위한 가격·주기 섹션이 커진다.
C. 동네 꽃집 · 방문 중심
고르면: 위치·영업시간이 첫 화면에 노출된다.
질문 2 — 목표 행동 (다중 선택)
A. 상담·문의 신청
B. 정기구독 시작
C. 매장 방문·예약
D. 소셜 채널 팔로우
(복수 선택 시 다음 라운드에서 우선순위를 확인합니다.)
질문 3 — 톤 (단일 선택, 모션·프리셋 영향 표시)
A. 에디토리얼 · 잡지
고르면: editorial 프리셋, 넓은 여백과 세리프, 모션은 절제(페이드 위주).
B. 대담 · 캠페인
고르면: anti-grid 프리셋, 깨진 격자와 큰 타입, 모션은 표현적.
C. 조용한 커머스
고르면: quiet-commerce 프리셋, 상품·사양이 주인공, 모션 최소.
질문 4 — 기존 브랜드 자산과 실제 값
A. 있다 — 자유 답(Other)에 로고·색 파일 위치와 상호명·연락처를 적어 주세요.
B. 아직 없다 — 브랜드 색은 레퍼런스에서 정하고, 상호명·연락처는 placeholder로 둡니다.
```
고유명사·실제 값은 선택지로 만들 수 없다. 질문 4처럼 자유 답(Other)으로 받거나, 비어 있으면 8절에 따라 2라운드에서 평문으로 받는다.
### (b) 3문항판 (Codex `request_user_input`: 질문 ≤3, 선택지 2~3, "Other"는 클라이언트가 자동 추가하므로 넣지 않는다)
```
질문 1 — 업종·성격
A. 하이엔드 플로럴 스튜디오 (추천 — README의 "맞춤 부케·상담 예약")
B. 데일리 플라워 · 정기구독형
C. 동네 꽃집 · 방문 중심
질문 2 — 가장 중요한 목표 행동 하나
A. 상담·문의 신청
B. 정기구독 시작
C. 매장 방문·예약
질문 3 — 톤
A. 에디토리얼 · 잡지 (editorial)
B. 대담 · 캠페인 (anti-grid)
C. 조용한 커머스 (quiet-commerce)
```
이 도구의 선택지는 서로 배타적이라 다중 선택을 받을 수 없다. 그래서 목표 행동은 "가장 중요한 하나"로 묻고, 나머지 행동은 아래 평문 블록에서 받는다. 같은 턴에 평문 한 블록을 더 낸다(질문 수 상한에 걸리는 나머지 슬롯):
```
추가로 확인이 필요합니다.
- 위에서 고른 것 말고도 원하는 행동(구독·방문·소셜 등)이 있으면 적어 주세요.
- 실제 상호명·연락처·영업시간이 있나요? 없으면 placeholder로 표시하겠습니다.
- 기존 로고나 브랜드 색이 있나요? 파일이 있으면 알려주세요.
- 좁은 화면 메뉴는 정보 구조를 정한 뒤 다음 라운드에서 따로 여쭙겠습니다.
```
### (c) 평문 폴백판 (구조화 질문 도구가 없거나 확인되지 않는 하네스)
```
1. 업종·성격이 어느 쪽에 가깝나요?
a) 하이엔드 플로럴 스튜디오
b) 데일리 플라워 · 정기구독형
c) 동네 꽃집 · 방문 중심
d) 위에 없음 — 직접 설명해 주세요
2. 목표 행동은 무엇인가요? (복수 가능)
a) 상담·문의 신청
b) 정기구독 시작
c) 매장 방문·예약
d) 소셜 채널 팔로우
3. 톤은 어느 쪽인가요?
a) 에디토리얼 · 잡지 (여백 넓고 모션 적음)
b) 대담 · 캠페인 (깨진 격자, 표현적 모션)
c) 조용한 커머스 (상품이 주인공, 모션 최소)
4. 실제 상호명·연락처·기존 로고나 브랜드 색이 있나요? 없으면 없다고 답해 주세요.
답을 주시면 1단계(레퍼런스 조사)로 넘어갑니다.
```
## 7. 턴 종료 규칙
물었으면 그 턴에서 1단계 조사·파일 생성·구현을 시작하지 않는다. 같은 턴에 할 수 있는 것은 스캔 결과 요약뿐이다 — "이런 파일을 읽었고 이렇게 추천한다"까지는 같은 턴에 말해도 되지만, 답을 받기 전에 레퍼런스를 조사하거나 토큰·코드를 만들지 않는다.
## 8. 라운드
1라운드가 기본이다. 2라운드는 다음 세 경우에만 연다.
- 답이 서로 모순될 때(9절)
- 고유명사·실제 값이 아직 없을 때
- 좁은 화면 내비를 정할 때(정보 구조가 확정된 뒤라야 물을 수 있으므로)
그 외의 이유로 라운드를 늘리지 않는다.
## 9. 답이 모순되면
그 자리에서 정리한다. 1절 사례에서 목표 행동 넷이 다 선택됐는데, 하이엔드 스튜디오에서 "정기구독"과 "문의 상담"은 성격이 다르다. **우선순위를 제안하고 확인받는다** — 넷을 같은 무게로 두면 CTA가 넷이 되고 페이지가 무너진다.
정리 방법은 다음 순서를 따른다.
1. 모순된 두 답을 그대로 나열한다(추측으로 하나를 지우지 않는다).
2. 먼저 온 답 또는 더 구체적인 답을 우선순위 후보로 제안한다.
3. "이렇게 이해했는데 맞나요"로 확인받는다. 확인 없이 임의로 하나를 폐기하지 않는다.
4. 확인된 우선순위를 브리프 세 줄과 `design.md`에 그대로 남긴다.
## 10. 무응답·비대화형·서브에이전트
- **한 번 실행하고 끝나는 실행(`claude -p`, `codex exec`)도 평문으로 묻고 끝낸다.** 구조화 도구로 답을 기다릴 수 없을 뿐, 최종 응답에 브리프 카드 초안과 번호 질문을 남기고 파일을 만들지 않은 채 끝낼 수는 있다. 답은 세션 재개나 다음 실행으로 온다.
- **자동 해제로 들어온 빈 답은 무응답으로 취급한다.** Codex의 autoResolution(60~240초 뒤 빈 답 자동 제출), Gemini CLI의 YOLO 모드에서 빈 답이 자동 통과되는 경우가 여기 해당한다. 이 빈 답을 어떤 선택지를 고른 것으로 해석하지 않는다.
- **서브에이전트로 실행 중이면 브리프 카드 초안과 질문을 호출자에게 반환하고 멈춘다.** 서브에이전트는 사용자에게 직접 물을 수 없으므로, 0단계는 반드시 메인 세션에서 끝낸다. 서브에이전트가 이 문서를 참조해 초안을 만들었더라도 그 초안은 확정이 아니다.
- **가정으로 진행하는 것은 질문이 오류·시간 초과·빈 답으로 끝났을 때뿐이다**(11절의 명시적 위임은 별도). 그때는 모든 가정에 라벨을 붙여 첫 응답에서 밝히고(마지막 응답이 아니라), 12절의 형식으로 `design.md` 미확정 목록에 올린다.
- **오케스트레이터가 워커에게 디자인 구현을 넘길 때는 브리프 카드를 작업 패킷에 포함한다.** 워커가 다시 사용자에게 묻는 일이 없도록, 확정된 슬롯과 미확정 가정을 함께 넘긴다.
## 11. 명시적 위임 예외
예외는 사용자의 명시적 위임뿐이다 — "알아서 해줘", "묻지 말고 진행" 같은 발화가 여기 해당한다. **"되돌리기 쉬운 습작"은 예외가 아니다.** 되돌리기 쉬움은 사용자가 판단할 몫이지, 모델이 되돌리기 쉬워 보인다는 이유로 인터뷰를 생략할 근거가 아니다.
위임을 받았을 때도 가정을 침묵 속에 진행하지 않는다.
1. 어떤 슬롯을 가정으로 채우는지 목록으로 말한다.
2. 12절의 형식으로 `design.md` 미확정 목록에 올린다.
3. 이후 사용자가 특정 슬롯을 정정하면 그 슬롯만 다시 확정 상태로 바꾼다.
## 12. 가정 기록 형식
`design.md`의 미확정 목록에는 아래 네 항목을 슬롯마다 한 행씩 적는다.
| 슬롯 | 가정한 값 | 근거 | 확인 필요 여부 |
|---|---|---|---|
| (3절 슬롯 이름) | (실제로 채택한 값) | (스캔한 파일·업종 평균·모델의 판단 중 무엇에서 나왔는지) | (예/아니오 — 다음 상호작용에서 반드시 확인해야 하면 예) |
근거 칸에 "모델의 판단"이라고 쓸 수밖에 없는 슬롯은 확인 필요를 항상 "예"로 둔다. 스캔한 파일이 근거면 파일 경로를 적는다.
## 13. 색 자산 확인
브랜드 자산은 3절 표에서 전체 경로의 필수 슬롯이다. 로고·간판·패키지·기존 토큰에 브랜드 색이 있으면 그것부터 확인한다. **파일로 확인되면 묻지 않는다.** 파일에 색이 없거나 사용자가 이미 "브랜드 색 없음"이라고 말했다면 그것도 확정으로 취급하고 다시 묻지 않는다. 그 외에는(파일도 없고 사용자 발화도 없으면) 묻는다.
- **기존 색이 있다** → 역할·대비·면적을 검토해 토큰에 반영한다. 반드시 강조색일 필요는 없다.
- **없다·상관없다(사용자가 확인함)** → 레퍼런스와 과업에서 색 역할을 정한다.
- **아직 확인되지 않았다** → 묻는다.
> 실측 사례: 꽃집 작업에서 색을 묻지 않고 레퍼런스 세 곳의 배경 평균(`#F8F6F0`)으로 정했다. 결과는 좋았지만 **운이 좋았던 것**이다. 브랜드 색이 있었다면 그걸 무시한 작업이 된다.
사진 자산의 유무와 조달은 [images.md](images.md) 4-0을 따른다.
## 14. 좁은 화면 내비
내비 구조는 항목 수만으로 정하지 않는다. 실제 라벨과 번역 길이, 글꼴 확대, 최소 화면 폭, 가장 중요한 이동 경로, 메뉴 깊이, 키보드 포커스 순서를 함께 본다. 한 줄·가로 스크롤·하단 바·여는 메뉴 중에서 그 조건에서 과업을 가장 덜 방해하는 방식을 고르고, 실제 좁은 화면과 확대 상태에서 검사한다.
여는 메뉴가 필요하다고 판단되면 [layout.md](layout.md)의 모바일 내비 절을 본다. 항목이 적어도 긴 번역·깊은 계층이면 여는 메뉴가 맞을 수 있고, 항목이 많아도 우선순위가 뚜렷하면 일부를 분리할 수 있다.
이 슬롯은 정보 구조·라벨이 정해진 뒤에만 물을 수 있으므로 8절에 따라 2라운드에서 묻는다. 판단 기준(라벨 길이·확대·폭·우선순위·깊이·포커스 순서)은 여기서 바뀌지 않는다.
## 15. 묻는 것과 묻지 않는 것
- **묻는다**: 결과를 바꾸는 결정(3절 슬롯), 사용자만 아는 사실(실제 수치·이름·재고·연락처 같은 것).
- **묻지 않는다**: 코드를 읽거나 검색하면 확인되는 사실.
이 스킬에는 "관례적으로 명확해서 묻지 않아도 되는" 디자인 결정이 없다는 것이 전제다. 무엇을 만들지, 누구에게 무엇을 시킬지, 어떤 인상을 줄지는 업종이 같아도 브랜드마다 다르다 — 관례를 근거로 질문을 생략하면 1절의 실측 사례처럼 넷 중 넷이 틀린다. 질문을 생략할 수 있는 유일한 근거는 "이미 코드·검색으로 확인했다"뿐이다.