프롬프트를 직접 쓰느라 지쳤나요? Claude Code의 이 기능으로 생산성이 3배 올랐습니다

실제 경험담

작년 10월, 2,000줄이 넘는 거대한 클래스로 이루어진 React 프로젝트를 리팩터링해야 했습니다. 보기만 해도 머리가 아팠습니다. Claude Code에 코드 최적화를 부탁할 때마다 다음 요구 사항을 반복해서 설명해야 했습니다.

• “TypeScript strict 모드를 사용해야 해”
• “API 호출에는 오류 처리를 추가해”
• “컴포넌트는 단일 책임 원칙을 따라야 해”
  이 요구 사항을 복사하고 붙여 넣는 데만 적어도 2~3분이 걸렸습니다. 더 답답한 점은 대화를 열댓 번 주고받고 나면 Claude Code가 처음의 요구 사항을 자주 “잊고” 다시 규칙에 맞지 않는 코드를 작성한다는 것이었습니다.
  그러다 문서에서 Skill 기능을 발견했습니다.
  일주일 동안 사용해 본 뒤 반복되는 요구 사항을 모두 몇 개의 skill 파일로 만들었습니다. 이제 @skill react-refactor 한 줄만 입력하면 Claude Code가 바로 무엇을 해야 하는지 압니다. 원래 사흘은 걸릴 것으로 예상했던 2,000줄짜리 클래스를 이틀 오후 만에 리팩터링했습니다.

Skill이란 무엇인가

간단히 말하면 Skill은 Claude Code에 설치하는 스킬 패키지입니다.
.claude/skills/ 디렉터리에 Markdown 파일을 만들고 자주 쓰는 프롬프트, 작업 흐름, 코드 규칙을 적어 둡니다. 필요할 때 @skill 스킬명 한 줄로 호출할 수 있습니다. 게임 캐릭터에 서로 다른 스킬을 장착하는 것과 같습니다. 공격이 필요할 때는 공격 스킬을, 방어가 필요할 때는 방어 스킬을 장착하는 식입니다.
가장 간단한 예시를 살펴보겠습니다.

---

title: "React 코드 리뷰 전문가"
description: "React 코드의 품질, 성능, 모범 사례를 전문적으로 검토합니다."

---

# React 코드 리뷰 절차
당신은 경험이 풍부한 React 코드 리뷰 전문가입니다. 다음 기준에 따라 코드를 검토하세요.
## 검토 중점
1. **컴포넌트 설계**
   - 단일 책임 원칙
   - Props 타입 정의의 완전성
   - 컴포넌트 분리의 적절성
2. **성능 최적화**
   - 불필요한 재렌더링
   - useMemo/useCallback 사용
   - 목록 렌더링의 key 값
3. **코드 품질**
   - TypeScript 타입 안전성
   - 오류 경계 처리
   - 접근성(a11y)
## 출력 형식
- 문제 목록(심각도순)
- 구체적인 코드 개선안
- 우선순위 표시(P0/P1/P2)

이 파일을 .claude/skills/react-review.md로 저장하면 이후 React 코드를 검토할 때 @skill react-review만 입력하면 됩니다. Claude Code는 정의한 기준을 엄격히 따라 검토합니다.

수동 프롬프트 작성이 한계에 부딪히는 이유

저도 예전에는 프롬프트 엔지니어처럼 Notion에 정성껏 다듬은 프롬프트 템플릿을 수십 개 보관했습니다. 하지만 몇 달 사용해 보니 이 방식에는 분명한 문제가 있었습니다.
반복 작업이 너무 많습니다
매번 Notion에서 복사해 붙여 넣어야 하고, 때로는 현재 프로젝트에 맞춰 단어 몇 개를 고쳐야 합니다. 하루 동안 프롬프트를 복사하고 붙여 넣는 데만 30분이 걸립니다.
버전 관리가 혼란스럽습니다
오늘 쓰는 프롬프트가 지난주 것과 달라 결과도 일정하지 않습니다. “지난번에 잘 됐던 버전”으로 돌아가고 싶어도 찾을 수 없습니다.
팀 협업이 엉망이 됩니다
제가 만든 좋은 프롬프트를 동료가 쓰려면 메신저로 직접 보내야 합니다. 동료가 개선하면 다시 수동으로 공유받아야 합니다. 석기 시대와 다를 바 없는 효율입니다.
AI가 잊어버립니다
긴 대화에서 Claude Code는 처음의 요구 사항을 쉽게 잊습니다. 20번째 대화쯤 되면 하지 말라고 했던 실수를 다시 반복하는 모습을 보게 됩니다.
Skill은 이 문제를 한 번에 해결합니다.

