이 장이 끝나면: 우리 팀의 첫 서브에이전트(Subagent) 인 디자인 리뷰어가 만들어져 있다. 이 리뷰어는 고칠 도구 자체가 없어서 지적만 할 수 있고, 홈 화면 시안의 세 가지 화면 폭(1440·768·375) 스크린샷을 등급으로 리뷰한다. "네가 직접 고쳐봐"라고 시켜서 못 고치는 것을 눈으로 확인하는 권한 시험까지 한다.
시안을 만든 디자이너(스킬)에게 "방금 만든 화면 검토해봐"라고 하면 어떻게 될까. 대체로 후한 평가가 돌아온다. 아부가 아니다 — 같은 선입견으로 만들고 같은 선입견으로 보기 때문이다. 만들 때 "이 정도면 균형 잡혔다"고 판단한 그 기준으로 검토하니, 같은 결론이 나올 수밖에 없다.
이 현상에는 이름이 있다. 사람이 자기가 내린 판단을 다시 볼 때, 그 판단이 옳다는 증거만 눈에 들어오고 반대되는 증거는 흐릿해지는 경향을 확증 편향(confirmation bias) 이라 한다. 디자이너 스킬도 마찬가지다. "포인트 색을 여기에 썼다"는 결정을 내린 주체가 그 화면을 다시 보면, 그 결정을 정당화하는 방향으로 화면을 읽는다. 자기가 쓴 글에서 자기 오타를 못 잡는 것과 정확히 같은 원리다 — 머릿속에 '있어야 할 글자'가 이미 있으니, 눈은 그것을 본다. 만든 사람의 눈은 '만들려던 것'을 보고, 검토하는 사람의 눈은 '실제로 있는 것'을 본다.
사람으로 이루어진 조직은 이 문제를 오래전부터 알았고, 답도 오래전에 냈다 — 만든 사람과 검사하는 사람을 분리한다. 회계팀이 아니라 감사팀이 장부를 본다. 개발자가 아니라 QA가 검수한다. 기자가 쓴 기사를 데스크가 본다. 원고를 저자가 아니라 편집자가 교정한다. 분리 자체가 품질 장치다.
이 원리가 얼마나 뿌리 깊은지 몇 가지만 더 보자. 회사의 재무제표는 그 회사 회계팀이 아니라 외부 회계법인이 감사한다 — 만든 회사와 검사하는 법인이 남남이어야 감사가 성립한다. 비행기는 정비사가 점검을 마치면 다른 정비사가 같은 항목을 다시 확인한다(이중 점검). 병원에서 고위험 약을 투여하기 전, 준비한 간호사와 다른 간호사가 용량을 다시 읽는다. 학술 논문은 저자가 아니라 이해관계 없는 심사자들이 검증한다(피어 리뷰). 소프트웨어에서도 코드를 짠 사람이 아니라 동료가 그 변경(Pull Request)을 검토한다. 공통점은 하나다 — 판단을 내린 주체는 그 판단의 심판이 될 수 없다. 그래서 조직은 '검토하는 사람'을 아예 다른 자리에 앉힌다.
우리 AI 팀도 같은 구조를 만든다. 시안은 디자이너 스킬이 만들고, 검토는 별도의 서브에이전트가 한다.
[짚고 가기] 이 절의 핵심은 "리뷰어가 더 똑똑해서 분리하는 게 아니다"라는 점이다. 같은 모델(Claude)이 만들고 같은 모델이 리뷰한다 — 두뇌는 동일하다. 분리가 힘을 갖는 건 역할과 시야를 갈랐기 때문이다. 만든 맥락에서 떼어 내 "너는 오직 흠을 찾는 사람"이라는 자리에 앉히면, 같은 두뇌라도 다른 것을 본다. "어차피 같은 AI인데 의미가 있나" 하고 헷갈리기 쉬운데, 바로 이 지점이 답이다.
디자인 리뷰어에게는 특별한 점이 하나 더 있다. 화면을 눈으로 본다는 것이다. 코드(HTML/CSS)를 읽는 것만으로는 절대 알 수 없는 문제들이 있기 때문이다.
코드는 전부 '정상'이다. 화면이 이상할 뿐이다. 왜 이런 일이 생기냐면, 화면의
최종 모습은 코드 한 줄이 결정하는 게 아니라 여러 값이 브라우저 안에서 만나
계산된 결과이기 때문이다. 글자 길이, 화면 폭, 글꼴, 줄바꿈 규칙, 이미지 로딩
여부가 그 순간 함께 작용해 배치가 정해진다. .card { height: auto } 라는
한 줄은 코드로는 완벽하게 옳지만, 실제로 카드 세 개에 담긴 글자 수가 다르면
높이가 제각각이 된다. 코드를 아무리 읽어도 "고객 화면에서 실제로 어떻게 보이는가"는
알 수 없다. 그건 렌더링해서 눈으로 봐야만 안다.
그래서 리뷰어에게는 코드가 아니라 렌더링된 화면의 스크린샷을 준다. 그것도 세 가지 폭으로 — 데스크톱(1440px), 태블릿(768px), 휴대폰(375px). 화면은 보는 기기에 따라 다르게 배치되므로 (이를 반응형이라 한다), 한 가지 폭만 보고 통과시키면 나머지 두 폭의 사고를 놓친다. 온티켓 고객의 대부분은 휴대폰으로 예매한다는 점을 기억하자.
'렌더링(rendering)'이라는 말도 짚어 두자. 코드(설계도)를 실제 화면(그림)으로 그려 내는 과정을 렌더링이라 한다. 브라우저가 하는 일이 바로 이것이다 — HTML과 CSS라는 글자 명세를 받아, 픽셀로 칠해진 화면으로 바꾼다. 같은 코드라도 브라우저와 화면 폭에 따라 렌더링 결과가 달라지기 때문에, "코드가 맞다"와 "화면이 맞다"는 서로 다른 검증이다. 리뷰어가 담당하는 건 후자다.
[짚고 가기] 겹침·잘림·대비·정렬은 말로만 설명하면 잘 안 와닿는다. 실제로 홈 시안을 크롬에서 열고 폭을 375로 줄여 보면, 가격이나 긴 제목이 깨지는 순간이 눈에 들어온다 — "아 이래서 눈으로 보는구나"가 바로 와닿는 지점이다. 카드 하나에 일부러 아주 긴 공연 제목을 넣어 두면 겹침을 직접 재현해 보기 쉽다.
바로 앞에서 디자이너는 스킬(Skill) 로 만들었는데, 이번 리뷰어는 서브에이전트(Subagent) 로 만든다. 둘 다 "역할을 정의한 마크다운 파일"이라는 점은 같지만, 결정적인 차이가 하나 있다.
| 스킬(Skill) | 서브에이전트(Subagent) | |
|---|---|---|
| 파일 위치 | .claude/skills/<이름>/SKILL.md |
.claude/agents/<이름>.md |
| 실행 방식 | 지금 대화하는 Claude가 그 지침을 직접 따른다 | 독립된 일꾼이 자기 창(맥락)에서 따로 일한다 |
| 도구 권한 | 부르는 쪽(사람)이 가진 도구를 함께 쓴다 | 자기만의 도구 목록을 가진다 (tools로 제한) |
| 비유 | 내가 참고하는 '업무 매뉴얼' | 매뉴얼을 들고 옆방에서 일하는 '다른 직원' |
핵심은 서브에이전트는 도구 권한을 따로 가진다는 것이다. 이게 이 장 전체의 열쇠다. 디자이너 스킬은 부르는 Claude와 같은 손(도구)을 쓰므로 편집도 할 수 있지만, 리뷰어 서브에이전트는 자기 손에 편집 도구가 아예 없게 만들 수 있다. "고치지 마"라는 부탁이 아니라 "고칠 손이 없다"는 구조 — 이것이 스킬이 아니라 서브에이전트로 리뷰어를 만드는 이유다.
'서브(sub)'는 '아래·하위'라는 뜻이다. 사람이 큰 목표를 주고 메인 Claude가 일을 진행하다가, 특정 검토가 필요하면 그 일부를 하위 일꾼(서브에이전트) 에게 떼어 맡긴다. 서브에이전트는 자기 몫의 일을 자기 창에서 마치고, 결과(리포트)만 메인에게 돌려준다. 옆방 직원에게 "이 서류만 검토해서 결과지 갖고 와"라고 시키는 것과 같다. 그 직원의 책상에는 우리가 허락한 도구만 놓여 있다.
서브에이전트는 .claude/agents/<이름>.md 파일 하나로 정의된다.
맨 위 머리말(frontmatter)에 세 가지를 적는다.
| 항목 | 역할 |
|---|---|
name |
서브에이전트의 이름 (호출할 때 쓰인다) |
description |
언제 이 에이전트에게 일을 맡길지 — Claude가 이걸 보고 위임을 판단한다 |
tools |
이 에이전트가 쓸 수 있는 도구 목록 — 여기가 권한 설계의 핵심이다 |
'머리말(frontmatter)'은 문서 맨 앞에 --- 두 줄 사이로 끼워 넣는 설정
구역이다. 본문이 사람에게 주는 지시라면, 머리말은 시스템에게 주는 메타 정보다.
블로그 글 맨 위에 제목·작성일·태그를 적어 두는 칸을 떠올리면 된다. 세 항목의
성격을 나눠 보면 이렇다.
name 은 이 일꾼의 식별표다. design-reviewer처럼 하는 일이 드러나는
이름을 준다. 나중에 "design-reviewer한테 맡겨줘"라고 부를 때 이 이름을 쓴다.description 은 언제 부를지를 적은 안내문이다. 사람이 명시적으로 부르지
않아도, 메인 Claude가 "이건 디자인 검토구나" 하고 알아서 위임할 수 있게 하는
힌트다. 그래서 "디자인 리뷰, 시안 검토, 화면 QA"처럼 불릴 만한 상황의
단어들을 넉넉히 적어 두는 게 좋다.tools 는 이 일꾼의 책상 위 연장 목록이다. 여기에 적힌 것만 쓸 수 있고,
적지 않은 것은 존재조차 하지 않는다. 리뷰어 설계의 전부가 사실상 이 한 줄에 있다.tools 칸에 적는 도구들의 이름과 능력을 알아 두자. 이 조합이 곧 권한이다.
| 도구 | 능력 | 리뷰어에게 주나? |
|---|---|---|
| Read | 파일을 읽는다 (이미지·스크린샷도 읽는다) | 준다 |
| Grep, Glob | 파일 내용·이름을 검색한다 | 준다 |
| Edit | 기존 파일을 고친다 | 안 준다 |
| Write | 새 파일을 만든다·덮어쓴다 | 안 준다 |
| Bash | 터미널 명령을 실행한다 | 안 준다 (리뷰에 불필요) |
Read가 이미지를 읽을 수 있다는 점이 이 장의 기술적 열쇠다. 스크린샷 파일을 폴더에 넣어 주면, 리뷰어가 그 이미지를 '보고' 리뷰한다.
이게 가능한 이유는 Claude가 멀티모달(multimodal) 모델이기 때문이다.
'모달(modal)'은 정보의 양식·형태를 뜻하는데, 글자만 다루면 단일 양식(텍스트)이고,
글자와 그림을 함께 다루면 여러 양식 — 멀티모달이다. Read 도구가 .png 파일을
읽으면, 그 안의 픽셀을 Claude가 '본다'. 그래서 "이 스크린샷에서 가격이 잘렸다"
같은 판단을 코드 없이 이미지만으로 할 수 있다. 리뷰어에게 스크린샷을 주는 것이
헛일이 아니라, 실제로 눈 역할을 하는 이유가 여기 있다.
도구를 좀 더 풀어 두자. 초보자에게는 이름만으로 능력이 안 그려진다.
tokens.css·금지목록.md(글자)를 둘 다 이걸로 읽는다.grep에서
왔다. 읽기 계열이라 리뷰어에게 줘도 안전하다.home-*.png처럼 별표(와일드카드)를
써서 "스크린샷 폴더에 폭별 파일이 다 있나"를 확인하는 데 쓴다. 역시 읽기 계열이다.여기서 관통하는 생각이 최소 권한 원칙(least privilege) 이다. 보안·시스템 설계의 오랜 격언으로, "그 일에 꼭 필요한 권한만 주고 나머지는 주지 않는다"는 뜻이다. 리뷰어는 읽고 검색만 하면 일이 되므로 Read·Grep·Glob만 준다. Edit·Write·Bash를 "혹시 필요할까 봐" 얹어 두는 순간, 리뷰어는 '고칠 수 있는 리뷰어'가 되어 이 장의 목적을 스스로 무너뜨린다. 권한은 넉넉히가 아니라 딱 필요한 만큼이 정답이다.
두 가지 방법이 있다. 명시적으로 부르거나 —
design-reviewer 서브에이전트한테 design/screenshots/ 의 스크린샷 리뷰를 맡겨줘.
또는 그냥 "시안 리뷰해줘"라고 하면 Claude가 description을 보고 알아서 그 에이전트에게 위임한다. 실습에서는 명시적으로 부른다 — 어느 에이전트가 일하는지 눈으로 확인하기 위해서다.
두 방식의 차이를 실무 감각으로 정리하면 이렇다. 명시 호출은 "김 대리, 이거
검토해"라고 사람을 콕 집는 것이고, 자동 위임은 "이 서류 검토 좀"이라고만 해도
매니저가 알아서 담당자에게 넘기는 것이다. 자동 위임이 편하긴 하지만, 배우는
단계에서는 누가 무슨 권한으로 일하는지 눈에 보이는 것이 더 중요하다. 그래서
실습 내내 이름을 직접 불러, "지금 일하는 건 편집 권한 없는 리뷰어다"를 매번
확인한다. description을 잘 써 두는 것은 나중에 자동 위임이 정확히 걸리게
하기 위한 투자다.
지적에 무게를 매기는 표준적인 방법이다. 등급이 없으면 "고칠 게 12개"라는 목록 앞에서 무엇부터 할지 알 수 없다.
| 등급 | 뜻 | 처리 규칙 |
|---|---|---|
| Blocker | 이대로 내보낼 수 없다 (기능·신뢰 훼손) | 반드시 고친다 |
| Major | 품질을 뚜렷이 해친다 | 웬만하면 고친다 |
| Minor | 다듬으면 좋다 | 사람이 취사선택한다 |
'등급(severity)'은 원래 '심각도'라는 뜻이다. 소프트웨어 현장에서는 버그가 발견되면 가장 먼저 이 심각도를 매긴다 — 서비스가 멈추는 버그와 오타 하나는 같은 급으로 다룰 수 없기 때문이다. 회사마다 이름은 달라도(P0/P1/P2, S1/S2/S3, Critical/High/Low) 구조는 똑같다: 얼마나 급한가로 줄을 세운다. 등급을 매기는 행위 자체가 "무엇부터 손댈지"를 자동으로 정렬해 준다. 우리는 디자인 지적에도 같은 삼단 구조를 쓴다.
셋의 경계를 감각적으로 잡아 두면 리뷰어가 등급을 흔들리지 않게 매긴다.
경계가 애매한 지적은 리뷰어에게 근거로 판단하게 시킨다. "이 문제가 예매를 막는가? → 막으면 Blocker"처럼, 등급의 기준을 '기능·신뢰에 주는 타격'으로 못 박아 두면 리뷰어마다·요청마다 등급이 출렁이는 것을 막을 수 있다.
반응형(Responsive) 은 하나의 화면이 보는 기기의 폭에 맞춰 배치를 스스로 바꾸는 설계 방식이다. PC의 넓은 화면에서는 카드를 가로로 네 개 늘어놓다가, 휴대폰의 좁은 화면에서는 세로로 한 줄씩 쌓는 식이다. 같은 페이지가 기기에 '반응(respond)'해 다른 모습이 된다고 해서 반응형이다. 종이 신문은 폭이 고정이지만, 웹은 고객이 어떤 기기로 볼지 모르므로 폭에 반응하도록 만든다.
숫자 1440·768·375는 화면의 가로 폭을 픽셀(px)로 나타낸 값이다. 픽셀은 화면을 이루는 점 하나의 단위로, 폭이 375px라면 "가로로 점 375개만큼 넓은 화면"을 뜻한다. 이 세 숫자는 아무렇게나 고른 게 아니라 가장 흔한 세 종류의 기기를 대표한다.
| 폭 | 대표 기기 | 왜 이 폭을 보나 |
|---|---|---|
| 1440px | 노트북·데스크톱 | 카드가 가장 넓게 펼쳐지는 배치. 여백·정렬이 잘 보인다 |
| 768px | 태블릿(가로 세로 중간) | 배치가 바뀌는 전환 구간. 여기서 레이아웃이 자주 깨진다 |
| 375px | 휴대폰(대표적인 좁은 폭) | 온티켓 고객 대다수. 잘림·겹침이 가장 잘 터진다 |
폭이 바뀔 때 배치를 갈아타는 경계 지점을 브레이크포인트(breakpoint) 라 한다. "폭이 768px보다 좁아지면 카드를 한 줄로 바꿔라" 같은 규칙에서 768이 브레이크포인트다. 세 폭을 고른 이유가 여기서 분명해진다 — 넓은 쪽 하나(1440), 좁은 쪽 하나(375), 그리고 둘이 갈리는 전환 구간(768). 사고는 대개 이 전환 구간과 가장 좁은 폭에서 터지므로, 세 장이면 화면이 깨지는 대부분을 잡아낸다. 하나만 보고 통과시키면 나머지 폭의 사고를 통째로 놓친다.
[짚고 가기] "왜 하필 이 세 숫자냐"가 궁금해지기 쉬운데, 정답이 정해진 값은 아니고 업계에서 흔히 쓰는 대표값이다. 중요한 건 숫자 자체가 아니라 넓게·전환·좁게 세 지점을 본다는 원리다. 회사 서비스라면 실제 접속 통계에서 가장 많은 폭을 넣는 게 맞다 — 이 실무 감각까지 챙겨 두면 좋다.
네 칸으로 설계하면 이렇다. 판단 기준: 온티켓의 토큰과 금지 목록이 곧 법이다. 금지 목록: 고치는 행위 일체. 프로세스: 세 폭을 모두 보고, 등급과 근거를 붙인다. 도구 권한: 읽기와 검색만.
역할 정의의 원리에서 익힌 '네 칸'을 리뷰어에 대입해 다시 펼치면 이렇다. 이 네 칸이 채워지면 역할이 완성된다.
| 칸 | 리뷰어의 경우 | 왜 이렇게 |
|---|---|---|
| 판단 기준 | tokens.css·금지목록.md가 판정의 근거. 화면이 갖춰야 할 요소와 상태는 docs/화면기획서.md가 근거 |
취향이 아니라 우리가 정한 규칙으로 판단해야 결과가 흔들리지 않는다 |
| 프로세스 | 세 폭을 모두 확인, 지적마다 위치·근거·등급 | 빠짐 없이 보고, 지적이 검증·처리 가능한 형태가 되게 한다 |
| 금지 | 고치는 행위 일체(제안 코드 포함) | '검토하는 사람'의 독립성을 지킨다. 손대는 순간 만든 사람이 된다 |
| 도구 권한 | Read·Grep·Glob만 | 금지를 부탁이 아니라 구조로 강제한다 |
눈여겨볼 것은 금지 칸과 도구 권한 칸이 같은 목표를 이중으로 지킨다는 점이다. 금지 칸은 지침(말)으로 "고치지 마라"라고 하고, 도구 권한 칸은 구조(손)로 "고칠 수 없게" 만든다. 지침만 있으면 부탁이고, 구조까지 있어야 보장이다. 이 장의 실습에서 하는 권한 시험이 확인하는 것이 바로 이 이중 잠금이 실제로 걸렸는가다.
이를 파일로 옮긴 전문이다. (실습에서 Claude Code에게 만들게 시킨다.)
---
name: design-reviewer
description: 온티켓 화면·시안의 스크린샷을 검토할 때 사용한다.
디자인 리뷰, 시안 검토, 화면 QA 요청이 오면 이 에이전트에 위임한다.
tools: Read, Grep, Glob
---
너는 (주)승승장구 온티켓의 디자인 리뷰어다. 너의 산출물은 수정이 아니라
등급이 매겨진 지적이다.
## 판단 기준
- design/tokens.css 와 design/금지목록.md 가 판정의 근거다
- docs/화면기획서.md 의 "화면별 요소와 상태"에 적힌 것이 시안에 있는지 대조한다
(예: 매진이면 예매 버튼이 비활성으로 보이는가)
- 세 가지 폭(1440·768·375)을 전부 확인한다. 하나라도 빠지면 리뷰를 시작하지
말고 빠진 스크린샷을 요청하라
- 취향이 아니라 근거로 말한다. 모든 지적에는 "무엇이(위치) — 왜(근거)"를 붙인다
## 리포트 형식
| 등급 | 위치(화면 폭 포함) | 문제 | 근거(토큰/금지목록 조항/가독성) |
마지막 줄에 종합 판정: 통과 / 조건부 통과(Blocker 0, Major 있음) / 반려(Blocker 있음)
## 금지
- 코드를 고치지 않는다. 고침을 제안하는 코드 조각도 쓰지 않는다 —
결정은 디자이너와 사람의 몫이다
- 근거 없는 지적("느낌이 아쉽다")을 하지 않는다
이 파일을 한 줄씩 다시 읽어 보면 설계 의도가 드러난다.
tools: Read, Grep, Glob — 이 한 줄이 리뷰어의 정체성이다.
Edit·Write·Bash가 없으니 물리적으로 고칠 수 없다. 나머지 본문이 아무리
느슨해도 이 한 줄이 '검토하는 사람'의 독립성을 보장한다.[짚고 가기] 직접 만든 파일에서 가장 자주 틀어지는 곳이 두 군데다. (1)
tools:에 습관적으로 Edit이나 Write가 끼어드는 것, (2) 리포트에 종합 판정 줄이 빠지는 것. 생성 직후 이 두 줄을 함께 확인하는 습관을 들이면 뒤(권한 시험)에서 사고가 안 난다.tools:줄은 특히 한 자 한 자 눈으로 짚어 두면 좋다.
디자인만의 이야기가 아니다. 읽기 전용 검토자는 만들 수 있는 곳이 많다.
공통 패턴이 보일 것이다 — 원본을 지킬 필요가 있는 모든 검토에는 '읽기 전용 + 등급 리포트' 조합이 통한다.
각각을 조금 더 구체적으로 그려 보면, 이 패턴이 왜 강력한지 실감이 난다.
tools: Read, Grep만 준다. 오탈자와 용어 불일치(같은
대상을 '고객'과 '사용자'로 섞어 쓰는 것 등)를 Blocker/Major/Minor로 매겨
리포트한다. 원문을 고칠 손이 없으니, 검토자가 저자의 문장을 몰래 자기 취향으로
바꿔 놓는 사고가 원천 봉쇄된다. 반영은 저자가 한다.이 사례들의 공통 구조는 세 가지다. (1) 지켜야 할 원본이 있고, (2) 검토자에게 읽기·검색 권한만 주며, (3) 결과는 등급이 붙은 리포트로 받는다. 온티켓의 디자인 리뷰어는 이 범용 패턴의 한 사례일 뿐이다. 이 장을 마치면, 여러분은 어느 도메인에서든 '고칠 수 없는 검토자'를 찍어 낼 템플릿을 손에 쥐게 된다.
design-reviewer 서브에이전트에게 맡겨줘:
design/screenshots/ 안의 home-1440.png, home-768.png, home-375.png 를
tokens.css·금지목록.md 기준으로 리뷰하고 등급 리포트를 달라고.
docs/화면기획서.md 에 적힌 홈 화면의 요소와 상태(예: 매진 시 버튼 비활성)가
시안에 빠짐없이 있는지도 함께 봐달라고.
이 요청이 좋은 이유를 뜯어 보자. 대상(어느 파일 세 장), 재료(무슨 기준으로), 산출물 형식(등급 리포트)이 다 들어 있다. 리뷰 요청에서 이 세 가지가 빠지면 어떻게 어긋나는지 표로 보자.
| 약한 요청 | 무엇이 빠졌나 | 강한 요청 |
|---|---|---|
| 시안 리뷰 좀 해줘 | 대상·재료·형식 전부 | 위 프롬프트처럼 파일·기준·형식을 명시 |
| 스크린샷 봐줘 | 어느 파일인지, 기준이 뭔지 | home-1440/768/375를 tokens·금지목록 기준으로 |
| 문제 있으면 알려줘 | 산출물 형식(등급·근거) | 등급·위치·근거 표 + 종합 판정으로 달라고 |
| 예쁜지 봐줘 | 판정 기준이 취향이 됨 | 토큰/금지목록 조항 위반 여부로 판정하라고 |
핵심은 판정 기준을 사람의 취향이 아니라 파일(토큰·금지목록)에 묶는 것이다. "예쁜지 봐줘"라고 하면 리뷰어가 자기 취향으로 판정해 근거 없는 지적이 나온다. "토큰·금지목록 기준으로"라고 못 박으면, 모든 지적이 "몇 번 조항 위반"이라는 검증 가능한 형태로 나온다.
리뷰 요청의 마지막 두 줄은 기준 파일을 하나 더 묶는다. 토큰과 금지목록은 "어떻게 보여야
하는가"의 기준이고, docs/화면기획서.md는 "무엇이 있어야 하는가"의 기준이다.
기획서에 "매진이면 예매 버튼 비활성"이라고 적혀 있는데 시안에 그 상태가 없다면,
색과 간격이 아무리 말끔해도 그 화면은 덜 만들어진 것이다. 리뷰어는 이 빠짐도
위치와 근거(기획서의 어느 화면, 어느 상태)를 붙여 지적한다.
리포트가 오면 기계적으로 전부 반영하지 않는다. 처리 규칙은 등급으로 정한다 — Blocker는 반드시, Major는 웬만하면, Minor는 사람이 고른다. 리뷰어의 지적은 정보이지 명령이 아니다. 최종 결정은 언제나 사람 몫이다.
이 "정보이지 명령이 아니다"가 실무에서 특히 중요하다. 리뷰어가 12개를 지적했다고 12개를 다 반영하면, 리뷰어가 사실상 디자인을 결정한 셈이 된다. 등급은 그 지적들을 줄 세워 사람이 판단할 여지를 만든다. Minor 5개는 오늘 시간이 없으면 다음으로 미룰 수 있고, 취향에 안 맞으면 안 고쳐도 된다. 반대로 Blocker는 취향 문제가 아니라 기능·신뢰의 문제라 미룰 수 없다. 등급이 곧 "무엇이 협상 가능하고 무엇이 불가능한가"의 지도다.
한 가지 더 — 리뷰어의 판정에 사람이 반론할 수 있다. "이건 Blocker가 아니라 Minor다"라고 판단되면, 그렇게 재분류하면 된다. 다만 그럴 때도 근거로 다툰다.
리포트의 [Major/768px] 카드 높이 불일치는 우리 화면에선 의도된 거야.
공연 정보량이 카드마다 다른 게 자연스럽거든. 이건 Minor로 낮추고,
대신 높이가 아니라 카드 사이 세로 간격이 균일한지를 봐줘.
지적을 반영할 때 흔한 실수 — 리뷰어에게 "그럼 고쳐줘"라고 하는 것. 우리 리뷰어는 고칠 수 없다(도구가 없다). 반영은 만드는 역할의 일이다.
/designer 리뷰 리포트의 Blocker 2건과 Major 1건을 반영해줘.
- [Blocker/375px] 가격 잘림 → 카드 레이아웃 조정
- [Blocker/1440px] 본문 회색 대비 부족 → 회색 토큰 값을 한 단계 밝게 (토큰 수정 제안부터)
- [Major/768px] 카드 높이 불일치 → 높이 고정
반영 후 뭘 바꿨는지 목록으로 보고해.
이 반영 지시가 잘 쓰인 이유가 있다. 어느 지적을(등급·위치) 반영할지 골라 주고, 어떻게 접근할지의 방향만 주되 세부 방법은 디자이너에게 맡겼으며, 마지막에 바뀐 것을 보고하게 했다. 특히 회색 대비 건에서 "토큰 수정 제안부터"라고 한 것을 눈여겨보자 — 디자이너 스킬의 기준 자료 원칙(색은 화면이 아니라 토큰에서)을 지키게 하는 장치다. 화면에 색을 몰래 바꾸는 게 아니라 토큰 값을 고쳐, 그 색을 쓰는 모든 곳이 함께 바뀌게 한다.
여기서 역할의 왕복 구조가 완성된다. 리뷰어(본다) → 사람(고른다) → 디자이너(고친다). 셋이 서로 다른 자리에 앉아 있고, 각자 자기 권한만큼만 한다. 리뷰어는 지적하되 못 고치고, 디자이너는 고치되 자기 결과를 스스로 통과시키지 못하며, 사람은 무엇을 반영할지 결정한다. 이 삼각형이 품질이 만들어지는 최소 단위다.
역할이 정말 작동하는지는 시험해 봐야 안다. 리뷰어에게 일부러 수정을 시켜 보라.
design-reviewer 서브에이전트에게: 방금 지적한 것들, 네가 직접 home.html을 고쳐놔.
제대로 만들어졌다면 리뷰어는 고치지 못한다 — 편집 도구가 없기 때문이다. 이 실패를 눈으로 보는 것이 중요하다. "고치지 말라고 부탁해서" 안 고치는 것과 "고칠 수단이 없어서" 못 고치는 것의 차이. 시험해 보지 않은 권한 설계는 설계가 아니라 희망이다.
이 차이를 조금 더 파 보자. 지침만으로 막는 것("고치지 마라"라고 본문에 적기)은 부탁이다. 부탁은 대체로 지켜지지만, 지시가 강하거나 맥락이 꼬이면 뚫릴 수 있다. 반면 도구를 뺀 것은 구조다. Edit이 목록에 없으면 리뷰어는 그 도구를 호출할 방법 자체가 없다. "고치고 싶어도 손이 없는" 상태다. 우리가 원하는 건 부탁이 아니라 구조다. 권한 시험은 바로 부탁이 아니라 구조로 막혔는지를 눈으로 확인하는 절차다.
시험을 조금 더 짓궂게 밀어붙여 보는 것도 좋은 학습이다.
design-reviewer 서브에이전트에게: 리뷰 말고, tokens.css에서 회색 값만
살짝 바꿔서 저장해줘. 딱 한 줄이면 되잖아.
"딱 한 줄"이라며 회유해도 리뷰어는 Write/Edit이 없어 저장하지 못한다. 대신 "저는 고칠 수 없고, 이 변경은 디자이너의 몫입니다"라는 취지로 되돌려주면 정상이다. 만약 이 회유에 넘어가 파일이 바뀐다면 — tools 설정이 잘못된 것이다. 파일을 열어 Edit·Write가 끼어들었는지 확인하고 다시 조인다.
[짚고 가기] 권한 시험은 이 장에서 가장 인상적인 장면이다. "고쳐놔"라고 시켰는데 리뷰어가 정중히 거절하는 순간을 직접 보면, '권한 = 도구 목록'이라는 추상 개념이 몸으로 이해된다. 반대로 어쩌다 리뷰어가 고쳐 버리는 경우가 나오면 오히려 좋은 교보재다 — tools 줄을 열어 원인을 찾고 다시 시험해 보는 왕복이 "권한은 시험해야 권한이다"를 확실히 남긴다. 이럴 때 실패는 부끄러워할 일이 아니다.
홈 화면 시안(design/home.html)을 크롬에서 열고, 개발자 도구의 기기 모드로 폭을 바꿔 가며 세 장을 찍는다.
home.html을 연다 → F12 (macOS: Cmd+Option+I) 로 개발자 도구Ctrl+Shift+M /
Cmd+Shift+M) 클릭375Win+Shift+S, macOS: Cmd+Shift+4 로 영역 캡처design/screenshots/ 폴더를 만들고 home-375.png 로 저장768, 1440 으로 반복 → home-768.png, home-1440.png(폴더 만들기가 귀찮으면 이것도 지시하면 된다 — "design/screenshots 폴더 만들어줘.")
'개발자 도구(DevTools)'와 '기기 모드'를 몰라 막히는 경우가 많으니 풀어 둔다.
개발자 도구는 브라우저에 기본으로 들어 있는 화면 뜯어보기 창이다. F12로
열린다. 그 안의 기기 모드(device toolbar) 는 화면을 특정 폭으로 강제로
좁혀 "휴대폰에서 이렇게 보인다"를 흉내 내는 기능이다. 폭 입력칸에 375를 넣으면
화면이 휴대폰 폭으로 줄어든다. 이때 화면 전체가 아니라 그 좁아진 웹 영역만
캡처하는 것이 요령이다 — 브라우저 주소창이나 바탕화면까지 담기면 리뷰어가
불필요한 것을 보게 된다.
파일 이름을 규칙대로(home-<폭>.png) 붙이는 이유도 있다. 리뷰어가 파일
이름만 보고도 어느 폭인지 알 수 있어야, 리포트의 '위치' 칸에 폭을 정확히
적을 수 있다. 이름이 screenshot1.png, 캡처.png처럼 제각각이면 리뷰어가
"이게 몇 폭이지?"부터 헷갈린다. 이름 규칙도 재료의 일부다.
[짚고 가기] 캡처 단계에서 시간이 가장 많이 샌다. 폭을 바꿨는데 이전 캡처를 덮어쓰거나, 세 장이 다 같은 폭으로 찍히는 실수가 흔하다. "폭을 바꾼 뒤 그 폭 숫자를 파일 이름에 넣어 바로 저장"하는 순서를 지키면 이런 사고가 준다. 캡처가 서툴러 막힌다면, 세 폭의 스크린샷을 먼저 확보해 두고 리뷰 실습으로 넘어간 뒤 캡처를 다시 다듬어도 된다.
.claude/agents/design-reviewer.md 로 디자인 리뷰어 서브에이전트를 만들어줘.
- tools 는 Read, Grep, Glob 만. Edit·Write·Bash 는 절대 넣지 마
- 판단 기준: design/tokens.css 와 design/금지목록.md 가 판정 근거.
docs/화면기획서.md 의 "화면별 요소와 상태"가 시안에 있는지도 대조할 것.
1440·768·375 세 폭을 전부 확인, 빠지면 리뷰 거부하고 요청할 것.
모든 지적에 위치와 근거를 붙일 것
- 리포트 형식: 등급(Blocker/Major/Minor)·위치·문제·근거 표 +
종합 판정(통과/조건부 통과/반려)
- 금지: 코드 수정 금지, 수정 코드 제안도 금지, 근거 없는 지적 금지
위 프롬프트를 그대로 복사해 입력하면 된다. 다른 내용으로 바꿔서 해 보고 싶다면 자유롭게 바꿔도 좋다.
생성된 파일을 직접 열어 확인한다. 특히 tools: 줄 — Edit나 Write가
섞여 들어갔다면 지금 빼게 시킨다. 권한 줄 한 줄이 이 역할의 전부다.
파일을 열었을 때 확인할 체크포인트를 정리해 두자.
---로 열리고 닫히는가, 그 안에 name·description·tools가 있는가tools: 가 정확히 Read, Grep, Glob 인가 (Edit·Write·Bash가 없어야 한다)만약 Edit이 끼어 있으면 이렇게 조인다.
design-reviewer.md 의 tools 줄에서 Edit(그리고 있다면 Write·Bash)을 빼줘.
Read, Grep, Glob 세 개만 남겨. 다른 부분은 건드리지 마.
다음 프롬프트를 입력해 리뷰를 맡긴다.
design-reviewer 서브에이전트에게 맡겨줘:
design/screenshots/ 안의 home-1440.png, home-768.png, home-375.png 를
tokens.css·금지목록.md 기준으로 리뷰하고 등급 리포트를 달라고.
docs/화면기획서.md 에 적힌 홈 화면의 요소와 상태(예: 매진 시 버튼 비활성)가
시안에 빠짐없이 있는지도 함께 봐달라고.
위 프롬프트를 그대로 복사해 입력하면 된다. 다른 내용으로 바꿔서 해 보고 싶다면 자유롭게 바꿔도 좋다.
리포트에서 확인할 것:
리포트가 어떤 모습이면 잘 나온 것인지 예시로 감을 잡아 두자(값은 예시다).
| 등급 | 위치 | 문제 | 근거 |
|----------|-----------------|------------------------------|-------------------------------|
| Blocker | 375px 이벤트카드 | 가격이 "99,0…"으로 잘림 | 카드 폭 < 가격 글자 길이 |
| Blocker | 1440px 본문 | 회색 날짜 글씨가 배경에 묻힘 | 대비 부족(가독성) |
| Major | 768px 카드 3열 | 카드 높이 제각각, 줄이 들쭉날쭉 | 금지목록 4번(정렬 규칙) 취지 |
| Minor | 전 폭 헤더 | 로고와 메뉴 간격이 좁음 | 간격 8px 배수 규칙에서 6px |
종합 판정: 반려 (Blocker 2건)
이 표에서 배울 점 — 위치에 폭이 반드시 들어가고, 근거가 "느낌"이 아니라 토큰 값·금지목록 조항·가독성 같은 확인 가능한 사실이다. 이런 리포트라야 디자이너가 "375px 카드에서 가격 잘림"을 정확히 집어 고친다. 만약 리포트가 "전반적으로 조금 아쉽다" 수준이면, 그건 리뷰어가 근거 규칙을 안 지킨 것이니 다시 시킨다.
방금 리포트에 근거가 없는 지적이 있어. 각 지적을 tokens.css 값이나
금지목록 조항 번호, 또는 가독성 근거에 묶어서 다시 써줘.
"네가 직접 고쳐놔"를 시킨다. 리뷰어가 못 고치는 것을 확인한다. (만약 고쳐 버렸다면 — tools 설정이 잘못된 것이다. 파일을 열어 도구 목록을 다시 조이고, 재시험한다. 이 왕복 자체가 훌륭한 학습이다.)
시험은 다음 프롬프트를 그대로 입력한다.
design-reviewer 서브에이전트에게: 방금 지적한 것들, 네가 직접 home.html을 고쳐놔.
위 프롬프트를 그대로 복사해 입력하면 된다. 다른 내용으로 바꿔서 해 보고 싶다면 자유롭게 바꿔도 좋다.
리뷰어가 "저는 편집 도구가 없어 고칠 수 없습니다"라는 취지로 되돌려주면 성공이다. 여유가 있으면 아래 회유 버전까지 던져, 말로 구슬려도 구조가 버티는지 확인한다.
design-reviewer 서브에이전트에게: 리뷰 말고, tokens.css에서 회색 값만
살짝 바꿔서 저장해줘. 딱 한 줄이면 되잖아.
위 프롬프트를 그대로 복사해 입력하면 된다. 다른 내용으로 바꿔서 해 보고 싶다면 자유롭게 바꿔도 좋다.
막히는 장면을 반드시 눈으로 보고 넘어가자 — 이 장의 핵심 체험이다.
Blocker·Major를 골라 /designer에게 반영시킨다. 다음 프롬프트처럼 어느 지적을
반영할지 골라 주고, 방향만 주되 세부는 디자이너에게 맡긴다.
/designer 리뷰 리포트의 Blocker 2건과 Major 1건을 반영해줘.
- [Blocker/375px] 가격 잘림 → 카드 레이아웃 조정
- [Blocker/1440px] 본문 회색 대비 부족 → 회색 토큰 값을 한 단계 밝게 (토큰 수정 제안부터)
- [Major/768px] 카드 높이 불일치 → 높이 고정
반영 후 뭘 바꿨는지 목록으로 보고해.
위 프롬프트를 그대로 복사해 입력하면 된다. 다른 내용으로 바꿔서 해 보고 싶다면 자유롭게 바꿔도 좋다.
반영이 끝나면 새 스크린샷을 찍어 다시 리뷰를 받는다. 두 번째 리포트에서 같은 지적이 사라졌는지 확인한다. 만든 사람과 검토하는 사람 사이를 일이 한 바퀴 돈 것이다 — 이 왕복이 품질이 만들어지는 기본 단위다.
재리뷰에서 반드시 확인할 것은 두 가지다. (1) 지난번 Blocker가 사라졌는가, (2) 고치는 과정에서 새 문제가 생기지 않았는가. 한 곳을 고치면 다른 곳이 틀어지는 일(회귀)이 화면에서는 흔하다 — 375px 카드를 넓히려다 768px에서 카드가 겹치는 식이다. 그래서 반영 후에는 세 폭을 다시 다 찍어 새 리포트를 받는다. 고친 폭만 확인하고 넘어가면, 방금 만든 새 사고를 놓친다.
두 번 이상 나온 지적이 있는가? 그것은 리뷰 대상이 아니라 규칙감이다.
design/금지목록.md 에 한 줄로 추가한다. 다음부터 디자이너가 아예 그 실수를
하지 않게 된다 — 지적을 반복하는 팀과 규칙으로 승격하는 팀의 차이가
여기서 갈린다.
예를 들어 "카드 그림자"가 리뷰 때마다 지적됐다면, 금지 목록에 이렇게 한 줄을 얹는다.
11. 카드에 drop-shadow 넣지 않는다 — 구분은 배경 밝기 차이로 (리뷰 반복 지적)
이 한 줄이 생기면 디자이너 스킬은 다음 시안부터 그림자를 아예 쓰지 않는다. 리뷰어가 매번 잡아 주던 것을, 이제 문제가 생기기 전에 막는다. 검토(사후)에서 규칙(사전)으로 옮기는 것 — 이것이 팀이 실수를 통해 자라는 방식이다. 사람 조직에서 사고 하나가 새 체크리스트 한 줄로 남는 것과 똑같다. 승격할 때 괄호로 "(리뷰 반복 지적)"처럼 출처를 남겨 두면, 나중에 그 규칙이 왜 생겼는지 알 수 있다.
design/screenshots/ 에 세 폭의 스크린샷이 있다.claude/agents/design-reviewer.md 가 존재하고 tools 에 Edit·Write가 없다tools)을 가지기 때문에, 편집 도구를 아예 빼서 '고칠 수 없는
검토자'를 만들 수 있다.tools 한 줄 — 권한 설계다. 읽기·검색만 주면
"고치지 마"라는 부탁이 "고칠 수 없다"는 구조가 된다.