🏢 실무에서 사용하는 Claude Code Skills 설계 패턴

🏢 실무에서 사용하는 Claude Code Skills 설계 패턴

— “AI를 개발팀의 일원으로 만드는 아키텍처”

 

🎯 왜 ‘설계 패턴’이 중요한가?

초보 단계에서는 이렇게 접근합니다:

 

“스킬 하나 만들어볼까?”

 

하지만 실무에서는 관점이 완전히 다릅니다 👇

 

❗ “AI가 조직의 개발 규칙을 따르게 만드는 시스템”

 

즉, Skills는 개별 파일이 아니라
👉 “팀의 개발 철학 + 아키텍처 + 프로세스”를 코드화한 것입니다.

 

🧠 전체 구조: 4계층 Skills 아키텍처

실제 기업에서는 보통 다음 4계층으로 나눕니다:

1. Foundation Layer (기본 규칙)
2. Domain Layer (도메인 규칙)
3. Task Layer (작업 단위)
4. Workflow Layer (프로세스 흐름)

 

1️⃣ Foundation Layer (기본 규칙)

 

💡 “이 프로젝트에서 코드 작성 기본 방식”

 

📌 역할

• 코딩 스타일
• 에러 처리 방식
• 네이밍 규칙
• 테스트 전략

📄 예시: 01-dev-standards.skill

## Description
All code must follow project coding standards

## Rules
- Use TypeScript strict mode
- Avoid any type
- Prefer functional components
- Error handling must use Result pattern

## Examples
// ❌ Bad
fetch('/api')

// ✅ Good
apiClient.get('/api')

🔥 핵심 특징

• 모든 작업에서 거의 항상 트리거됨
• “기본 DNA” 역할

2️⃣ Domain Layer (도메인 규칙)

 

💡 “이 비즈니스 영역은 이렇게 구현해”

 

📌 역할

• 주문, 결제, 유저 등 도메인 규칙
• 데이터 구조
• 비즈니스 로직 패턴

📄 예시: 04-order-domain.skill

## Description
Handles order-related business logic

## Rules
- Order status must follow state machine
- Cancellation must validate payment state
- Use OrderService for all order mutations

## Examples
cancelOrder(orderId) {
  validateCancelable(order)
  refundPayment(order)
  updateStatus(order, 'CANCELLED')
}

🔥 핵심 특징

• “비즈니스 일관성”을 강제함
• 잘못된 로직을 AI가 스스로 피하게 만듦

3️⃣ Task Layer (작업 단위)

 

💡 “이 작업은 이렇게 구현해”

 

📌 역할

• API 생성
• 컴포넌트 생성
• 상태관리 작성

📄 예시: 03-rtk-query-api.skill

## Description
Creating API endpoints using RTK Query

## Rules
- Use createApi
- Separate endpoint per domain
- Use tagTypes for cache

## Examples
createApi({
  endpoints: (builder) => ({
    getOrders: builder.query({...})
  })
})

🔥 핵심 특징

• 가장 자주 사용됨
• “개발 생산성” 직접 상승

4️⃣ Workflow Layer (프로세스 흐름)

 

💡 “이 작업을 할 때 전체 흐름은 이렇게 진행해”

 

📌 역할

• 기능 개발 프로세스
• 문서화 자동화
• 테스트 → 배포 흐름

📄 예시: 07-feature-workflow.skill

## Description
Standard feature development workflow

## Steps
1. Define API contract
2. Implement backend
3. Generate frontend API hooks
4. Create UI
5. Write tests
6. Update documentation

🔥 핵심 특징

• 여러 스킬을 묶는 상위 개념
• “개발 방식 자체”를 통제

 

⚙️ 실제 기업에서의 설계 전략

🎯 전략 1: “스킬은 작게, 조합은 크게”

❌ 안 좋은 예

• frontend-all-in-one.skill

✅ 좋은 예

• api.skill
• component.skill
• validation.skill

👉 필요할 때 조합되도록 설계

 

🎯 전략 2: 트리거는 “의도 기반”으로 설계

❌ 나쁜 트리거

"코드 작성"

✅ 좋은 트리거

