AI/claude

Claude Code 팀 사용법 4편: 설계는 숫자로 고르고, 화면은 디자인 기준 파일로

agentnote 2026. 10. 4. 10:52

요약. 저희 팀은 되돌리기 비싼 설계 결정을 느낌으로 하지 않습니다. Claude Code(클로드 코드)에게 대안을 같은 축의 표와 숫자로 비교하게 하고, "무엇이 달라지면 다시 보나"를 꼭 적게 합니다. 화면을 만들 때는 /impeccable 같은 디자인 스킬보다 디자인 기준 파일을 먼저 읽힙니다.

이 글은 "Claude Code 팀 사용법" 4편 연재 중 마지막 4편입니다. 프론트엔드·백엔드가 있는 웹 시스템을 여러 명이 함께 개발하는 팀 기준입니다. 데이터 분석이나 문서 작업, 혼자 쓰는 작은 스크립트처럼 상황이 다르면 맞지 않는 규칙도 있습니다.

Claude Code로 설계 결정할 때 "느낌"으로 정하지 않는 이유

사내 업무용 웹 대시보드를 만들며 구조를 정할 일이 자주 있었습니다. 근거가 느낌뿐이면 반년 뒤에 왜 그렇게 정했는지 아무도 모릅니다. 그래서 대안을 숫자로 견줘 놓고 고르기로 했습니다. 이때 부르는 스킬이 /jeffdean-mind입니다. 대안을 2개 이상 숫자로 비교하고, 10~20배로 늘었을 때와 결정이 뒤집히는 조건까지 적게 하는 스킬입니다. 실제로 이렇게 고른 기록이 네 건 남아 있습니다.

대안 비교는 언제 부르나: 세 가지가 다 맞을 때만

  • 선택지가 둘 이상이다.
  • 되돌리기가 비싸다. 폴더 구조, DB 스키마, 배포 경로, 라이브러리 도입 같은 것입니다.
  • 근거가 "느낌"밖에 없다.

하나라도 빠지면 그냥 만듭니다. 이미 방법이 정해진 일, 단순 버그 수정, 함수 하나 다듬기에는 부르지 않습니다. 표만 길어지고 결론은 안 바뀝니다.

그림 1. 세 조건이 다 맞을 때만 숫자로 비교합니다.

비교 결과에 반드시 나와야 할 네 가지

하나라도 빠지면 다시 시킵니다.

나와야 할 것 왜
대안 2개 이상을 같은 축으로 비교한 표 축이 다르면 비교가 아니라 나열입니다
숫자 (줄 수, KB, px, 일수, 건수) 단위가 없으면 나중에 못 씁니다
10~20배로 늘면 지금 괜찮은 게 내년에도 괜찮은지는 다른 질문입니다
뒤집는 조건 "무엇이 달라지면 이 결정을 다시 봐야 하나." 이 줄이 진짜 산출물입니다

실제로 숫자로 고른 네 건

수치는 크기만 적었습니다.

뭘 고민했나 무엇을 쟀나 결론
프론트를 한 번에 갈아탈까, 화면 단위로 갈까 다시 써야 할 줄 수, 이주 기간 동안 얼려야 하는 커밋 수, 하루에 벌어지는 차이 골격 먼저. 결정을 가른 건 일수가 아니라 "깨지면 원인이 하나로 좁혀진다"였다
새 보드를 새 페이지로, 탭으로, 상단에 늘 보이는 띠로 기존 파일 수정 줄 수, 화면 세로 점유, 필요한 가로 폭(작은 노트북에서 이미 스크롤) 별도 페이지. 데이터 크기는 셋 다 무시할 수준이라 화면 공간이 갈랐다
백엔드를 도메인별로 나눌까, 계층별로 나눌까 import 문 변경 0 vs 수십 개 파일, 기존 테스트가 이미 도메인 단위로 부르고 있었음 도메인 + 파사드. 기존 테스트가 이미 답을 갖고 있었다
DB 이름 규칙: 전부 개명 / 충돌 몇 건만 / 규칙 문서만 코드 수정 0 vs 수십 줄 vs 수천 줄, 전면 개명 시 업로드 기능 여러 곳이 조용히 열을 잃을 위험 규칙 문서와 검사 먼저, 개명은 나중. 위험한 건 뒤로 미뤘다

네 건에서 배운 것 둘

첫째, 숫자가 결론을 안 바꿔도 값이 있습니다. 새 보드 건은 재 보니 데이터 크기가 세 안 모두 무시할 수준이었습니다. "데이터 크기는 기준이 아니다"를 알아낸 게 수확이었고, 그래서 축을 화면 공간으로 옮겼습니다. 재 보지 않았다면 엉뚱한 기준으로 논쟁했을 겁니다.