• 버전 관리: Git으로 관리하므로 언제든 이전 버전으로 돌아갈 수 있습니다.
• 공유 가능: 팀 저장소를 받으면 모든 팀원이 동기화됩니다.
• 지속 적용: 대화가 길어져도 효력이 사라지지 않습니다.

"Skill의 핵심 가치는 재사용성과 일관성입니다. 프롬프트 엔지니어링을 유지 관리하고 공유할 수 있는 프로젝트 자산으로 바꿉니다."

첫 번째 Skill: API 생성기

그 전자상거래 프로젝트에서 백엔드 개발자가 API 100개가 넘는 Swagger 문서를 건넸습니다. 수동으로 연동하려면 API 하나마다 다음 항목을 작성해야 했습니다.

1. TypeScript 타입 정의
2. axios 요청 함수
3. 오류 처리 로직
4. loading 상태 관리
   계산해 보니 API 100개에 약 30시간이 필요했습니다.
   저는 한 시간을 들여 api-generator skill을 만들었습니다.

---

title: "API 코드 생성기"
description: "API 문서를 바탕으로 TS 타입 정의와 axios 래퍼를 생성합니다."
version: "1.3.0"

---

# API 코드 생성 전문가
당신은 프론트엔드와 백엔드 API 연동에 능숙한 풀스택 엔지니어입니다. API 문서를 바탕으로 고품질 TypeScript 코드를 생성하는 것이 당신의 임무입니다.
## 생성할 내용
### 1. TypeScript 타입 정의
```typescript
// 요청 매개변수 타입
interface GetUserRequest {
  userId: string;
  includeDetails?: boolean;
}
// 응답 데이터 타입
interface GetUserResponse {
  id: string;
  name: string;
  email: string;
  createdAt: string;
}

2. Axios 요청 함수

import request from '@/utils/request';
export const getUserAPI = async (
  params: GetUserRequest
): Promise<GetUserResponse> => {
  try {
    const response = await request.get<GetUserResponse>('/api/user', { params });
    return response.data;
  } catch (error) {
    console.error('사용자 정보 가져오기 실패:', error);
    throw error;
  }
};

3. React Hook 래퍼(선택 사항)

export const useGetUser = (userId: string) => {
  const [data, setData] = useState<GetUserResponse | null>(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<Error | null>(null);
  useEffect(() => {
    const fetchData = async () => {
      setLoading(true);
      try {
        const result = await getUserAPI({ userId });
        setData(result);
      } catch (err) {
        setError(err as Error);
      } finally {
        setLoading(false);
      }
    };
    fetchData();
  }, [userId]);
  return { data, loading, error };
};

코드 규칙

• 이름은 camelCase 명명법을 따릅니다.
• API 함수 이름은 API로 끝나야 합니다.
• Hook 함수 이름은 use로 시작해야 합니다.
• 모든 비동기 함수에는 오류 처리가 있어야 합니다.
• 내보내는 타입과 함수에는 모두 JSDoc 주석을 추가해야 합니다.

출력 형식

1. 먼저 타입 정의를 출력합니다.
2. 그다음 API 함수를 출력합니다.
3. 자주 쓰는 API라면 Hook 래퍼도 생성합니다.
4. 마지막으로 사용 예시를 제공합니다.

이 skill을 사용하자 API 하나를 연동하는 시간이 30분에서 5분으로 줄었습니다. API 100개를 모두 연동하는 데 이틀밖에 걸리지 않았습니다. 더 중요한 점은 신입 팀원도 같은 규칙으로 코드를 생성할 수 있어 프로젝트 전체의 코드 스타일이 매우 일관되게 유지된다는 것입니다.

## 고급 활용법: 여러 Skill을 함께 사용하기
익숙해지고 나니 skill 하나만으로는 부족하다는 것을 알게 됐습니다. 실제 개발에서는 여러 skill을 함께 사용해야 하는 경우가 많습니다.
예를 들어 레거시 코드를 리팩터링할 때의 표준 절차는 다음과 같습니다.
```bash
# 1단계: 코드 문제 분석
@skill code-analyzer src/legacy/UserService.ts
# 2단계: 리팩터링 계획 수립
@skill refactor-planner
# 3단계: 테스트 케이스 생성(리팩터링 전에 반드시 테스트로 안전망 확보)
@skill test-generator
# 4단계: 리팩터링 수행
(직접 리팩터링하거나 Claude Code의 도움을 받음)
# 5단계: 최종 코드 리뷰
@skill code-reviewer