"API endpoint 추가"
"React 컴포넌트 생성"
"주문 취소 구현"

👉 사용자의 자연어 요청과 맞아야 함

 

🎯 전략 3: Example이 핵심이다

Claude는 규칙보다 예제에 더 강하게 영향받습니다

👉 그래서 실무에서는:

Rules 30%
Examples 70%

 

🎯 전략 4: “금지 규칙”을 명확히

## Anti-patterns
- Do not call API directly
- Do not mutate state directly

👉 이게 없으면 AI는 계속 실수합니다

 

🧪 실전 운영 방식 (중요)

🔁 운영 사이클

1. 개발 중 패턴 발견
2. 스킬 생성
3. 실제 사용
4. 문제 발생
5. 스킬 수정

👉 이 루프가 핵심입니다

 

📊 실제로 자주 발생하는 문제

❌ 문제 1: 스킬이 너무 많음

👉 해결: 통합 or 계층 재설계

 

❌ 문제 2: 트리거 충돌

👉 해결: description 명확화

 

❌ 문제 3: AI가 스킬 무시

👉 해결:

• description 개선
• 예제 추가
• 직접 호출

 

🧠 고급 개념: “Skill = Prompt Engineering의 진화형”

기존 방식:

매번 프롬프트에 규칙 작성

 

Skills 방식:

규칙을 외부화 + 재사용

👉 즉:

 

💡 “지속 가능한 프롬프트 시스템”

 

 

🚀 최종 구조 (실무 템플릿)

.claude/skills/

01-foundation/
  dev-standards.skill
  error-handling.skill

02-domain/
  order.skill
  payment.skill

03-task/
  api.skill
  component.skill

04-workflow/
  feature.skill
  release.skill

---

🛒 React 쇼핑몰 프론트엔드 Skills 풀세트

— RTK Query + Feature 기반 아키텍처 기준

 

🧠 전체 아키텍처

.claude/skills/

01-foundation/
  dev-standards.skill
  error-handling.skill

02-domain/
  product-domain.skill
  cart-domain.skill
  order-domain.skill

03-task/
  api-rtk-query.skill
  component-structure.skill
  form-handling.skill

04-workflow/
  feature-development.skill
  api-integration.skill

 

1️⃣ Foundation Layer

📄 dev-standards.skill

## Description
Apply global coding standards for React + TypeScript project

## Rules
- Use TypeScript strict mode
- Do not use `any`
- Use functional components only
- Use absolute import paths (@/)

## Component Rules
- Separate container and presentational components
- Keep components under 200 lines

## Naming
- Components: PascalCase
- hooks: useSomething
- variables: camelCase

## Examples

// ❌ Bad
const data: any = fetch('/api')

// ✅ Good
const data: Product[] = await apiClient.get('/products')

 

📄 error-handling.skill

## Description
Standard error handling pattern

## Rules
- API errors must be normalized
- UI must not directly expose raw error
- Use toast or error boundary

## Example

try {
  await dispatch(createOrder())
} catch (error) {
  showToast("주문 실패")
}

 

2️⃣ Domain Layer

📄 product-domain.skill

## Description
Handles product-related logic

## Rules
- Product must have id, name, price, stock
- Always validate stock before purchase
- Use ProductCard for UI

## Example

export interface Product {
  id: string
  name: string
  price: number
  stock: number
}

 

📄 cart-domain.skill

## Description
Handles cart logic

## Rules
- Cart must persist in localStorage
- Quantity cannot exceed stock
- Use centralized cart slice

## Example

addToCart(product) {
  if (product.stock <= 0) throw Error("Out of stock")
}

 

📄 order-domain.skill

## Description
Handles order flow

## Rules
- Order must validate cart state
- Must include payment status
- Use OrderService abstraction

## Flow
1. validateCart
2. createOrder
3. processPayment

 

3️⃣ Task Layer (핵심)

📄 api-rtk-query.skill ⭐ (핵심)

## Description
Create API layer using RTK Query

## Rules
- Use createApi
- Separate by domain
- Use tagTypes for cache

## Example