둘째, 뒤집는 조건이 반년 뒤에 제일 쓸모 있습니다. "이거 왜 이렇게 했지?"에 답하는 건 결론이 아니라 그 한 줄입니다. 백엔드 쪼개기 문서에는 "테스트가 계층 단위로 옮겨 가거나, 두 번째 채널이 생겨 공유가 필요해지면 다시 본다"가 적혀 있습니다.

표 대신 직접 만들어 보고 정한 것: CSS 프레임워크 도입

단계 내용
관찰 CSS 한 파일이 수천 줄이었습니다. "확장성이 막힌다"는 느낌은 맞았습니다
원인 후보 둘 ① 한 파일에 다 있다 ② 표준 어휘가 없다. 어느 쪽인지 모르는 게 문제였습니다
실제로 해 봄 버리는 브랜치에서 전체 선언의 아주 일부(약 2%)를 Tailwind(클래스 이름을 조합해 스타일을 거는 CSS 프레임워크)로 옮겨 봤습니다
측정 결과 코드가 늘었습니다. 새로 쓴 유틸 상당수가 기본 눈금에 없는 임의값이었습니다(격자의 수가 눈금에 하나도 안 맞음). 번들 크기가 늘고, 검사 여러 건이 빨개졌고, 스타일 몇 개가 조용히 사라졌는데 자동으로 잡힌 건 0건이었습니다
결정적이었던 것 크기가 아니었습니다. CSS를 글자로 읽어서 규칙을 거는 검사를 수십 건 갖고 있는데, 이주하면 그걸 통째로 잃습니다
결정 도입하지 않았습니다. 대신 한 파일을 기능별로 쪼갰습니다
뒤집는 조건 ① 조금씩 옮기는 걸 막는 기술 문제가 풀리고 ② 화면이 조용히 깨지는 걸 잡는 검출기가 생기면 다시 봅니다

그림 2. 느낌을 측정으로 바꾼 하루가 몇 주짜리 이주를 막았습니다.

대안 비교를 부르는 문장: 비교 기준은 직접 준다

이 화면을 새 페이지로 뺄지, 기존 화면에 탭으로 붙일지 못 정했습니다. 두 안을 숫자로 비교해 주세요. 기존 파일을 몇 줄 고쳐야 하는지, 화면 세로·가로를 얼마나 먹는지(작은 노트북 기준), 지금 걸려 있는 검사 중 빨개지는 게 있는지. 그리고 어떤 조건이면 이 결정이 뒤집히는지도 적어 주세요.

"알아서 비교해 주세요"라고만 하면 성능·확장성 같은 일반 항목으로 표를 만듭니다. 실제로 문제가 되는 건 화면 공간이나 검사 빨강처럼 구체적인 것들입니다.

Claude Code로 화면을 만들 때는 디자인 문맥 파일부터 읽힌다

스킬을 부르기 전에 디자인 문맥 파일(.impeccable.md)부터 읽힙니다. 우리 화면을 누가·어디서·어떻게 쓰는지, 그래서 어떤 모양이어야 하는지 적은 파일입니다. 디자인 스킬(/impeccable, /critique 등)은 이 파일을 기준으로 판단합니다.

왜 필요한가. 설명 없이 "화면 만들어 주세요"라고 하면 카드와 그림자가 많고 도넛 차트와 게이지가 들어간, 흔히 보는 예쁜 대시보드가 나옵니다. 저희 대시보드에는 맞지 않았습니다. 숫자를 보는 도구가 아니라 숫자를 고치는 도구이기 때문입니다.

처음 만들 때: /impeccable teach

새 프로젝트에서 한 번만 합니다.

  1. Claude가 먼저 저장소를 훑습니다(README·문서, package.json, 기존 컴포넌트, CSS 토큰). 알 수 있는 건 스스로 채웁니다.
  2. 코드로 알 수 없는 것만 선택지를 주고 묻습니다.
  3. 누가 어떤 상황에서 쓰나, 이 화면으로 무슨 일을 끝내려 하나
  4. 사용자가 어떤 느낌을 받아야 하나(확신·침착함·속도감 등)
  5. 서비스 성격을 세 단어로 하면
  6. 닮고 싶은 서비스와, 그 서비스의 어떤 점이 좋은지
  7. 절대 이렇게 보이면 안 되는 모습
  8. 라이트·다크, 꼭 쓰거나 피할 색
  9. 접근성 요구(WCAG 등급, 색약, 애니메이션 줄이기)
  10. 답을 모아 저장소 맨 위에 파일을 씁니다. 사용자, 성격, 디자인 방향, 원칙 3~5개.

이 프로젝트의 디자인 기준 파일을 만들고 싶습니다. /impeccable teach로 진행해 주세요. 코드에서 알 수 있는 건 먼저 확인하시고, 모르는 것만 물어봐 주세요. 참고로 이 화면은 매일 쓰는 실무자와, 주 1회 회의실 큰 화면으로 보는 참석자가 같이 씁니다.

