CLAUDE.md + 18개 Skills 시스템 설계기
Claude Code에 프로젝트 지침서를 넣어주면 AI가 코드베이스를 이해하고, 일관된 규칙을 따릅니다. 매 세션마다 "Tailwind 쓰고, 커밋은 feat: 접두사로..." 같은 말을 반복하지 않아도 됩니다.
이 블로그(White Place)는 CLAUDE.md 1개 + 스킬 파일 18개로 운영됩니다. 블로그 글 작성, AI 뉴스, 데스크 리뷰, 코드 리뷰, 배포까지 각각 전담 스킬이 처리합니다. 그 구조를 공개합니다.
CLAUDE.md — 프로젝트의 헌법
CLAUDE.md는 Claude Code가 매 세션 시작 시 자동으로 읽는 프로젝트 지침서입니다. 이 파일 하나가 AI의 행동 기준을 잡아줍니다.
이 프로젝트의 CLAUDE.md는 크게 5개 블록으로 구성됩니다.
Project Context & Structure
프로젝트가 뭔지, 어떤 기술 스택을 쓰는지, 디렉토리 구조가 어떻게 되는지 정리한 부분입니다.
- Next.js 14 App Router
- React, TypeScript, Tailwind CSS, React Three Fiber
- Deploy: Vercel (main 브랜치 푸시 시 자동 배포)
src/app/, src/components/, src/content/posts/, src/lib/ 등 주요 디렉토리와 각 파일의 역할을 명시해뒀습니다. Claude가 "이 파일 어디에 만들어야 하지?"를 묻지 않게 됩니다.
Category System (2-Tier)
블로그 포스트 분류 체계입니다. category + subcategory 2단계로 나뉩니다.
| category | subcategory | 설명 |
|---|---|---|
dev | web-dev, dev-env | 웹 개발, 개발환경 |
cs | tutorial, algorithm | 튜토리얼, 알고리즘 |
desk | desk-setup, keyboard, peripherals | 데스크 셋업 |
ai | ai-tools, ai-news | AI 도구, AI 뉴스 |
4개 카테고리, 9개 서브카테고리. 이걸 CLAUDE.md에 명시해두면 AI가 포스트를 쓸 때 프론트매터의 category/subcategory 값을 틀리지 않습니다.
Global Rules — 6개
프로젝트 전역에서 지켜야 할 규칙입니다. 진짜 자주 깨지는 것만 넣었습니다.
1. 하드코딩 색상 금지 → CSS 변수(var(--bg-primary)) 또는 Tailwind 토큰 사용
2. 패키지 설치 전 반드시 물어보기
3. SSG first — 서버사이드 로직 최소화
4. 3D 컴포넌트는 dynamic import + ssr: false
5. 모든 이미지는 next/image 사용
6. 카드 텍스트에서 " — " 구분자 금지
6개면 충분합니다. 규칙이 20개가 되면 아무도 안 읽습니다. AI도 마찬가지입니다.
Code Quality 셀프리뷰
구현 완료 후, 결과를 보고하기 전에 반드시 거치는 체크리스트입니다.
1. npm run build 실행 — 에러 있으면 수정 후 재실행
2. 사용하지 않는 import/변수 제거
3. React 안티패턴 점검 (useEffect cleanup, StrictMode)
4. CSS 레이아웃 회귀 확인
5. 섹션 맥락 일치 확인
6. Off-by-one 에러 점검
이 체크리스트 덕분에 "빌드 안 되는 코드를 완료라고 보고하는" 상황이 사라졌습니다.
Agent Routing 테이블
이게 핵심입니다. 사용자가 입력한 키워드에 따라 어떤 스킬 파일을 읽어야 하는지 매핑한 테이블입니다.
| Skill | File | Trigger Keywords |
|-------|------|-----------------|
| A Blog Writer | A-blog-writer.md | blog, post, article |
| F AI News Writer | F-ai-news-writer.md | ai news, 뉴스, LLM |
| R Code Review | R-review.md | review, 리뷰, 검토 |
| P Push & Deploy | P-Push-and-deploy.md | deploy, push, 배포 |
| ... | ... | ... |
"블로그 글 써줘"라고 하면 Skill A가, "코드 리뷰해줘"라고 하면 Skill R이 활성화됩니다. CLAUDE.md가 라우터 역할을 하는 겁니다.
Skills — 전문 에이전트 18개
.claude/skills/ 디렉토리에 마크다운 파일을 넣으면 됩니다. 각 파일이 하나의 전문 에이전트 역할을 합니다.
4개 카테고리
콘텐츠 스킬 (A, E~G, I, J, S)
| 스킬 | 역할 |
|---|---|
| A | 블로그 작성 (아웃라인 → 승인 → 본문 → 빌드) |
| E | YouTube 큐레이션 |
| F | AI 뉴스 (WebSearch 필수, 팩트체크) |
| G | CSV 데이터 시각화 |
| I | 이미지/미디어 관리 |
| J | 데스크 리뷰 |
| S | SEO 메타데이터 |
빌드 & 개발 스킬 (B~D, H)
| 스킬 | 역할 |
|---|---|
| B | 기능 개발 (Feature Dev) |
| C | 포트폴리오 관리 |
| D | 디자인 시스템 (CSS 변수, Tailwind 토큰) |
| H | 3D 전문가 (R3F, WebGL, dynamic import) |
유틸리티 스킬 (R, P)
| 스킬 | 역할 |
|---|---|
| R | 코드 리뷰 (severity 등급, file:line 강제) |
| P | 푸시 & 배포 (Vercel) |
Dark Place 스킬 (DP-*)
별도의 다크 테마 사이트 전용 스킬 4개입니다. 보안 뉴스, 3D 씬, 컴포넌트, 디자인 토큰을 각각 담당합니다.
스킬 파일의 공통 구조
모든 스킬 파일은 같은 뼈대를 따릅니다.
1. Purpose — 이 스킬이 하는 일
2. Workflow — 단계별 작업 흐름
3. Quality Gate — 통과 기준
4. Self-Check — 최종 점검 체크리스트
5. Routing Rules — 다음 스킬로의 연결
특히 Routing Rules가 중요합니다. "리뷰 후 스타일 수정이 필요하면 Skill D로 가라"처럼, 스킬 간 참조 패턴으로 연결됩니다. 중복 없이 워크플로우가 이어집니다.
스킬 하이라이트 — 실전 사례 3개
Skill A: Blog Writer
가장 기본이 되는 스킬입니다. 워크플로우를 보면:
1. 주제 분석 → 타겟 독자/카테고리 결정
2. 아웃라인 생성 (H2/H3 구조, 최소 3개 섹션)
3. AskUserQuestion으로 아웃라인 승인 (승인 전까지 본문 작성 금지)
4. 본문 작성 (tone-guide.md 준수)
5. 프론트매터 생성 + 파일 저장
6. npm run build 검증
3번이 포인트입니다. 아웃라인 승인 없이 바로 2000자 글을 써버리면 방향이 틀어졌을 때 전부 버려야 합니다. 사람이 한 번 확인하는 게 훨씬 효율적입니다.
Skill F: AI News Writer
AI 뉴스 전용 스킬은 Skill A의 규칙을 상속하면서 추가 제약을 겁니다.
출처 등급 시스템이 핵심입니다.
| 등급 | 출처 유형 | 사용 방식 |
|---|---|---|
| A | 공식 블로그, 논문 | 사실로 기술 |
| B | TechCrunch, The Verge | 사실로 기술 + 매체명 언급 |
| C | 분석가, 전문 블로그 | "~에 따르면" 형태 |
| D | SNS, 루머 | 사용 금지 또는 미확인 명시 |
WebSearch가 필수입니다. 학습 데이터에만 의존해서 뉴스를 쓰면 날짜가 틀리고 수치가 엉뚱해집니다. 최소 2~3개 독립 검색 쿼리를 실행하고, 핵심 주장은 교차 검증해야 합니다.
그리고 팩트 vs 추론 분류가 엄격합니다. AI가 "이 기술은 곧 시장을 지배할 것입니다"라고 단정적으로 쓰는 걸 막습니다. 추론은 반드시 별도 섹션으로 분리하고 "필자의 시각"임을 명시해야 합니다.
Skill R: Code Review
"looks good" 같은 리뷰를 금지한 스킬입니다.
severity 등급이 있습니다.
| 등급 | 의미 | 예시 |
|---|---|---|
[C] Critical | 빌드 실패, 보안 취약점 | 타입 에러, XSS |
[M] Major | 기능 오동작, 회귀 버그 | 반응형 깨짐 |
[m] Minor | 코드 품질 | 불필요한 import |
[S] Suggestion | 선택적 개선 | 더 나은 패턴 |
모든 이슈는 src/components/Foo.tsx:42 형태의 file:line 레퍼런스가 필수입니다. "어딘가에서 문제가 있다" 같은 모호한 리뷰는 허용되지 않습니다.
tone-guide.md — AI 냄새 제거기
스킬과 별도로, 모든 콘텐츠 스킬이 참조하는 톤 가이드 파일이 있습니다.
Anti-AI Ban List
금지어 목록이 이 파일의 핵심입니다.
금지된 전환어: "결론적으로 말씀드리자면", "놀랍게도", "요약하자면", "Let's dive in"
금지된 형용사: "혁신적인", "환상적인", "game-changing", "revolutionary"
금지된 인트로: "안녕하세요 여러분!", "오늘 소개해드릴 내용은~"
금지된 패턴: 같은 구조로 3문장 연속, "또한"으로 문단 시작 2회 이상, 매번 정확히 3개씩 나열
문체 규칙
합니다체를 씁니다. 문단은 4문장 이하. 기술 용어는 영어 그대로 둡니다("React", "SSG", "API"). 이모지는 전체 글에서 02개만 허용됩니다.
셀프체크 기준
모든 콘텐츠 스킬의 마지막 단계에 이 질문이 있습니다:
"새벽 2시에 커피 마시며 쓴 느낌인가?"
이걸 통과 못 하면 다시 씁니다. AI에게 "자연스럽게 써라"보다 "이런 건 하지 마라"가 훨씬 잘 먹힙니다.
설계하며 배운 것
CLAUDE.md는 짧게 유지한다
CLAUDE.md에 모든 규칙을 넣으면 파일이 500줄을 넘깁니다. 핵심 구조와 라우팅 테이블만 남기고, 상세한 프로세스는 스킬 파일로 분리했습니다.
스킬 간 참조로 중복을 제거한다
Skill F(AI 뉴스)는 글쓰기 프로세스를 Skill A(Blog Writer)에서 상속합니다. "프론트매터 규칙은 Skill A 참조"라고 한 줄 쓰면, 같은 내용을 두 곳에서 관리할 필요가 없습니다.
Global Rules는 진짜 자주 깨지는 것만
"하드코딩 색상 금지"를 넣은 건, AI가 실제로 bg-[#fff]를 자주 써서입니다. "파일 크기 100KB 이하"처럼 안 깨지는 규칙은 넣지 않았습니다. 6개면 충분합니다.
금지어 목록이 효과적이다
AI에게 "인간처럼 써라"고 하면 해석이 모호합니다. "혁신적인을 쓰지 마라", "Let's dive in을 쓰지 마라"는 명확합니다. Ban List를 만들고 셀프체크에서 검사하게 하면, 글의 AI 냄새가 확연히 줄어듭니다.
시작하려면
이 시스템의 구조를 정리하면 이렇습니다.
프로젝트 루트/
├── CLAUDE.md # 핵심 규칙 + Agent Routing 테이블
└── .claude/skills/
├── tone-guide.md # 톤 & 금지어 목록
├── A-blog-writer.md # 블로그 작성
├── B-feature-dev.md # 기능 개발
├── C-portfolio-manager.md # 포트폴리오
├── D-design-system.md # 디자인 시스템
├── E-youtube-curator.md # YouTube 큐레이션
├── F-ai-news-writer.md # AI 뉴스
├── G-csv-visualizer.md # CSV 시각화
├── H-3d-specialist.md # 3D/WebGL
├── I-image-media.md # 이미지/미디어
├── J-desk-review-writer.md # 데스크 리뷰
├── S-seo-metadata.md # SEO
├── R-review.md # 코드 리뷰
├── P-Push-and-deploy.md # 배포
└── DP-*.md # Dark Place 전용 (4개)
자신의 프로젝트에 적용할 때 이 순서를 추천합니다:
- CLAUDE.md부터 만듭니다. 프로젝트 구조, 기술 스택, 명령어 3개(dev, build, type-check)만 적어도 효과가 있습니다.
- 자주 반복하는 작업 하나를 스킬 파일로 뺍니다. 블로그를 자주 쓴다면 A-blog-writer.md 같은 파일을 만드세요.
- AI가 반복적으로 깨는 규칙을 Global Rules에 추가합니다. 3개부터 시작해서, 필요할 때만 늘리세요.
- 톤 가이드는 금지어 목록부터 만듭니다. AI가 쓰는 글에서 거슬리는 표현을 모으면 됩니다.
18개 스킬까지 갈 필요는 없습니다. CLAUDE.md 하나만 잘 써도 생산성이 달라집니다. 거기서부터 필요에 따라 확장하면 됩니다.