이 네 개의 skill을 차례로 호출하면 완전한 리팩터링 워크플로가 됩니다. 저는 이 과정을 자동 실행하는 shell 스크립트까지 작성했습니다.

#!/bin/bash
# refactor-workflow.sh
echo "🔍 1/4단계: 코드 문제 분석 중..."
claude-code @skill code-analyzer $1
read -p "계속하려면 Enter 키를 누르세요..."
echo "📋 2/4단계: 리팩터링 계획 수립 중..."
claude-code @skill refactor-planner
read -p "계속하려면 Enter 키를 누르세요..."
echo "🧪 3/4단계: 테스트 케이스 생성 중..."
claude-code @skill test-generator
read -p "테스트를 실행하고 통과를 확인한 뒤 Enter 키를 누르세요..."
echo "✅ 4/4단계: 최종 코드 리뷰 중..."
claude-code @skill code-reviewer

이 스크립트로 2,000줄짜리 거대한 클래스를 리팩터링해 책임이 명확한 작은 클래스 7개로 나눴습니다. 테스트 커버리지는 40%에서 85%로 올랐고, 전체 과정도 예상보다 훨씬 순조로웠습니다.

Railway - 현대적인 배포 플랫폼, 번거로운 운영 없이 몇 분 만에 라이브

지금 시작 →광고

팀 공유: Skill을 인프라로 관리하기

현재 우리 팀은 skill을 인프라처럼 관리합니다. team-skills를 보관할 전용 Git 저장소를 만들었습니다.

team-skills/
├── frontend/
│   ├── react-review.md          # React 코드 리뷰
│   ├── vue-component-gen.md     # Vue 컴포넌트 생성
│   └── css-optimizer.md         # CSS 성능 최적화
├── backend/
│   ├── api-design.md            # API 설계 규칙
│   ├── database-review.md       # 데이터베이스 검토
│   └── security-audit.md       # 보안 감사
└── common/
    ├── code-cleaner.md          # 코드 정리
    ├── test-generator.md        # 테스트 생성
    └── commit-msg.md            # Git 커밋 메시지 생성

각 개발자는 로컬 프로젝트에서 이 저장소로 심볼릭 링크를 만듭니다.

