design-workflow 스킬 디벨롭 기록 (2026-09-23)
AI 코딩 에이전트(Claude Code·Codex)가 화면·차트·덱 같은 시각 산출물을 만들 때 따르는 workflow 스킬을 2026-07-29에 처음 만들고 7주 동안 고쳐 왔다. 무엇으로 구성됐고, 왜 그렇게 됐고, 실제로 무엇이 좋아졌고, 무엇을 배웠는지 정리한다. 이 스킬은 앞으로도 계속 디벨롭할 것이라 이 글은 중간 기록이다.
0. 한 줄 요약
“에이전트는 사용자가 시안을 보고 고르기 전까지 제품 코드를 건드리지 않는다.” 이 한 문장을 지키게 만드는 데 스킬 전체가 쓰인다. 나머지는 이 문장을 우회하는 경로를 하나씩 막아 온 역사다.
1. 왜 만들었나
에이전트에게 “예쁘게 해줘”라고 하면 두 가지가 일어난다. 자기 취향으로 화면을 만든 뒤 보여주거나, 취향을 묻긴 하지만 ㄱㄱ 한마디를 “다 승인”으로 해석해 버린다. 둘 다 결과는 같다. 다 만들어진 뒤에 기각하고 코드를 되돌린다.
그래서 만든 첫 버전(2026-07-29)은 모드 5개(new/rebrand/refactor/small-feature/audit)와 조사·도구·검증 참조 5개짜리 155줄 스킬이었다. 그런데 같은 날 바로 두 번째 커밋이 들어갔다. “인터뷰를 권장한다”는 문구로는 안 됐기 때문이다. 당시 구현노트에 남은 판단이 이 스킬의 출발점이다.
단순 ‘인터뷰 권장’ 문구는 건너뛸 수 있으므로 STOP 조건, 승인 의미, gate evidence, 위반 복구까지 최상위 규칙으로 둔다.
이 커밋에서 신규·리브랜딩 절대 게이트 5단계가 생겼다. 제품 인터뷰 → 디자인 방향 인터뷰 → 시각 방향 3개 선택 → 고해상도 시안 정확히 3개 승인 → 구현 잠금 해제. 그리고 ㄱㄱ, 진행해, 알아서, 테스트니까 해봐는 “아직 보여주지 않은 방향이나 시안의 승인이 아니다”라는 문장이 들어갔다.
2. 지금의 구성
현재(2026-09-15 기준 최신 커밋) 규모는 다음과 같다.
| 구성 | 수 | 역할 |
|---|---|---|
SKILL.md | 337줄 | 모드·게이트·승인 판정·도구 기본값·규칙 소유·실행 순서 |
references/ | 17개 | 상황별 절차(업무 UI, 차트, 모션, 3D, 그래픽, 검증, 도구 권한 등) |
assets/ | 템플릿 4개 | PRODUCT.md, DESIGN.md, 게이트 증거, 감사 보고 |
scripts/ | 1개 | 보조 스킬(Taste·Impeccable) 프로젝트 로컬 설치 계획·적용·검증 |
| 전체 | 약 38,700 words | Claude와 Codex가 같은 소스를 읽는다 |
두 개의 축
작업은 변경 모드(무엇을 얼마나 바꾸나)와 주 목적(어떤 사이트인가) 두 축으로 분류한다.
- 모드 5개:
new/rebrand/refactor(보존형·전면교체형) /small-feature/audit(읽기 전용) - 주 목적 6개: 업무 UI / 커머스 / B2C / 데이터 대시보드 / 홍보·콘텐츠 / 그래픽·3D 체험
모드는 범위와 write 권한만 정한다. 강도는 정하지 않는다. small-feature라고 시안을 건너뛰거나 검증 매트릭스를 줄이지 않는다. 이 원칙이 왜 생겼는지는 4절에서 다룬다.
게이트와 승인의 정의
flowchart LR A["1 제품 인터뷰<br/>질문 하나씩"] --> B["2 디자인 방향 인터뷰"] B --> C["3 시각 방향 3개<br/>사용자 선택"] C --> D["4 고해상도 시안 정확히 3개<br/>승인/조합/수정/폐기"] D --> E["5 구현 잠금 해제<br/>Implementation unlocked: yes"] E --> F["제품 소스 수정"] style F fill:#e8f5e9
게이트 자체보다 중요한 것은 승인의 정의다. 세 조건을 모두 만족해야 승인이다.
- 메시지가 그 산출물(방향 3개, 시안 3개)을 제시한 뒤에 왔다.
- 내용이 그 산출물에 대한 결정(선택·승인·조합·수정·폐기·명시적 위임)으로 읽힌다.
- 보낸 주체가 사용자다. 모델·reviewer·subagent의 메시지는 승인이 아니다.
여기서 나온 규칙이 “보기 전 위임은 무효다”이다. 시안을 보여주기 전의 알아서 해는 착수 승인일 뿐이고, 보여준 뒤 AI 추천안까지 붙인 다음의 알아서 해만 위임이다. 같은 ㄱㄱ가 시점에 따라 다르게 해석되는 표가 SKILL.md에 11행짜리로 들어 있다.
subagent가 못 하는 것도 명시했다. 게이트 파일의 Real user answer 필드 채우기, 사용자 메시지를 승인으로 해석하기, Implementation unlocked: yes 기록하기, 사용자 대신 고르기. 사용자와 직접 대화하는 에이전트만 이걸 쓸 수 있다.
도구 기본값과 레거시 교체
2026-09-14부터 도구 기본값을 선언했다. 차트는 Bklit UI, UI 상태·전환은 Motion, 연출·타임라인은 Anime.js, 3D는 Three.js/R3F. 그리고 ECharts·Chart.js·Highcharts 등 기존 차트 엔진은 교체 대상으로 못 박고 7단계 이관 절차(인벤토리 → 호환 판정 → 대상 화면 이관 → parity → 전체 이관 제안 → 제거 → 완료 증거)를 넣었다. 과도기 보고는 반드시 "부분 적용: N/M 화면 이관, 나머지 제안 중" 형식이라 “적용 완료”라는 말로 1/5만 바꾼 상태를 감출 수 없다.
증거의 등급
검증 파트는 “무엇이 증거가 아닌가”를 나열하는 데 지면을 쓴다.
- 자동 검사, 직접 조작, reviewer 의견, 사용자의 미적 선택은 서로 다른 증거다.
- 설치돼 있다는 것과 구현에 사용됐다는 것을 구분한다.
- 문서·영상·소스 읽기·설치 성공은 준비 자료이며 관찰 완료가 아니다. 공식 예제를 브라우저에서 직접 조작하고 URL·행동·결과를 기록했을 때만 완료다.
- 대상이 없으면
N/A, 대상은 있는데 못 했으면미실행. 검증 계정이 없다는 이유는 N/A가 아니라 미실행이다.
규칙 소유 표
파일이 22개가 되자 같은 규칙이 여러 파일에 반복됐다. 중복을 금지하는 대신 “반복은 허용, 불일치는 금지, 충돌 시 소유 파일 우선”으로 정하고 규칙 → 소유 파일 표를 SKILL.md에 뒀다. 새 주 목적을 추가하면 고칠 8곳, 새 도구를 추가하면 고칠 7곳이 목록으로 있다.
3. 발전 과정
| 날짜 | 변화 | 동기 |
|---|---|---|
| 07-29 | v0 생성. 모드 5개, 참조 5개, 155줄 | 시각 작업의 공통 절차가 없었다 |
| 07-29 | 절대 게이트 5단계 + ㄱㄱ≠승인. 팀 플러그인 0.2.0에 contract test로 문구 고정 | ”권장”은 건너뛰어졌다 |
| 08-09~10 | 고객사 홈페이지 신규 디자인에 실전 적용. 시안 라운드 6회 | 아래 4절 |
| 08-23 | 전역 규칙 Rule 17. 프론트엔드·덱·리포트 전부 이 스킬 경유. “기본값은 사용이다. 건너뛰려면 근거를 한 줄로 밝힌다.” 경량 덱 모드는 만들지 않음 | 스킬이 있어도 호출이 안 됐다 |
| 09-08~09 | 고객사 ERP 목록 화면·로그인·알림 재설계에 적용 | 아래 4절 |
| 09-12 | 공개 SSOT 저장소로 컷오버 | 개인 정본 공개 |
| 09-14 | 웹 품질 개선(#4). 203→103줄로 슬림화, 주 목적 축 신설, audit 모드 설치 차단, 설치 스크립트 회귀 테스트 11개 | 사이트 목적별 도구 선택 기준 부재, audit에서 설치가 실행될 수 있었음 |
| 09-14 | 모션·3D·권한 인식(#8). 도구 기본값 선언, 무료/유료 기능 분리 | ”구독 중”이 API 접근을 뜻하지 않았고, 3D 초보에게 모델링 숙제를 넘기고 있었다 |
| 09-15 | 의도 구체화·그래픽 제작(#12). “화려하게”를 도메인에 맞는 연출 이름으로 번역, 영상·스크롤·게임형 전달 경로, 피드백 원인 분류 | 용어를 모르는 사용자의 요청 처리 |
| 09-15 | 승인된 체계 보존. 공식 예제 직접 관찰, 양방향 드리프트 방어 | 승인 뒤 확장 시 표현이 임의로 복원·제거됐다 |
| 09-15 | 성능 우선 재작업(#13). 103→338줄, 승인 해석표, 레거시 교체 절차, 규칙 소유 표, 업무 UI 참조 신설. 루브릭 8항목을 Claude Fable + Codex astra 교차 채점, 6.75 → 9.25 | ”효율이 아니라 성능. small-feature도 강도는 전부” |
| 09-22 | 블로그 뷰어 디자인에 보존형 refactor로 적용 | 게이트 N/A 근거와 detector before/after 표를 남김 |
4. 실질적으로 무엇이 좋아졌나
만족도 점수 같은 건 없다. 스킬 자체도 “만족도 향상을 실측 없이 단정하지 않는다”고 적혀 있다. 대신 기록에 남은 사실로 말한다.
기각이 코드 앞에서 일어난다. 고객사 홈페이지 신규 디자인은 시안 라운드가 6번 돌았다. R1 5개 컨셉 전부 기각, R2 5안 중 두 개 조합 지시, R3 3안 중 V3 채택, R4 3안 전부 기각 후 V3로 롤백, R5 보존형 refactor로 라이트 테마 승인, R6 본 개발. 기각된 시안이 11개인데 그동안 제품 소스는 잠겨 있었다(Application source writes: locked). 스킬이 없었으면 R1 시점에 코드로 만들고 R4까지 네 번 되돌렸을 것이다.
반려의 원인이 규칙이 됐다. ERP 목록 화면에서 조회 조건과 표를 한 카드에 넣은 결과가 반려됐다. 대응은 “대표 화면(채널 주문) 하나를 실제 코드로 만들어 확인받고, OK면 나머지 일괄 적용”이었고, 이것이 이후 카드 분리 리팩터링의 전 화면 적용 규칙(FilterCard와 표 Card 분리, one-card detector로 검출)이 됐다. 같은 실수를 화면 수만큼 반복하지 않았다.
증거 형식이 통일됐다. 블로그 디자인 작업 구현노트에는 impeccable detect before/after 표와 “인용문 왼쪽 선은 Obsidian 인용 관례이며 카드 accent가 아님”이라는 의도된 예외가 적혔다. 어떤 프로젝트든 같은 표가 남으니 나중에 “그때 뭘 확인했지”를 다시 조사하지 않는다.
두 에이전트가 같은 규칙을 읽는다. Claude Code는 ~/.claude/skills/design-workflow 심링크로, Codex는 agents/openai.yaml 진입점으로 같은 디렉토리를 본다. 팀 플러그인은 contract test가 “고해상도 시안 세 개”, “Implementation unlocked” 같은 문구를 고정해서 배포본이 정본과 어긋나면 테스트가 깬다.
비용도 있다. new 모드는 인터뷰 항목을 한 질문씩 묻기 때문에 최소 14턴이 든다. SKILL.md만 6,500 words라 매 세션 컨텍스트에 들어간다. 토큰 효율 진단에서 확인했듯 비용은 컨텍스트 크기가 결정하므로, 이 스킬은 의도적으로 정확도를 사고 토큰을 쓰는 쪽이다.
5. 교훈
- “권장”은 건너뛰어진다. STOP 조건, 승인의 의미, 기록 필드, 위반 시 복구까지 규칙으로 써야 지켜진다. 첫날 두 번째 커밋에서 배웠다.
- 승인은 시점 + 내용 + 주체다. 이 셋을 분리하지 않으면
ㄱㄱ한마디가 모든 게이트를 통과한다. “보기 전 위임은 무효”가 가장 많은 사고를 막은 문장이다. - 모드는 범위만 정하고 강도는 정하지 않는다. 초기엔
small-feature에 “변경 강도 낮음”을 줬다. 그 결과 작은 작업에서 시안·검증이 생략되고 스타일이 조금씩 새는 드리프트가 생겼다. 09-15에 이 열을 지우고 “범위는 좁게, 강도는 전부”로 역전시켰다. - 슬림화와 재확장은 진자다. 203줄 → 103줄(상세를 전부 조건부 참조로) → 338줄(판정 규칙을 본문으로 재승격). 참조로 빼면 본문에 “언제 어느 파일을 읽나”만 남고 판정이 사라진다. 지금 결론은 본문은 판정, 참조는 절차다.
- 중복은 허용하되 소유자를 하나 둔다. 22개 파일에서 중복을 없애는 건 불가능했다. 대신 소유 파일과 “같은 숫자·순서·용어” 규칙을 뒀다. 단 자동 검사가 없어 이게 지금 가장 큰 약점이다.
- 읽는 것은 관찰이 아니다. 문서·설치·정지 스크린샷을 근거로 “확인했다”고 쓰는 일이 반복됐다. 증거 등급을 나누고 브라우저 직접 조작만 관찰로 인정하게 했다.
- 드리프트는 양방향이다. 승인된 질감·모션을 “업무 UI라서” 지우는 것도, 공식 예제의 색을 “예제라서” 가져오는 것도 드리프트다. 승인 패턴 재사용 / 기존 코드 패턴(미승인) / 새 표현 세 갈래로 판정한다.
- 프로젝트 취향을 전역 규칙으로 만들지 않는다. “밋밋하다” 한마디로 스킬을 고치면 다른 프로젝트가 오염된다. 재현된 지침 결함만 반영한다.
- 다중 모델 교차 채점은 유효하되 목표엔 못 미쳤다. Fable과 Codex astra가 같은 루브릭으로 채점하니 결함이 36 → 26 → 17로 줄었다. 하지만 두 리뷰어의 처방이 다를 때 Lead가 단일 문장을 정해 배포하지 않으면 점수가 안 오른다. 9.5 목표는 9.25에서 사용자 지시로 종료했다.
- 템플릿과 실사용이 다르다.
DESIGN.md템플릿은 274줄인데 실제 프로젝트에DESIGN.md파일은 하나도 없다. 게이트 기록은 전부 구현노트 안의# Design gate evidence절로 썼다. 템플릿이 실제 쓰임을 따라가야 한다.
6. 다음에 손볼 것
현재 구조를 비판적으로 읽었을 때 나온 후보다. 우선순위는 미정이다.
- SKILL.md 슬림화: 레거시 차트 절이 SKILL.md에 13줄이나 있고 같은 문장이 6개 파일에 41회 복제돼 있다. 소유 파일에만 두고 본문은 링크로.
- 문구 동기화 검사 스크립트: 규칙 소유 표를 자동으로 검증할 수단이 없다.
- 예시 결손: 대표 흐름이 S1·S2·S5뿐이다. S3·S4가 비어 있고
new전체 흐름·3D·덱·audit 예시가 없다. frontend-design·dataviz스킬과의 우선순위: 범위가 가장 겹치는 두 스킬만 관계가 정의돼 있지 않다.audit경계의 소유 모순: 읽기 전용 금지 목록이 15곳에 흩어져 있는데 소유 파일의 목록이 가장 짧다.new모드의 턴 폭증: 요약 확인 라운드가 저장소 증거를 전제해서 정작 신규 제품에서는 작동하지 않는다.- Bklit 단일 벤더 리스크: 재검토 조건과 shadcn 버전 고정이 없다.
small-feature용DESIGN.md최소 프로필: 274줄 템플릿 중 어디까지 채울지 명시.- 팀 플러그인 0.3.0 push: 로컬 커밋만 있고 GitLab 인증 문제로 push가 안 됐다.
이 스킬의 정본은 공개 저장소 oyuns-wishket/ai-working의 skills/design-workflow/다. 위 이력의 근거는 그 저장소의 docs/impl-notes/ 구현노트 4편과 GitHub 이슈 #4·#8·#12·#13, 그리고 개인 wiki의 세션 record다.