export const productApi = createApi({
  reducerPath: 'productApi',
  baseQuery: fetchBaseQuery({ baseUrl: '/api' }),
  tagTypes: ['Product'],
  endpoints: (builder) => ({
    getProducts: builder.query<Product[], void>({
      query: () => '/products',
      providesTags: ['Product']
    })
  })
})

 

📄 component-structure.skill

## Description
Standard React component structure

## Rules
- Separate UI and logic
- Use hooks for logic
- No API calls inside UI component

## Example

// Container
export function ProductListContainer() {
  const { data } = useGetProductsQuery()
  return <ProductList products={data} />
}

// UI
export function ProductList({ products }) {
  return <div>{products.map(...)} </div>
}

 

📄 form-handling.skill

## Description
Handle forms using react-hook-form

## Rules
- Use react-hook-form
- Validate before submit
- No uncontrolled inputs

## Example

const { register, handleSubmit } = useForm()

<form onSubmit={handleSubmit(onSubmit)}>
  <input {...register("email")} />
</form>

 

4️⃣ Workflow Layer

📄 feature-development.skill ⭐

## Description
Standard feature development flow

## Steps
1. Define API contract
2. Create RTK Query API
3. Create container component
4. Create UI component
5. Add loading & error handling
6. Write basic test

 

📄 api-integration.skill

## Description
Integrate API into UI

## Rules
- Always handle loading
- Always handle error
- Use skeleton UI

## Example

if (isLoading) return <Skeleton />
if (error) return <ErrorMessage />

 

🧩 실제 React 프로젝트 구조

src/
├── app/
│   └── store.ts
├── features/
│   ├── product/
│   │   ├── api/
│   │   │   └── productApi.ts
│   │   ├── components/
│   │   │   ├── ProductList.tsx
│   │   │   └── ProductCard.tsx
│   │   ├── containers/
│   │   │   └── ProductListContainer.tsx
│   │   └── types.ts
│   │
│   ├── cart/
│   └── order/
│
├── shared/
│   ├── components/
│   ├── hooks/
│   └── utils/

 

💻 실제 코드 샘플 (핵심 흐름)

📄 productApi.ts

import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react'

export const productApi = createApi({
  reducerPath: 'productApi',
  baseQuery: fetchBaseQuery({ baseUrl: '/api' }),
  tagTypes: ['Product'],
  endpoints: (builder) => ({
    getProducts: builder.query({
      query: () => '/products'
    })
  })
})

export const { useGetProductsQuery } = productApi

 

📄 ProductListContainer.tsx

import { useGetProductsQuery } from '../api/productApi'
import { ProductList } from '../components/ProductList'

export function ProductListContainer() {
  const { data, isLoading, error } = useGetProductsQuery()

  if (isLoading) return <div>Loading...</div>
  if (error) return <div>Error</div>

  return <ProductList products={data} />
}

 

📄 ProductList.tsx

export function ProductList({ products }) {
  return (
    <div>
      {products.map((p) => (
        <div key={p.id}>{p.name}</div>
      ))}
    </div>
  )
}

 

🔥 실무에서 이 구조의 핵심 가치

1️⃣ AI가 “팀 규칙대로 코드 작성”

👉 그냥 이렇게 말하면:

"상품 리스트 페이지 만들어줘"

Claude는:

• api-rtk-query.skill
• component-structure.skill
• product-domain.skill
• feature-development.skill

👉 자동으로 조합해서 생성

 

2️⃣ 코드 스타일이 절대 흔들리지 않음

• 누가 작성하든 동일한 구조
• 리뷰 비용 감소

---

3️⃣ 신입 + AI 둘 다 온보딩 해결

👉 사람 + AI 동일 시스템

 

 

⚠️ 실무 팁 (진짜 중요)

❗ 반드시 해야 할 것

1. Example 많이 넣기

👉 AI는 규칙보다 예제를 더 잘 따른다

 

2. Anti-pattern 작성

## Anti-pattern
- Do not call fetch directly
- Do not mix UI and logic

 

3. 스킬은 작게 쪼개기

👉 절대 “frontend.skill” 이런 거 만들지 마세요

🚀 결론

 

💡 이 구조의 본질은 “코드 자동화”가 아닙니다

 

👉 “개발팀의 일하는 방식을 코드로 고정하는 것”