Claude Code 실전 (3): Custom Skills로 팀 표준 만들기

/setup-dev 하나로 신입 온보딩 완료. /deploy staging 한 줄로 배포 자동화. Custom Skills로 팀만의 명령어를 만드는 법.

TL;DR

Skills: 재사용 가능한 Claude 명령어 세트
팀 표준화: 복잡한 워크플로우를 단일 명령어로
온보딩 자동화: /setup-dev로 환경 설정 일원화
지식 공유: 암묵지를 명시적 명령어로 전환

1. Custom Skills란?

기존의 문제

신입 개발자 첫 날:

"개발 환경 어떻게 설정하나요?" → "위키 보세요" (위키는 3개월 전 버전)
"node 버전은요?" → "nvm use"
".env 파일은요?" → ".env.example 복사해서..."
"DB는요?" → "docker-compose up 하시고..."
결과: 반나절 소요

Skills를 사용하면

신입 개발자 첫 날:

"개발 환경 어떻게 설정하나요?" → "Claude에서 /setup-dev 실행하세요"
자동으로 Node.js 버전 확인, 의존성 설치, .env 생성, DB 실행, 마이그레이션 완료
결과: 5분 소요

Skills는 팀의 암묵지를 실행 가능한 명령어로 바꿉니다.

2. Skill 구조

파일 위치

text

프로젝트/
├── .claude/
│   └── skills/
│       ├── setup-dev.md      # 개발 환경 설정
│       ├── deploy.md         # 배포 자동화
│       ├── create-feature.md # 기능 생성 템플릿
│       └── review-pr.md      # PR 리뷰 가이드
└── CLAUDE.md

기본 구조

markdown

# /skill-name

## Description
이 스킬이 무엇을 하는지 한 줄 설명

## Arguments
- `arg1`: 첫 번째 인자 설명 (필수/선택)
- `arg2`: 두 번째 인자 설명 (기본값: xyz)

## Steps
1. 첫 번째 단계
2. 두 번째 단계
3. 세 번째 단계

## Example
/skill-name arg1 arg2

3. 실전 예제: /setup-dev

`.claude/skills/setup-dev.md`

markdown

# /setup-dev

## Description
새로운 개발자를 위한 로컬 개발 환경 완전 자동 설정

## Prerequisites
- macOS 또는 Linux
- Docker Desktop 설치됨
- Git 설치됨

## Steps

### 1. 시스템 요구사항 확인
- Node.js 18+ 설치 확인, 없으면 nvm으로 설치 안내
- pnpm 설치 확인, 없으면 `npm install -g pnpm` 실행
- Docker 실행 중인지 확인

### 2. 의존성 설치

pnpm install

text

### 3. 환경 변수 설정
- `.env.example`을 `.env.local`로 복사
- 필요한 기본값 설정:
  - `DATABASE_URL`: `postgresql://localhost:5432/myapp_dev`
  - `REDIS_URL`: `redis://localhost:6379`
- 사용자에게 외부 API 키가 필요한지 확인

### 4. 데이터베이스 설정

docker-compose up -d postgres redis

pnpm db:migrate

pnpm db:seed

text

### 5. 확인

pnpm dev

text

- http://localhost:3000 접속 가능한지 확인
- 기본 로그인 계정 안내: test@example.com / password123

## Troubleshooting
- 포트 3000 사용 중: `lsof -i :3000`으로 확인 후 종료
- DB 연결 실패: Docker가 실행 중인지 확인
- 권한 에러: `sudo chown -R $(whoami) .`

## Success Message
🎉 개발 환경 설정 완료!
- 개발 서버: http://localhost:3000
- DB Admin: http://localhost:5555 (pnpm db:studio)
- 문서: http://localhost:3000/docs

4. 실전 예제: /deploy

`.claude/skills/deploy.md`

markdown

# /deploy

## Description
지정된 환경에 애플리케이션 배포

## Arguments
- `environment`: 배포 환경 (staging | production) - 필수
- `--skip-tests`: 테스트 스킵 (production에서는 무시됨)

