Claude Code
완전 정복

무엇이 다른가요?

둘의 차이는 "더 긴 프롬프트"나 "더 어려운 언어"가 아닙니다. 목표 자체가 다릅니다.

CLAUDE.md — AI의 장기 기억

Claude Code는 세션이 바뀌면 이전 대화를 기억하지 못합니다. CLAUDE.md는 이 문제를 해결하는 파일입니다. 프로젝트 루트에 두면 Claude가 매 세션마다 자동으로 읽어 컨텍스트를 복원합니다.

단순한 README가 아닙니다. Claude에게 "이 프로젝트에서 어떻게 일해야 하는지"를 알려주는 작업 지침서입니다.

CLAUDE.md 기본 구조

# 프로젝트 개요
출석 관리 웹앱. React + TypeScript + Vite.
Supabase를 DB로 사용. Vercel에 배포.

# 코딩 규칙
- 모든 컴포넌트는 TypeScript 타입을 명시할 것
- CSS는 Tailwind만 사용 (styled-components 금지)
- 함수명은 camelCase, 컴포넌트명은 PascalCase
- 커밋 메시지는 한국어로 작성

# 폴더 구조
src/components/  — 재사용 가능한 UI 컴포넌트
src/pages/       — 라우트별 페이지
src/hooks/       — 커스텀 훅
src/lib/         — Supabase 클라이언트, 유틸

# 현재 작업 중
출석 통계 페이지 구현 중. /stats 라우트.
아직 모바일 레이아웃 미완성.

# 주의사항
- Supabase API 키는 .env.local에만 있음. 절대 커밋 금지.
- StudentList 컴포넌트는 리팩토링 예정이므로 건드리지 말 것

CLAUDE.md 작성 팁

• 처음에는 짧게 시작하세요. 나중에 Claude에게 "이 내용 CLAUDE.md에 추가해줘"라고 하면 됩니다.
• "하지 말 것" 목록이 "해야 할 것"보다 더 중요합니다. 실수 패턴을 기록하세요.
• 기술 스택뿐만 아니라 비즈니스 맥락도 적으세요. "이 앱은 학원 원장님이 쓴다"는 정보가 UI 결정을 바꿉니다.
• 세션마다 claude "CLAUDE.md 읽고 현재 상태 파악해줘"로 시작하면 바로 이어서 작업할 수 있습니다.

Plugin — Claude Code에 도구 붙이기

Claude Code의 플러그인은 Claude가 사용할 수 있는 도구(Tool)를 추가하는 방법입니다. 기본 Claude Code는 파일 읽기·쓰기, 터미널 실행이 가능합니다. 플러그인을 통해 여기에 새로운 능력을 붙일 수 있습니다.

플러그인 설정 방법

Claude Code 플러그인은 .claude/settings.json 또는 CLAUDE.md의 tools 섹션으로 관리합니다. 가장 간단한 방법은 Claude에게 직접 설정을 요청하는 것입니다.

플러그인 활용 흐름

Skill — 반복 작업을 슬래시 명령으로

스킬(Skill)은 자주 쓰는 복잡한 프롬프트나 작업 흐름을 슬래시 명령으로 만들어두는 기능입니다. /commit, /review, /deploy처럼 자신만의 명령어를 정의할 수 있습니다.

스킬이 해결하는 문제

같은 작업을 할 때마다 긴 프롬프트를 타이핑하고 있다면 스킬이 필요합니다.

스킬 파일 만들기

스킬은 .claude/skills/ 폴더 안에 마크다운 파일로 만듭니다. 파일명이 곧 슬래시 명령어가 됩니다.

---
description: 변경사항을 분석하고 커밋 메시지를 작성한 뒤 커밋합니다
---

## 작업 순서

1. `git diff --staged`로 스테이징된 변경사항을 확인하세요
2. 변경의 목적을 파악하세요 (기능 추가 / 버그 수정 / 리팩토링 / 문서)
3. 한국어로 커밋 메시지를 작성하세요: `유형: 간결한 설명`
4. `git commit -m "메시지"`를 실행하세요
5. 커밋 성공 여부를 확인하세요

