Claude Code 스킬로 API 개발 자동화하기 – api-endpoint-creator

왜 Claude Code 스킬이 필요한가?

프로젝트 규모가 커지면 새로운 API를 추가할 때마다 동일한 패턴을 반복해서 작성해야 합니다. 프레임워크가 Next.js든, Express든, NestJS든 상관없이 말입니다.

• 인증 미들웨어 설정
• 입력 검증 스키마 작성
• 에러 처리 패턴 적용
• 응답 형식 통일
• 프로젝트 컨벤션 준수

매번 기존 코드를 찾아보거나 문서를 참조하는 것은 비효율적입니다. Claude Code 스킬을 만들면 이런 반복 작업을 자동화하고, 프로젝트의 코딩 컨벤션을 일관되게 유지할 수 있습니다.

스킬의 필요성: 3가지 핵심 이유

1. 일관성 (Consistency)

프로젝트가 커질수록 여러 개발자가 참여하고, 코드 스타일이 제각각이 될 수 있습니다. 스킬은 프로젝트의 베스트 프랙티스를 코드화하여 누가 작업하든 동일한 패턴을 따르게 합니다.

2. 생산성 (Productivity)

“favorites CRUD API 만들어줘”라고 말하면, 스킬이 프로젝트 패턴에 맞는 완전한 엔드포인트 코드를 생성합니다. 보일러플레이트 작성 시간을 대폭 절약할 수 있습니다.

3. 지식 보존 (Knowledge Preservation)

프로젝트의 아키텍처 결정, 에러 처리 패턴, 검증 방식 등을 스킬에 문서화하면 팀의 암묵지가 명시지로 변환됩니다. 새로운 팀원도 스킬을 통해 빠르게 프로젝트 컨벤션을 익힐 수 있습니다.

api-endpoint-creator 스킬 생성 과정

Step 1: skill-wizard로 스킬 생성

Claude Code의 /skill-wizard 커맨드를 사용하여 대화형으로 스킬을 생성했습니다.

/skill-wizard 로 api-endpoint-creator 스킬 만들어줘

Skill Wizard는 6단계 워크플로우를 따릅니다.

Step 2: 스킬 구조 설계

생성된 스킬의 디렉토리 구조:

api-endpoint-creator/
├── SKILL.md                    # 메인 가이드 (프레임워크 감지 + 워크플로우)
└── references/
    ├── crud-template.md        # 6개 프레임워크별 CRUD 템플릿
    └── error-codes.md          # 범용 에러 처리 패턴

스킬 동작 방식: 3단계 워크플로우

Step 1: 프로젝트 자동 감지

스킬이 활성화되면 먼저 프로젝트를 분석합니다:

1. package.json 읽기 → 프레임워크, 검증 라이브러리, ORM 식별
2. API 파일 탐색 → 기존 엔드포인트 위치 파악
3. 기존 API 파일 2-3개 읽기 → 패턴 파악
4. tsconfig.json 확인 → path alias 파악

프레임워크 감지 기준:

그 다음, 기존 API 파일에서 다음 패턴을 파악합니다.

• 미들웨어/래퍼: 인증, rate limit 처리 방식
• 응답 헬퍼: 성공/에러 응답 유틸리티
• 에러 처리: 커스텀 에러 클래스, 에러 핸들러
• 검증 라이브러리: zod, joi, class-validator, yup 등
• DB/ORM: prisma, drizzle, typeorm, mongoose 등
• 디렉토리 구조: 라우트/컨트롤러/서비스 파일 위치

Step 2: 요구사항 확인

사용자에게 확인할 항목:

• 어떤 리소스의 API인가? (users, posts, products 등)
• 필요한 HTTP 메서드는? (GET, POST, PUT, DELETE)
• 인증 필요 여부? (공개/인증/관리자)
• 동적 라우트 파라미터?

Step 3: 패턴에 맞춰 생성

핵심 원칙 – 기존 프로젝트의 패턴을 그대로 따릅니다.

1. 기존 프로젝트의 import 경로를 그대로 사용
2. 기존 미들웨어/래퍼를 그대로 사용
3. 기존 응답 헬퍼를 그대로 사용
4. 기존 에러 처리 패턴을 그대로 사용
5. 기존 파일 네이밍/구조를 그대로 따름
6. 새로운 유틸리티나 패턴을 발명하지 않음

프레임워크별 코드 예시

동일한 “users CRUD API”를 각 프레임워크에서 생성하면,

Next.js App Router

// app/api/users/route.ts
import { NextRequest, NextResponse } from 'next/server';

export async function GET(request: NextRequest) {
  const users = await db.user.findMany();
  return NextResponse.json(users);
}

export async function POST(request: NextRequest) {
  const body = await request.json();
  const user = await db.user.create({ data: body });
  return NextResponse.json(user, { status: 201 });
}

Express.js

// routes/users.routes.ts
import { Router, Request, Response } from 'express';

const router = Router();

router.get('/', async (req: Request, res: Response) => {
  const users = await db.user.findMany();
  res.json(users);
});

router.post('/', async (req: Request, res: Response) => {
  const user = await db.user.create({ data: req.body });
  res.status(201).json(user);
});

export default router;

NestJS

// users/users.controller.ts
import { Controller, Get, Post, Body } from '@nestjs/common';
import { UsersService } from './users.service';
import { CreateUserDto } from './users.dto';

@Controller('users')
export class UsersController {
  constructor(private readonly service: UsersService) {}

  @Get()
  findAll() {
    return this.service.findAll();
  }

  @Post()
  create(@Body() dto: CreateUserDto) {
    return this.service.create(dto);
  }
}

Hono

// routes/users.ts
import { Hono } from 'hono';

const app = new Hono();

app.get('/', async (c) => {
  const users = await db.user.findMany();
  return c.json(users);
});

app.post('/', async (c) => {
  const body = await c.req.json();
  const user = await db.user.create({ data: body });
  return c.json(user, 201);
});

export default app;

에러 처리: 범용 패턴

프레임워크에 관계없이 적용되는 표준 HTTP 상태 코드 기반의 에러 처리:

프로젝트에 커스텀 에러 클래스(AppError, HttpException, ApiError 등)가 있으면 자동으로 감지하여 사용합니다.

트리거 키워드

다음 키워드로 스킬이 자동 활성화됩니다:

• “API 만들어”
• “엔드포인트 추가”
• “route 생성”
• “CRUD API”
• “API endpoint”
• “새 API”

GitHub 저장소

스킬을 GitHub에 공개하여 다른 프로젝트에서도 참고할 수 있도록 했습니다.

다음 단계: 추가로 만들 스킬들

프로젝트에 더 필요한 스킬들을 식별했습니다. 그리고 그 다음엔 스킬이 스킬을 혼합하는 스킬이 예정되어 있습니다.

결론

Claude Code 스킬은 단순한 코드 생성 도구가 아닙니다. 프로젝트의 아키텍처 결정을 코드화하고, 팀의 개발 문화를 표준화하는 도구입니다.

프로젝트의 프레임워크와 기존 패턴을 자동 감지하여, Next.js 프로젝트든, Express 프로젝트든, NestJS 프로젝트든 같은 스킬 하나로 일관된 API 엔드포인트를 생성할 수 있습니다.

반복적으로 하는 작업이 있다면, 스킬로 만들어보세요. skill-wizard가 대화형으로 가이드해줍니다.

/skill-wizard 로 [스킬명] 스킬 만들어줘