구글링 3시간에서 원라인 배포까지

배포 가이드 검색을 그만두고 Claude Code 스킬을 만들기 시작한 이유

Sarah Chen
Sarah Chen

SENIOR SOFTWARE ENGINEER AT TECHCORP....

제니입니다.

프로덕션 배포할 때 뭘 검색하세요? "Kamal deploy guide", "Rails production deployment", "Tailwind CSS Docker not working"... 저도 처음엔 딱 이랬어요.

공식 문서 읽고, Stack Overflow 답변 따라하고, 블로그 글 복붙하고. 합리적으로 들리죠?

근데 문제가 있었어요.

배포할 때마다 똑같은 걸 계속 검색했어요. Apple Silicon 때문에 Tailwind CSS가 프로덕션에서 안 먹히는 거, Docker 캐시가 깨지는 거, Kamal 락 충돌... 같은 에러가 날 때마다 다시 검색하고, 다시 읽고, 다시 시도하고. 배포 한 번에 2-3시간이 걸렸어요.

그것도 "배포 성공"까지만요. 에러 없으면 10분이면 돼요. 근데 에러가 뜰 때마다 검색 스파이럴에 빠졌어요.

웹 검색 가이드의 한계

Kamal 배포를 예로 들어볼게요.

"Kamal deploy Tailwind CSS not working"을 구글에 검색하면 답이 나와요. 근데 그 답이 내 환경에 맞는지 확인하는 데 더 오래 걸려요.

문제웹 검색 결과내 실제 환경
Tailwind 안 됨"npm rebuild 해라"Apple Silicon + QEMU 이슈 — 완전히 다른 수정이 필요
Docker 빌드 실패"캐시 지워라".dockerignore가 builds 폴더를 제외하고 있었음
컨테이너 안 뜸"로그 확인해라"OpenAI 젬이 API 키 없이 자동 로딩됨

검색 결과가 틀린 건 아니었어요. 근데 그 답을 내 프로젝트, 내 서버, 내 환경에 연결하는 것 — 그 정신적 작업을 매번 해야 했어요.

그래서 스킬을 만들었어요

Claude Code에는 "스킬"이라는 개념이 있어요. 마크다운 파일 하나를 쓰고 전체 가이드를 규칙으로 먹이는 거예요.

제 /deploy 스킬은 671줄짜리 배포 자동화 에이전트예요. 안에 뭐가 있냐면:

1. 지금까지 만난 모든 에러 패턴

🔴 CRITICAL: Tailwind CSS v4 + Apple Silicon QEMU 이슈
🔴 SQLite Database Locked
🔴 Development-only Gem LoadError
🟡 Docker build cache corruption
🟡 Kamal Lock conflicts
🟡 Optional Gem auto-loading failures

이 에러들을 만날 때마다 증상 → 원인 → 수정법을 스킬 파일에 직접 적었어요. 다음에 같은 에러가 나면 Claude가 패턴 매칭하고 자동으로 고쳐요.

2. 자동화된 해결 파이프라인

STEP 1: 사전 검증 (Git 상태, .dockerignore, Tailwind 빌드)
↓
STEP 2: 사전 빌드 (Apple Silicon 워크어라운드)
↓
STEP 3: Kamal 배포
↓
STEP 4: 에러 분석 → 패턴 매칭 → 자동 수정
↓
STEP 5: 최대 5회 재시도
↓
STEP 6: 배포 후 검증 (CSS 파일 크기 비교까지!)
↓
STEP 7: 성공/실패 리포트

3. 사람 개입 — 진짜 필요할 때만

SSH 키 문제, DNS 설정, 서버 권한 — Claude가 못 고치는 것들. 스킬은 그런 것들만 물어봐요. 나머지는 전부 자동으로 처리돼요.

Before vs After

지표웹 검색/deploy 스킬
배포 시간 (에러 없을 때)~10분~10분
배포 시간 (에러 있을 때)2-3시간15분
같은 에러 재발다시 검색자동 해결
Apple Silicon 대응매번 기억해야 함사전 검증에서 자동 처리
배포 후 검증수동 체크자동화 (CSS 크기 비교 포함)

핵심 차이는 에러가 났을 때예요. 웹 검색은 매번 0에서 다시 시작해요. 근데 스킬은 이미 수정법을 알고 있어요 — 패턴 매칭하고, 솔루션 적용하고, 재시도해요.

이 패턴은 모든 배포에 적용돼요

/deploy가 웹 서버에서 잘 작동하는 걸 보고 생각했어요 — 모든 배포에 이렇게 하면 되잖아?

앱 배포도 마찬가지예요. "iOS App Store deployment guide"를 검색하면 결과가 수백 개 나오는데, 내 프로젝트의 인증서 설정, 프로비저닝 프로파일, 빌드 넘버 규칙은 매번 달라요. 안드로이드도 마찬가지 — 서명 키, Google Play Console 설정, 빌드 변형... 매번 검색하고, 매번 헤매요.

근데 스킬로 만들면? 내 프로젝트의 서명 키 경로, 내 앱의 번들 ID, 내 CI/CD 파이프라인 — 전부 다 거기 있어요. /ios-deploy 치면 끝. /and-deploy 치면 끝.

웹 검색 가이드는 "일반적으로 이렇게 해"라고 해요. 스킬은 "너의 프로젝트에서는 이렇게 해"라고 해요.

핵심 인사이트

웹 검색이 나쁜 건 아니에요. 문제를 처음 만났을 때는 검색하는 게 맞아요. 근데 같은 문제를 두 번째 검색하고 있다면, 그게 스킬로 만들어야 한다는 신호예요.

증상, 원인, 수정법을 마크다운 파일 하나에 적어두세요. 다음에는 검색할 필요가 없어요. AI가 읽고, 적용하고, 검증해요 — 전부 자동으로.

검색은 문제를 발견하는 도구예요. 스킬은 문제를 없애는 도구예요.

— 제니

스킬 받기

이 스킬들을 직접 써보고 싶으신가요? 전체 소스 파일은 여기에 있어요:

  • /deploy — 671줄 에러 패턴과 자동 복구를 갖춘 Kamal 배포 자동화 (웹 서버)
  • /and-deploy — Android AAB 빌드 + Google Play Console 업로드 자동화
  • /ios-deploy — iOS IPA 빌드 + App Store Connect 업로드 (Transporter 경유)

사용법

  1. Gist 페이지에서 Raw를 클릭하고 전체 내용을 복사하세요
  2. SKILL.md 파일로 프로젝트에 저장하세요:
    .claude/skills/{skill-name}/SKILL.md
  3. Claude Code를 열고 /{skill-name}을 입력해서 실행하세요

Responses (0)