## Pre-checks
1. 현재 브랜치 확인
   - staging: 모든 브랜치 가능
   - production: main 브랜치만 가능
2. 커밋되지 않은 변경사항 확인
3. 원격과 동기화 상태 확인

## Steps

### Staging 배포

1. 테스트 실행

pnpm test

pnpm lint

2. 빌드

pnpm build

3. 배포

git push origin HEAD:staging

text

- Vercel/Netlify 자동 배포 트리거됨
- 배포 URL: https://staging.myapp.com

### Production 배포

1. 반드시 모든 체크 통과

pnpm test

pnpm lint

pnpm typecheck

pnpm build

2. 태그 생성

VERSION=$(node -p "require('./package.json').version")

git tag -a "v$VERSION" -m "Release v$VERSION"

git push origin "v$VERSION"

3. main 브랜치 푸시

git push origin main

text

## Post-deploy
- Slack 채널 #deployments에 알림 발송
- 배포 후 5분 내 health check 확인
- 문제 발생 시 롤백 명령어: `/rollback production`

## Examples

/deploy staging

/deploy staging --skip-tests

/deploy production

5. 실전 예제: /create-feature

`.claude/skills/create-feature.md`

markdown

# /create-feature

## Description
새로운 기능을 위한 파일 구조와 보일러플레이트 생성

## Arguments
- `name`: 기능 이름 (kebab-case) - 필수
- `--with-api`: API 엔드포인트 포함
- `--with-tests`: 테스트 파일 포함

## Generated Structure

src/features/{name}/

├── components/

│ └── {Name}View.tsx

├── hooks/

│ └── use{Name}.ts

├── api/

│ └── {name}.api.ts # --with-api

├── types/

│ └── {name}.types.ts

├── __tests__/ # --with-tests

│ └── {Name}.test.tsx

└── index.ts

text

## Component Template

// src/features/{name}/components/{Name}View.tsx

import { use{Name} } from '../hooks/use{Name}';

import type { {Name}Props } from '../types/{name}.types';

export function {Name}View({ ... }: {Name}Props) {

const { data, isLoading, error } = use{Name}();

if (isLoading) return <LoadingSpinner />;

if (error) return <ErrorMessage error={error} />;

return (

{/* TODO: Implement UI */}

</div>

);

}

text

## Hook Template

// src/features/{name}/hooks/use{Name}.ts

import { useQuery } from '@tanstack/react-query';

import { {name}Api } from '../api/{name}.api';

export function use{Name}() {

return useQuery({

queryKey: ['{name}'],

queryFn: {name}Api.getAll,

});

}

text

## After Creation
1. 생성된 파일 목록 출력
2. index.ts에 export 추가 안내
3. 라우트 설정이 필요하면 안내

## Examples

/create-feature user-profile

/create-feature shopping-cart --with-api --with-tests

6. 팀 온보딩 최적화

온보딩 체크리스트를 Skill로

`.claude/skills/onboarding-checklist.md`

markdown

# /onboarding-checklist

## Description
신입 개발자 온보딩 진행 상황 체크 및 다음 단계 안내

## Checklist

