프로젝트의 CLAUDE.md에 새 규칙을 하나 넣을 때마다 드는 생각이 있었다.

이 규칙을 다른 프로젝트에도 반영해야겠는데?

바이브코딩을 하면서 프로젝트마다 규칙, 스킬, 훅 같은 것들이 꽤 쌓였는데, 문제는 이게 전부 각 프로젝트 레포 안에 갇혀 있다는 거였다. 새 사이드 프로젝트를 시작하면 규칙 0개짜리 빈 레포에서 또 처음부터다. 매번 복사붙여넣기 하기도 귀찮고, 매번 새 업데이트를 반영하기도 귀찮았다.
그래서 다음 바이브 코딩은 정리된 규칙 위에서 바로 시작할 수 있게, 규칙까지 통째로 담은 시작 템플릿을 만들었다.

규칙은 쌓이는데 프로젝트마다 리셋된다

이전 프로젝트들에서 제일 크게 체감한 게 바이브 코딩은 초기 '규칙' 싸움이란 것이다. 규칙 없이 시작하면 AI가 한 파일에 모든 걸 때려 넣어 짬뽕파스타가 되어버리고, 규칙을 잡아두면 결과물이 일관되게 나온다.

그런데 그 규칙이라는 게 처음부터 완성되는 건 아니다. 프로젝트를 하다가 AI가 이상한 짓을 할 때마다 "아 이런 규칙이 필요하구나" 하고 하나씩 추가되는 식이다. (이걸 하네스라고 한다던데..자연스럽게 적용하고 있었던 듯하다..ㅋㅋ)
직접 global.css 수정하지마라, shadcn 원본 수정하지 마라, 커밋은 시키기 전에 하지 마라... 이렇게 몇 달에 걸쳐 다듬어진 규칙 세트가 프로젝트 끝날 때쯤에야 완성된다. 정작 규칙이 제일 필요한 건 코드가 하나도 없는 프로젝트 초반인데 말이다..!

그러면 답은 하나다! 다음 프로젝트는 이 정리된 규칙에서 시작하면 된다. 규칙을 프로젝트에 종속된 설정이 아니라 재사용 가능한 자산으로 만드는 것. 이게 바이브 코딩의 템플릿이 필요한 이유라고 생각했다.

규칙을 통째로 이식하기

내가 만든 템플릿의 심장은 src/가 아니라 .claude/ 폴더다. 여러 프로젝트들에서 검증된 것들을 그대로 심었다.

CLUADE.md

CLAUDE.md에는 작업 방식의 뼈대가 되는 규칙들을 넣어 두었다.
AI가 구현 코드를 직접 짜지 않고 구조와 가이드만 주는 Learn by Doing 규칙, task 1개 단위로 진행 후 정지, 완료 보고 → 검토 → 명시적 승인 후 다음 스텝이라는 2단 ask까지.
프로젝트 컨벤션 규칙들도 함께 들어 있다. 예를 들면 이런 것들이다. 이 밖에도 디렉터리 구조부터 커밋 규칙까지 AI가 마음대로 판단하면 곤란한 것들을 전부 문서로 잡아뒀다.

• network 레이어 — 클라이언트·훅 → clientFetch, Server Component → publicFetch. 직접 fetch() 호출 금지.
• 색상 — globals.css 토큰 변수만사용. 하드코딩 HEX 금지.
• 컴포넌트 분리 기준 — 200라인 초과 + variant·event·layout·action 혼재 → 분리 후보. "역할이 독립적으로 설명 가능할경우"

규칙이 쌓일수록 CLAUDE.md 자체가 비대해진다. AI가 세션마다 통째로 읽는 파일이라 너무 길면 오히려 핵심이 묻힌다. 그래서 실행 규칙같은 것들은 .claude/rules로 따로 빼고, CLAUDE.md는 얇은 인덱스로 유지했다.

SKILLS

스킬도 3개 가져왔다. 매번 프롬프트로 설명하기 귀찮았던 반복 작업들이다.

• register-api-hook — 백엔드 스펙을 주면 fetch 래퍼 함수 + React Query 훅을 컨벤션대로 생성
• zustand-context-store — 화면 스코프 Zustand + Context 스토어 생성
• generate-story — 컴포넌트를 분석해서 Storybook 스토리 생성

frontend-code-reviewer 에이전트는 변경된 코드를 컨벤션 기준으로 체크해주는 리뷰어도 만들었다,

HOOKS

훅은 3개다. 수정 파일 추적, 세션이 끝날 때 tsc --noEmit을 자동으로 돌려서 타입 에러가 있으면 AI가 스스로 고치게 막는 훅, 그리고 이번에 새로 추가한 .env 읽기 차단이다.

디자인도 규칙으로