# 최초 1회 설정
git clone [email protected]:your-team/team-skills.git ~/.team-skills
ln -s ~/.team-skills/* .claude/skills/

효과는 즉시 나타났습니다.

• 신입 친화적: 입사 첫날부터 완전한 skill 라이브러리를 사용해 바로 규칙에 맞는 코드를 작성할 수 있습니다.
• 자동 동기화: 팀이 skill을 업데이트하면 모든 팀원이 git pull로 최신 버전을 받을 수 있습니다.
• 코드 일관성: 누가 작성하든 코드 스타일이 매우 일관됩니다.
  지난달에 인턴이 한 명 합류했는데 둘째 날부터 팀 규칙에 맞는 코드를 작성했습니다. 예전 같으면 최소 일주일은 교육해야 했을 것입니다.

Skill과 CLAUDE.md는 최고의 조합입니다

Skill을 더 강력하게 활용하려면 프로젝트 루트의 CLAUDE.md와 함께 사용하면 됩니다.
CLAUDE.md에 프로젝트 전역 규칙을 정의합니다.

# 프로젝트 컨텍스트
- 기술 스택: React 18 + TypeScript 5.0 + Vite 4
- 코드 규칙: Airbnb ESLint 규칙
- 커밋 규칙: Conventional Commits
- 상태 관리: Zustand(Redux 사용 금지)
## 중요 규칙
- 모든 컴포넌트에는 완전한 TypeScript 타입 정의가 있어야 합니다.
- API 호출은 모두 src/utils/request.ts 래퍼를 사용합니다.
- 컴포넌트 파일명은 PascalCase를 사용합니다(예: UserProfile.tsx).
- 유틸리티 함수 파일명은 camelCase를 사용합니다(예: formatDate.ts).
## 디렉터리 구조
src/
├── components/    # 공용 컴포넌트
├── pages/        # 페이지 컴포넌트
├── hooks/        # 사용자 정의 Hooks
├── utils/        # 유틸리티 함수
├── services/     # API 서비스
└── stores/       # Zustand 상태 관리

그런 다음 skill에서 이 규칙을 참조합니다.

---

title: "React 컴포넌트 생성기"

---

# 컴포넌트 생성 지침
CLAUDE.md에 정의된 기술 스택, 디렉터리 구조, 명명 규칙을 엄격히 준수해 React 컴포넌트를 생성하세요.
생성된 컴포넌트는 반드시 다음 조건을 충족해야 합니다.
- TypeScript 사용
- 프로젝트의 ESLint 규칙 준수
- 올바른 디렉터리에 배치
- 프로젝트에서 정한 상태 관리 방식 사용

이렇게 하면 skill이 CLAUDE.md 설정을 자동으로 읽고 프로젝트 규칙에 완전히 맞는 코드를 생성합니다. 새 프로젝트를 clone한 직후에도 skill이 곧바로 적응합니다.

제가 꼭 쓰는 Skill 5가지

6개월 동안 사용하면서 skills 디렉터리에 20개가 넘는 skill이 쌓였습니다. 그중 가장 자주 쓰는 몇 가지를 소개합니다.

1. 테스트 케이스 생성기(test-gen.md)

기능 코드를 작성한 뒤 가장 번거로운 일은 테스트를 추가하는 것입니다. 이 skill은 함수 로직을 분석하고 경계 조건과 예외 상황을 포함한 단위 테스트를 자동 생성합니다.
효과: 테스트 커버리지가 40%에서 85%로 올랐고 테스트 작성 시간도 절반 이상 줄었습니다.

2. Git 커밋 메시지 생성기(commit-msg.md)

커밋할 때마다 commit message를 고민하는 일은 꽤 번거롭습니다. 이 skill은 git diff 내용을 분석해 Conventional Commits 규칙에 맞는 커밋 메시지를 자동 생성합니다.
출력 예시:

feat(user-auth): OAuth2.0 로그인 기능 추가
- Google 및 GitHub 서드파티 로그인 연동
- JWT token 갱신 메커니즘 추가
- 사용자 권한 검증 미들웨어 개선
Closes #123

코드는 30줄뿐이지만 매일 사용하는 skill입니다. 지금까지 절약한 시간을 합치면 이미 몇 시간이 됩니다.

Alibaba Cloud - 개발자 클라우드 1순위, Lighthouse 서버 15% 할인

15% 할인 받기 →광고

3. 코드 리팩터링 도우미(refactor.md)

레거시 코드를 개선해야 하지만 어디서 시작할지 모를 때 이 skill은 다음을 수행합니다.

• 코드 스멜 식별
• 리팩터링 우선순위 제시
• 단계별 리팩터링 계획 제공
• 리팩터링 전후 기능이 동일하도록 보장
  앞에서 말한 2,000줄짜리 거대한 클래스도 이 skill로 해결했습니다.

4. 보안 검토 전문가(security-audit.md)

코드의 보안 문제를 전문적으로 검사합니다.

• SQL 인젝션 위험
• XSS 공격 방어
• 민감한 정보 유출
• 권한 검증의 완전성
  한번은 출시 전에 이 skill로 검사했다가 잠재적인 보안 취약점 3개를 발견해 식은땀이 났습니다.

5. 문서 생성기(doc-gen.md)

프로젝트 문서가 늘 코드보다 뒤처지나요? 이 skill은 코드를 바탕으로 API 문서를 자동 생성하고 함수 주석을 추출해 Markdown을 만들며 변경 로그까지 관리합니다.
문서 업데이트 시간이 2시간에서 10분으로 줄었고, 이제 “코드는 바뀌었는데 문서는 그대로인” 일도 없습니다.

좋은 Skill을 작성하는 5가지 팁

6개월간 사용하며 skill 작성에 관한 몇 가지 경험을 정리했습니다.

1. Frontmatter를 꼼꼼히 작성하세요

없어도 될 것처럼 보이지만 title과 description은 skill 목록에 표시됩니다.

---

title: "풀스택 코드 리뷰 전문가"
description: "프론트엔드와 백엔드 코드를 검토하며 보안, 성능, 유지보수성에 집중합니다."
version: "2.1.0"
tags: ["코드 리뷰", "보안", "성능"]

---

version 필드는 버전 관리에, tags는 분류와 검색에 편리합니다.

2. 역할을 명확하게 정의하세요

“당신은 … 전문가입니다” 같은 문장으로 시작하면 Claude Code가 역할을 빠르게 파악하는 데 도움이 됩니다.

당신은 10년 경력의 풀스택 엔지니어이며 코드 리뷰와 보안 감사에 능숙합니다.

단순히 “코드를 검토하세요”라고 말하는 것보다 훨씬 효과적입니다.

KiloClaw - 기업용 매니지드 OpenClaw, AI Agent 오케스트레이션 및 스마트 라우팅

시작하기 →광고

3. 비교 예시로 설명하세요

✅와 ❌로 좋은 코드와 나쁜 코드를 비교하면 Claude Code가 더 정확히 이해합니다.

### SQL 인젝션 위험
❌ 위험한 코드:
```javascript
const query = `SELECT * FROM users WHERE id = ${userId}`;

✅ 안전한 코드:

const query = 'SELECT * FROM users WHERE id = ?';
db.query(query, [userId]);

### 4. 출력 형식을 구체적으로 지정하세요
"제안해 주세요"라고만 말하지 말고 "다음 형식으로 출력하세요"라고 해야 합니다.
```markdown
## 출력 형식
### 🔴 심각한 문제(반드시 수정)
- [파일명:줄 번호] 문제 설명
- 위험 설명
- 수정 제안(코드 예시 포함)
### 🟡 개선 권장 사항
- [파일명:줄 번호] 문제 설명
- 개선 이유
- 최적화 방안

5. 오류 처리 규칙을 추가하세요

문제가 발생하면 AI가 어떻게 해야 하는지 알려 주세요.

## 오류 처리
다음 상황이 발생하면:
- 코드 구문 오류: 오류 위치를 먼저 알리고 검토를 계속하지 않습니다.
- 파일에 접근할 수 없음: 사용자에게 경로를 확인하라고 안내합니다.
- 코드가 너무 많음(>5000줄): 나누어 검토할 것을 권합니다.

자주 묻는 질문

Skill이 너무 많아 이름을 기억하기 어렵나요?

명명 규칙을 활용하세요.

• review-*: 코드 리뷰
• gen-*: 코드 생성
• util-*: 유틸리티
• fix-*: 문제 수정
  제가 쓰는 이름은 review-frontend.md, gen-api.md, util-commit.md입니다.

Skill 출력이 너무 길어 읽기 어렵나요?

skill에 간결 모드를 추가하세요.

기본적으로 상세 모드를 사용합니다. 사용자가 `--brief` 매개변수를 추가하면 간결한 버전을 출력합니다.
- 문제 목록(항목당 한 줄)
- 심각도 표시
- 핵심 수정 제안

프로젝트마다 Skill의 결과가 다른가요?

skill이 능동적으로 컨텍스트를 요청하게 하세요.

## 분석 전 단계
시작하기 전에 다음을 수행하세요.
1. package.json을 읽어 의존성 버전을 파악합니다.
2. tsconfig.json을 확인해 TS 설정을 파악합니다.
3. .eslintrc를 확인해 코드 규칙을 파악합니다.
4. README.md를 살펴 프로젝트 아키텍처를 파악합니다.

마무리하며

skill 기능을 6개월 동안 사용하면서 개발 생산성이 최소 40% 향상됐습니다. 더 중요한 점은 반복적인 지적 작업에서 벗어나 진정으로 고민이 필요한 아키텍처 설계와 비즈니스 로직에 시간을 쓸 수 있게 됐다는 것입니다.
지금도 프롬프트를 직접 작성하고 있다면 다음과 같이 시작해 보세요.

1. 오늘 바로 시작하기: 코드 리뷰나 테스트 생성처럼 간단한 skill 하나부터 시작하세요.
2. 점진적으로 개선하기: 사용할 때마다 개선할 부분을 돌아보고 버전을 업데이트하세요.
3. 팀과 공유하기: 좋은 skill은 좋은 도구 라이브러리와 같으므로 함께 나누세요.
4. 꾸준히 학습하기: 공식 문서 업데이트를 확인하세요. 새 기능으로 작성 방식이 달라질 수 있습니다.
   마지막으로 한 가지 경험을 공유하겠습니다. Skill의 가치는 얼마나 복잡한가가 아니라 실제 문제를 해결하는가에 달려 있습니다. 가장 간단한 commit-msg 생성기는 30줄뿐이지만 매일 사용하며 지금까지 몇 시간이나 절약했습니다.
   지금부터 매일 반복해서 입력하는 프롬프트를 skill로 정리해 보세요. 석 달 뒤에는 오늘 시작한 자신에게 고마워할 것입니다.
   관련 자료

• Claude Code 공식 문서
• Skill 모범 사례 가이드
• 커뮤니티 Skill 템플릿 라이브러리