### Day 1: 환경 설정
- [ ] `/setup-dev` 실행 완료
- [ ] Slack 채널 참여 (#dev, #deployments, #alerts)
- [ ] GitHub 팀 추가됨
- [ ] Jira/Linear 접근 권한

### Day 2: 코드베이스 이해
- [ ] CLAUDE.md 읽기
- [ ] 아키텍처 문서 읽기 (docs/architecture.md)
- [ ] 첫 번째 Good First Issue 할당받기

### Day 3-5: 첫 PR
- [ ] 로컬에서 기능 개발
- [ ] `/create-feature` 사용해보기
- [ ] PR 생성 및 리뷰 받기
- [ ] `/deploy staging` 체험

### Week 2: 심화
- [ ] 온콜 로테이션 이해
- [ ] 모니터링 대시보드 익히기
- [ ] 장애 대응 프로세스 숙지

## Current Progress
진행 상황을 체크하고 다음 할 일을 안내해주세요.

7. PR 리뷰 표준화

`.claude/skills/review-pr.md`

markdown

# /review-pr

## Description
PR 리뷰 수행 및 팀 표준에 따른 피드백 제공

## Arguments
- `pr_number`: PR 번호 또는 URL (선택, 없으면 현재 브랜치)

## Review Checklist

### 1. 코드 품질
- [ ] 네이밍 컨벤션 준수 (CLAUDE.md 참조)
- [ ] 불필요한 코드 중복 없음
- [ ] 함수/컴포넌트 크기 적절 (50줄 이하 권장)
- [ ] 에러 처리 적절함

### 2. 타입 안전성
- [ ] `any` 사용 없음
- [ ] 적절한 타입 정의
- [ ] null/undefined 처리

### 3. 테스트
- [ ] 새 기능에 테스트 포함
- [ ] 엣지 케이스 커버
- [ ] 테스트가 의미 있음 (구현 세부사항 X)

### 4. 보안
- [ ] 사용자 입력 검증
- [ ] SQL Injection 방지
- [ ] XSS 방지
- [ ] 민감 정보 노출 없음

### 5. 성능
- [ ] N+1 쿼리 없음
- [ ] 불필요한 리렌더링 없음
- [ ] 큰 번들 추가 시 정당화

## Output Format
각 항목에 대해:
- ✅ 통과
- ⚠️ 제안 (선택적 개선)
- ❌ 필수 수정

## Example

/review-pr 123

/review-pr https://github.com/org/repo/pull/123

8. Skill 작성 팁

1) 명확한 단계 정의

❌ 모호함:

markdown

## Steps
1. 환경 설정
2. 코드 작성
3. 테스트

✅ 구체적:

markdown

## Steps
1. Node.js 18+ 설치 확인
   - `node --version` 실행
   - 18 미만이면 `nvm install 18 && nvm use 18`
2. 의존성 설치
   - `pnpm install` 실행
   - 에러 시 `rm -rf node_modules && pnpm install`

2) 예외 상황 처리

markdown

## Troubleshooting
- **포트 충돌**: `lsof -i :3000`으로 확인 후 해당 프로세스 종료
- **권한 에러**: Docker Desktop 실행 확인
- **M1 Mac**: `--platform linux/amd64` 옵션 필요할 수 있음

3) 환경별 분기

markdown

## Environment-specific

### macOS

brew install postgresql

text

### Ubuntu

sudo apt-get install postgresql

text

### Windows (WSL)

wsl --install

WSL 내에서 Ubuntu 명령어 사용

9. 팀별 추천 Skills

프론트엔드 팀

Skill	용도
`/setup-dev`	개발 환경 설정
`/create-component`	컴포넌트 보일러플레이트
`/create-page`	Next.js 페이지 생성
`/storybook-story`	Storybook 스토리 생성
`/a11y-check`	접근성 검사

백엔드 팀

Skill	용도
`/setup-dev`	개발 환경 설정
`/create-endpoint`	API 엔드포인트 생성
`/create-migration`	DB 마이그레이션 생성
`/api-docs`	OpenAPI 스펙 업데이트
`/load-test`	부하 테스트 실행

DevOps 팀

Skill	용도
`/deploy`	환경별 배포
`/rollback`	롤백 실행
`/scale`	서비스 스케일 조정
`/logs`	로그 조회
`/incident`	장애 대응 체크리스트

마무리

Custom Skills는 단순한 자동화가 아닙니다.

팀의 암묵지를 실행 가능한 형태로 문서화하는 것입니다.

장점	효과
온보딩 시간 단축	반나절 → 30분
실수 방지	체크리스트 자동화
지식 공유	위키 → 실행 가능한 명령어
표준화	팀원 간 일관성

다음 편에서는 MCP 서버를 구축해 Claude가 외부 시스템과 통신하는 방법을 다룹니다.

시리즈 목차

Context가 전부다
Hooks로 워크플로우 자동화
Custom Skills로 팀 표준 만들기 (현재 글)
MCP 서버 구축하기
모델 믹스 전략