답할 때 신경 쓸 것 셋입니다. ① "깔끔하게"보다 구체적으로("회의실 뒷줄에서 읽혀야 한다", "적록색약 참석자가 있다"). ② 레퍼런스는 이름만 말고 "그 서비스의 무엇"까지. ③ 피할 모습을 꼭 말합니다. 실제로 가장 많이 쓰이는 항목입니다.

디자인 문맥 파일에 적힌 것

항목 내용
누가 쓰나 두 부류가 같은 화면을 씁니다. ① 매일 자기 모니터로 값을 검토하고 조정하는 실무자 ② 주 1회 회의실 큰 화면으로 조정안을 같이 보고 그 자리에서 확정하는 참석자. 개인 모니터에 맞추면 뒷줄에서 안 보이고, 회의실에 맞추면 개인 작업 때 스크롤이 끝없이 길어집니다. 그래서 화면 밀도(글자·칸 크기)를 개인용과 회의용 사이에서 고르게 했습니다
닮고 싶은 것 조정 전·후를 차이(델타)로 보여 주는 방식 / Linear처럼 키보드만으로 일이 끝나고 누르면 바로 반응하는 것 / Figma처럼 누가 지금 무엇을 바꿨는지가 화면에 남는 것
피하고 싶은 것 값 하나 고치려고 화면 세 개를 오가는 오래된 업무 시스템 / 도넛·게이지는 많은데 정작 숫자를 고칠 수 없는 일반 BI 대시보드

디자인 원칙 다섯 개와 실제로 적용한 곳

원칙 무슨 뜻인가 실제로 적용한 곳
① 숫자가 주인공 카드·그림자·아이콘이 숫자보다 먼저 눈에 띄면 뺍니다. 꾸미기 전에 "숫자가 더 잘 읽히나?"를 묻습니다 진단 설명을 문단으로 넣은 목업은 행이 전부 2~3줄로 늘어 표가 글처럼 됐습니다. 칸에는 한 줄, 긴 설명은 툴팁으로 옮겼습니다
② 값보다 차이 조정한 값만 보면 잘 고쳤는지 모릅니다. 전·후와 차이를 한 화면에 둡니다 일괄 조정 화면에서 목표값 옆에 "+1,200 (+8%)"처럼 차이를 붙였습니다(예시 숫자)
③ 색은 보조 증감을 색으로만 표시하지 않습니다. +/− 부호와 화살표가 먼저, 색은 거들 뿐입니다. 적록색약은 남성에게 드물지 않아서 참석자 중에 있을 수 있습니다 증감에 부호를 항상 붙이고, 새 색 대신 기존 경고색을 다시 씁니다
④ 제자리에서 펼치기 모달(팝업 창)이나 다른 페이지로 넘기지 않고 보던 자리에서 펼칩니다. 회의 중 화면이 바뀌면 모두 흐름을 놓칩니다 값 편집 창을 격자 위에 작게 뜨는 칸으로 만들었습니다. "진단 화면을 하나 더 만들자"는 안도 이 원칙으로 기각했습니다
⑤ 바로 반응하고, 저장은 뒤에서 저장을 누르면 서버 응답을 기다리지 않고 화면부터 바꿉니다. 실패하면 원래 값으로 되돌리고 이유를 보여 줍니다 처음엔 저장할 때마다 격자가 잠깐 비었다가 다시 나타났습니다. 입력하는 순간 값이 보이게 바꾸고 그 동작을 테스트로 고정했습니다

코드 주석에도 원칙을 적는다

디자인 문서는 보통 만들고 잊힙니다. 저희 것은 계획서와 코드 주석에서 그대로 인용됩니다.

/** 색은 2차 신호다(원칙 3) — 방향은 글자가 먼저 말한다. 적록색약은 증감 색을 못 가른다. */
// 제자리에서 편다. 모달 오버레이가 아니라 격자 위에 얹히는 팝오버다
// (원칙 4 — 모달은 다른 수가 정말 없을 때만)

"왜 이렇게 만들었지?"의 답이 코드 바로 옆에 있습니다.

화면 하나를 만드는 순서

  1. 디자인 문맥 파일을 읽히고 아이디어를 말합니다. 원칙에 어긋나는 게 있으면 만들기 전에 먼저 말해 달라고 합니다.
  2. 목업부터 만듭니다. HTML 목업으로 모양을 보고, docs/mockups/에 쌓습니다.
  3. 목업 확인 뒤 구현합니다. 2편의 흐름을 그대로 탑니다.
  4. 만든 화면을 평가받습니다. /critique에 우리 사용자 조건을 알려 줍니다.
  5. 브라우저로 직접 봅니다.