템플릿에 CLAUDE 규칙만큼 미리 깔아두고 싶었던 게 디자인이었다. 기능 구현은 AI로 잘 굴러가는데, 디자인은 아직까지 AI로 하는 게 힘들다고 느꼈다. 디자인 토큰은 많은 사이트에서 예시를 제공하지만, 그걸로 일관된 컴포넌트를 생성하는 건 아직 AI의 영역이 아니라고 느꼈다. 그냥 예쁜 페이지 만들어줘~ 하면 공통되지 않은 비슷한 디자인을 엄청나게 나열하는 게 무한 반복이었다. claude design 쓰면 되는 거 아니야? 하면 그것 또한 페이지 디자인을 잡아주는 것이지 모든 컴포넌트들의 스타일을 지정해주는 것은 아니라고 느꼈다. 내가 디자인하고 싶은 것은 '컴포넌트'인데 말이다!

그래서 이번엔 반대로 갔다. AI한테 매번 디자인을 시키는 게 아니라, 내가 미리 디자인 체계를 잡아놓고 AI는 그 체계 위에서만 움직이게 하는 것이다.

Design.md

디자인 토큰은 getdesign.kr에서 얻었다.
토스, 당근 같은 한국 서비스들의 디자인 시스템을 정리해둔 곳인데, 여기서 가져온 킷을 바탕으로 평소 맘에 들었던 앱 디자인들을 참고해가며 토큰을 Primitive → Semantic → Component 3계층으로 정의했다.

그리고 토큰만 만들고 끝낸 게 아니라, docs/design.md라는 별도 디자인 규칙 문서를 만들었다. 쏘카의 컴포넌트들과 디자인이 예쁜 앱들의 화면을 캡처해서 모아두고, 이걸 기반으로 규칙을 뽑아냈다.

• (1) 강조색은 그린 하나 — 버튼·CTA·선택·focus는 전부 brand 계열이고, 화면당 primary 액션은 하나만 둔다.
• (2) 파스텔은 분류 전용— 비인터랙티브 표면에만 쓰고, 액션에는 절대 쓰지 않는다.
• (3) 숫자는 bold, 단위는 regular. — docs/design.md

이렇게 박아두면 AI가 색을 고를 때 자기 마음대로 HEX를 찍는 게 아니라 이 문서와 토큰 안에서만 고른다.

이 토큰과 design.md를 기반으로 컴포넌트 제작을 부탁했다. 기본은 shadcn ui 컴포넌트를 바탕으로 하고, 그 위에 core라는 커스텀 컴포넌트를 규칙에 맞게 제작하도록 했다.

구현하기 전에 design.md에 컴포넌트마다 디자인 규칙을 먼저 정해뒀다.
예를들어 버튼이라면 5개 사이즈별 height·radius·타이포에 disabled·loading·press 상태까지 정했다. 이렇게 규칙을 정해놓고 나서 컴포넌트를 제작하니, 스타일이 공통된 컴포넌트들이 만들어졌다. 그렇게 Button, Input, Modal, BottomSheet 같은 core 컴포넌트 23개를 미리 만들어서 스토리까지 붙여뒀다.

새 프로젝트에서 화면을 짤 때 AI가 참조할 재료가 처음부터 있는 셈이다. 만들어둔 컴포넌트들은 Storybook에 배포했다.

고민

바이브 코딩을 하면 할수록 코딩 자체보다 코딩 전에 뭘 깔아두느냐가 코드의 품질을 가르는거 같다. 그리고 기획력이랑 그걸 어떻게 보여줄지에 대한 디자인 감각이 더 중요하게 느껴진다. (그래서 디자인을 배워봐야 하나 하고도 고민중이다..)
그 고민을 하다보면 또 내가 고민하던걸 해결한 무언가를 claude나 openai에서 내놓는것 같다. 언젠가는 삐까 번쩍한 디자인으로 구현해내는 ai 가 나오지 않을까!
너무 빠른 발전속에서, 아니 적절하게 활용하면서 나만의 것을 어떻게 효율적이게 만들어 나갈 수 있는지 고민중이다

REFERENCE

• getdesign.kr — 한국 서비스들의 디자인 시스템을 design.md로 정리해둔 카탈로그. 이 템플릿의 디자인 토큰 출처
• 토스 디자이너가 제품에만 집중할 수 있는 방법 — 토스 디자인 시스템(TDS) 이야기
• SEED Design System — 당근 디자인 시스템 공식 문서, 토큰 계층 참고
• 쏘카 디자인 시스템 2.0 개발기 — SOCAR FRAME 컴포넌트를 웹에서 시스템으로 굴리는 이야기
• Tailwind CSS v4 — Theme variables — config 파일 없이 CSS 변수로 토큰 정의하는 방식