## 커밋 유형
- feat: 새로운 기능
- fix: 버그 수정
- refactor: 리팩토링
- docs: 문서 수정
- style: 스타일만 변경

스킬 호출 방법

# Claude Code 세션 안에서 슬래시로 호출
> /commit

# 인자 전달도 가능
> /review --focus security

# 스킬 목록 확인
> /help

MCP — Claude를 외부 세계와 연결

MCP(Model Context Protocol)는 Claude가 외부 서비스와 실시간으로 통신하게 해주는 표준 프로토콜입니다. 파일 시스템, 데이터베이스, GitHub, Figma, Slack 같은 도구를 Claude Code에 직접 붙일 수 있습니다.

일반 플러그인이 Claude의 동작을 확장한다면, MCP는 외부 시스템과의 양방향 통신 채널을 만들어줍니다.

MCP 서버 설정 방법

MCP 서버는 claude mcp add 명령으로 등록합니다. 이후 Claude Code가 자동으로 인식합니다.

# GitHub MCP 서버 추가
claude mcp add github \
  --env GITHUB_TOKEN=ghp_your_token_here

# Supabase MCP 서버 추가
claude mcp add @supabase/mcp-server-supabase \
  --env SUPABASE_URL=https://xxx.supabase.co \
  --env SUPABASE_KEY=your_anon_key

# 등록된 MCP 목록 확인
claude mcp list

MCP를 활용한 실제 작업 흐름

Sub-agent — 작업을 나눠서 동시에

서브에이전트는 메인 Claude가 별도의 Claude 인스턴스를 생성해 특정 작업을 위임하는 기능입니다. 큰 작업을 잘게 나눠 여러 에이전트가 동시에 처리하면 속도와 품질이 모두 올라갑니다.

서브에이전트가 필요한 상황

서브에이전트 실행 흐름

서브에이전트 활용 프롬프트

# 메인 에이전트가 서브에이전트를 생성
Agent({
  description: "StudentList 컴포넌트 리팩토링",
  prompt: "src/components/StudentList.tsx를 TypeScript 타입 완성 및 훅 분리"
})

Agent({
  description: "AttendanceTable 컴포넌트 리팩토링",
  prompt: "src/components/AttendanceTable.tsx를 TypeScript 타입 완성 및 훅 분리"
})

# 두 에이전트가 동시에 실행됨

Agent Team — 에이전트가 팀을 이루다

에이전트팀은 여러 전문화된 에이전트가 역할 분담을 하며 협력하는 구조입니다. 단순 병렬(서브에이전트)과 달리, 에이전트팀은 각 에이전트가 서로의 결과를 받아 연속적으로 작업합니다. 복잡한 소프트웨어 개발 파이프라인을 자동화하는 가장 강력한 방법입니다.

역할 분담 예시 — 기능 개발 파이프라인

에이전트팀 운영 방식

에이전트팀 실전 프롬프트

어디까지 자동화할 수 있나

• 이슈 생성 → 코드 구현 → 테스트 작성 → PR 생성까지 원클릭 자동화
• 버그 리포트 수신 → 원인 분석 → 수정 코드 작성 → 검증까지 무인 처리
• 정기 코드 품질 점검 → 개선 PR 자동 생성 (크론 스케줄로 실행)
• 여러 서비스에 동시 배포 (스테이징 → QA → 프로덕션 순차 배포)

AI로 단위 테스트 작성하기

Advanced의 핵심은 "앱이 동작한다"에서 "앱이 올바르게 동작한다"로 이동하는 것입니다. AI는 테스트 코드 작성을 매우 잘 합니다. 기능을 만든 직후 테스트를 바로 요청하는 습관을 들이세요.

테스트 작성 요청 흐름

AI와 함께 아키텍처 개선하기

코드가 동작하는 것과 코드가 좋은 것은 다릅니다. AI는 코드 리팩토링과 아키텍처 개선에 탁월합니다. "동작하는 코드"를 "유지보수 가능한 코드"로 만드는 방법을 배워봅니다.

Claude Code 마스터 로드맵

6가지 기능을 순서대로 익히면 개발 방식이 단계적으로 달라집니다.