표에 진단 열을 붙이려 합니다. 디자인 문맥 파일을 먼저 읽고, 제 아이디어 중 원칙에 어긋나는 게 있으면 만들기 전에 먼저 말씀해 주세요. 목업부터 만들고, 제가 보고 나서 구현으로 갑니다.

이렇게 요청했더니, 만들기 전에 "설명을 문단으로 넣으면 칸이 길어져서 정작 숫자가 눈에 안 들어온다"는 지적을 먼저 받았습니다. 평가를 맡길 때도 조건을 붙입니다.

이 화면 평가해 주세요. 회의실 큰 화면에서 뒷줄이 읽을 수 있느냐가 제일 중요하고, 적록색약인 분이 참석자에 있을 수 있습니다. 그 두 가지를 기준으로 봐 주세요.

조건 없이 평가를 시키면 일반 UX 기준으로 봅니다.

그림 3. 기준 파일 → 목업 → 구현 → 평가 → 브라우저.

화면과 문서를 만드는 스킬들

이럴 때 이걸 쓴다
화면·컴포넌트를 만든다 /impeccable (목업 → 구현)
디자인 문맥을 처음 세운다 /impeccable teach (한 번만)
만든 화면을 평가한다 /critique (시각 위계·인지 부하 점수)
배치·여백이 어딘가 어색하다 /layout (간격·정렬·리듬 교정)
움직임을 더한다 /animate
아키텍처 도식이 필요하다 아키텍처 도식 스킬
이미 있는 HTML에 그림을 넣는다 그림 넣는 스킬 (새 파일 없이 제자리 수정)
차트·지표 타일을 만든다 /dataviz (차트 코드 전에 읽는 색·축·범례 규칙)
조사 결과를 보고서로 보고서 스킬
운영 가이드·런북 /guidify
회의 메모를 회의록으로 /minutes
글에서 AI 티를 걷어낸다 /humanizer (현업 안내 메일·공지)

왜 문서를 "아티팩트"(HTML 페이지)로 만드나

현업에는 엑셀이나 PPT 대신 링크 하나를 보냅니다. 받는 쪽은 열기만 하면 되고, git에 같이 있으니 나중에 찾을 수 있습니다. docs/에 수십 장 쌓여 있습니다. 설명 대본, 화면 목업, 속도 개선 실측, 현업 안내, 아키텍처 도식.

따라 해 보기: 다음 구조 결정에 "뒤집는 조건" 받기

다음에 되돌리기 비싼 결정을 할 때 이렇게 덧붙여 보세요. "비교 기준은 A, B, C입니다. 숫자로 비교하고, 어떤 조건이면 이 결정이 뒤집히는지 적어 주세요." A, B, C는 실제로 걱정하는 것으로 채웁니다.

더 깊이: 결정 기록과 디자인 문맥 파일

결정 기록의 뼈대. 네 가지 산출물을 칸으로 만든 양식입니다.

## 결정: <무엇을 정했나>
### 비교표 (같은 축)
| 축 | 안 A | 안 B |
|---|---|---|
| 기존 파일 수정 (줄) | | |
| 화면 세로 점유 (px) | | |
| 빨개지는 검사 (건) | | |
### 10~20배로 늘면
### 뒤집는 조건

디자인 문맥 파일의 자리. /impeccable은 공개 저장소(pbakaus/impeccable, Apache-2.0)로 배포되는 디자인 스킬입니다. teach를 한 번 돌리면 저장소 맨 위에 .impeccable.md가 생깁니다. 저장소에 들어 있어서 클론하면 팀원 모두에게 같은 기준이 따라옵니다(1편).

기준을 주는 이유. Claude Code의 스킬은 SKILL.md에 절차를 적은 설명서입니다. 무엇을 기준으로 읽었느냐에 따라 결과가 갈립니다. 비교와 평가도 기준을 안 주면 가장 일반적인 기준을 고릅니다.

자주 묻는 질문

Q. 모든 결정을 숫자로 비교시켜야 하나요? 아닙니다. 선택지가 둘 이상이고, 되돌리기가 비싸고, 근거가 느낌뿐일 때만 시킵니다.

Q. 비교했는데 결론이 처음 생각과 같으면 시간 낭비 아닌가요? "데이터 크기는 기준이 아니다"를 알게 되어 엉뚱한 논쟁을 피했습니다.

연재는 여기까지입니다. 이제 다시 Engineering 본편으로 돌아갑니다.

연재 목차: Claude Code 팀 사용법

출처

  • /impeccable (Apache-2.0): https://github.com/pbakaus/impeccable
  • superpowers (MIT): https://github.com/obra/superpowers
  • Claude Code 문서, Skills: https://code.claude.com/docs/en/skills
  • Claude Code 문서, Memory(CLAUDE.md): https://code.claude.com/docs/en/memory