터미널 하나면 된다

Part I

지침이 곧 실력이다

Claude Code는 코드 자동완성 도구가 아니다. 에이전트다. 파일을 읽고, 명령을 실행하고, git을 관리하고, 테스트를 돌리고, 배포까지 한다. 200K 토큰의 컨텍스트 윈도우 안에서 프로젝트 전체를 이해하고 동작한다. 핵심은 이 에이전트에게 어떤 지침을 주느냐다.

Principle 01

분리하라

프로젝트 규칙은 CLAUDE.md에. 반복 패턴은 Skills에. 자동화 훅은 Hooks에. 역할별로 분리해야 유지보수가 된다.

Principle 02

명시하라

"적절히 처리해줘"는 최악의 지침이다. 기술 스택, 폴더 구조, 코딩 규칙, 금지 사항을 구체적으로 적어야 한다.

Principle 03

제약하라

AI는 자유도가 높으면 발산한다. "하지 말 것"을 정의하면 결과물의 품질이 올라간다. 네거티브 프롬프트가 핵심이다.

CLAUDE.md — 프로젝트의 헌법

프로젝트 루트에 CLAUDE.md를 놓으면 Claude Code가 매 세션마다 자동으로 읽는다. 프로젝트의 모든 규칙을 한 곳에 정의하는 파일이다. 구조는 이렇다.

CLAUDE.md
# 프로젝트 개요
기술 스택: Python 3.12 + FastAPI / React 19 + TanStack Query v5
배포: Docker + GitHub Actions → AWS ECS
DB: PostgreSQL 16 + Redis 7

# 폴더 구조
backend/     ← FastAPI 서버
frontend/    ← React + Vite
infra/       ← Docker, CI/CD, IaC
docs/        ← PRD, 스펙, ADR

# 코딩 규칙
- Python: ruff 포맷, type hints 필수, docstring Google 스타일
- React: 함수 컴포넌트만, CSS Modules, barrel export 금지
- 커밋: Conventional Commits (feat/fix/chore)
- 테스트: 새 기능은 반드시 테스트 포함

# 금지 사항
- any 타입 사용 금지 (TypeScript)
- console.log 커밋 금지
- .env 파일 커밋 금지
- 기존 API 스키마를 사전 논의 없이 변경 금지

Skills — 반복 패턴의 모듈화

CLAUDE.md가 프로젝트 전체 규칙이라면, Skills는 특정 작업의 전문 매뉴얼이다. .claude/skills/ 폴더에 SKILL.md 파일을 만들면, Claude Code가 해당 작업 시 자동으로 참조한다.

.claude/ ├── settings.json ← 권한, 모델 설정 ├── commands/ ← 커스텀 슬래시 명령 │ ├── deploy.md ← /deploy 명령 정의 │ └── review.md ← /review 명령 정의 └── skills/ ├── api-design/SKILL.md ← REST API 설계 규칙 ├── testing/SKILL.md ← 테스트 작성 패턴 ├── docker/SKILL.md ← 컨테이너화 규칙 └── react-component/SKILL.md ← 컴포넌트 작성 규칙

SKILL.md 예시 — API 설계 스킬
# API 설계 규칙

엔드포인트 네이밍: 복수형 명사 (/users, /orders)
응답 형식: { "data": ..., "meta": { "total": n } }
에러 형식: { "error": { "code": "NOT_FOUND", "message": "..." } }
인증: Bearer JWT, Authorization 헤더
페이지네이션: cursor 기반 (offset 금지)
버전: URL prefix (/v1/, /v2/)

# 금지
- GET 요청에 body 사용 금지
- 200 OK로 에러 반환 금지
- 중첩 3단계 이상의 리소스 경로 금지

커스텀 명령 — 슬래시 한 번으로

.claude/commands/에 마크다운 파일을 만들면 슬래시 명령이 된다. 파일명이 곧 명령명이다. /deploy를 치면 배포가 시작되고, /review를 치면 코드 리뷰가 시작된다.

.claude/commands/deploy.md
현재 브랜치의 변경사항을 프로덕션에 배포한다.

git status로 커밋되지 않은 변경 확인
테스트 전체 실행 (pytest + vitest)
Docker 이미지 빌드 (docker compose build)
이미지 태그 지정 (git SHA 기반)
배포 전 체크리스트 확인 후 사용자에게 승인 요청

Claude Code에게 좋은 지침을 주는 것은
유능한 신입에게 온보딩 문서를 주는 것과 같다.

Part II

PRD에서 코드까지

Claude Code의 진가는 전 구간을 하나의 에디터에서 처리한다는 점이다. 기획 문서 작성 → 스펙 분해 → 코드 구현 → 테스트 → 배포. 터미널 하나로 전부 된다. 파이프라인은 이렇다.

01 PRD 기획 문서
요구사항 정의

02 Spec 태스크 분해
의존성 매핑

03 Code 멀티 언어
구현

04 Test 자동화 테스트
커버리지

05 Deploy Docker + CI/CD
프로덕션

01 — PRD 작성

Prompt docs/prd.md에 상품 주문 시스템 PRD를 작성해줘. 타겟 사용자: 소규모 이커머스 운영자 핵심 기능: 상품 CRUD, 장바구니, 주문/결제, 주문 상태 추적 비기능 요구사항: 동시 접속 1,000명, 응답 시간 200ms 이하 기술 스택: CLAUDE.md 참조 경쟁 서비스: Shopify, 카페24 1단계 MVP 범위와 2단계 확장 범위를 분리해서 작성.

02 — 스펙 트래킹

Prompt docs/prd.md를 읽고 구현 태스크를 분해해줘. 각 태스크에 포함할 것: - 우선순위 (P0/P1/P2) - 예상 복잡도 (S/M/L) - 의존성 (선행 태스크) - 담당 모듈 (backend/frontend/infra) docs/tasks.md에 테이블 형식으로 작성.

03 — 멀티 언어 구현

Claude Code는 언어를 가리지 않는다. Python, Java, TypeScript, Go, Rust — VS Code에서 열 수 있는 모든 언어를 다룬다. 같은 프로젝트 안에서 백엔드는 Python으로, 프론트엔드는 React로, 인프라는 Terraform으로 작업하는 것이 자연스럽다.

Python + FastAPI

백엔드 API

backend/에 주문 API를 만들어줘. - FastAPI + SQLAlchemy 2.0 - /v1/orders CRUD - Pydantic v2 스키마 - alembic 마이그레이션 - pytest + httpx 테스트 포함 api-design 스킬 참조.

FastAPI, Django, Flask, Celery, SQLAlchemy 모두 지원

Java + Spring Boot

마이크로서비스

payment-service/에 결제 서비스를 만들어줘. - Spring Boot 3.3 + JPA - /api/payments CRUD - Gradle 빌드 - H2(dev) → PostgreSQL(prod) 전환 구조 - JUnit5 + MockMvc 테스트 포함

Spring, Maven/Gradle, Hibernate, Kafka 모두 지원

React + TanStack

프론트엔드 SPA

frontend/에 주문 대시보드를 만들어줘. - React 19 + TypeScript - TanStack Router (파일 기반 라우팅) - TanStack Query (서버 상태 관리) - TanStack Table (주문 목록) - CSS Modules, 반응형 react-component 스킬 참조.

Next.js, Vite, Zustand, Tailwind 모두 지원

Go / Rust / etc.

시스템 레벨

gateway/에 API Gateway를 만들어줘. - Go 1.22 + chi router - JWT 검증 미들웨어 - Rate limiting (token bucket) - 헬스체크 + Prometheus 메트릭 - go test 테스트 포함

Go, Rust, C++, Ruby, PHP — 언어 제한 없음

04 — 테스트 자동화

Prompt backend/app/api/orders.py의 테스트를 작성해줘. - pytest + httpx AsyncClient - 정상 케이스 + 에러 케이스 모두 포함 - fixture로 테스트 DB 세팅 - 커버리지 80% 이상 목표 - 테스트 실행해서 통과하는지 확인까지.

마지막 줄이 핵심이다. "확인까지"라고 쓰면 Claude Code가 테스트를 직접 실행하고, 실패하면 코드를 수정하고, 다시 실행한다. 코드를 쓰는 것과 코드가 동작하는 것은 다르다. Claude Code는 동작까지 책임진다.

Part III

배포 파이프라인

코드가 완성되면 프로덕션에 올려야 한다. Docker 컨테이너화, CI/CD 파이프라인, 배포 자동화. 이 모든 것을 터미널에서 Claude Code에게 시킬 수 있다.

Docker — 컨테이너화

Prompt 이 프로젝트를 Docker로 컨테이너화해줘. - backend: 멀티스테이지 빌드 (builder → runtime) - frontend: nginx로 정적 파일 서빙 - docker-compose.yml: app + db(postgres) + redis + nginx - .dockerignore 포함 - 개발용(docker-compose.dev.yml)과 프로덕션용 분리 - docker 스킬 참조

CI/CD — 자동화 파이프라인

GitHub Actions

클라우드 네이티브

.github/workflows/에 CI/CD를 설정해줘. PR: lint → test → build main 머지: Docker build → ECR push → ECS deploy 시크릿은 GitHub Secrets 사용

claude-code-action으로 PR에서 @claude 멘션하면 AI 코드 리뷰까지 자동화 가능

Jenkins

온프레미스

Jenkinsfile을 작성해줘. Pipeline: Build → Test → Docker → Deploy 스테이지별 Slack 알림 환경 분기: dev/staging/prod 크레덴셜은 Jenkins Credentials

헤드리스 모드(-p 플래그)로 Jenkins 파이프라인 안에서 Claude Code 직접 호출 가능

Headless Mode — CI/CD 안의 AI

Claude Code는 -p 플래그로 헤드리스 모드를 지원한다. 사람의 입력 없이 스크립트에서 직접 호출할 수 있다. CI/CD 파이프라인 안에서 코드 리뷰, 리팩토링, 보안 점검을 자동으로 실행하는 것이 가능하다.

CI/CD Pipeline Script
# PR 자동 코드 리뷰
claude -p "이 PR의 변경사항을 리뷰해줘. 보안 이슈, 성능 문제, 코딩 규칙 위반을 확인."

# 마이그레이션 자동 생성
claude -p "models.py 변경사항을 감지하고 alembic 마이그레이션을 생성해줘."

# 배포 전 보안 점검
claude -p "프로젝트 전체를 스캔하고 OWASP Top 10 취약점을 확인해줘."

배포 전 체크리스트

환경 변수가 프로덕션 값으로 설정되었는가
테스트가 전부 통과하는가
Docker 이미지가 멀티스테이지 빌드인가 (이미지 크기 최소화)
.env, 시크릿, API 키가 이미지에 포함되지 않았는가
헬스체크 엔드포인트가 존재하는가
롤백 전략이 정의되어 있는가
모니터링/로깅이 설정되어 있는가

Part IV

프롬프트 레시피

상황별로 바로 쓸 수 있는 프롬프트 패턴이다. 핵심은 맥락 + 태스크 + 제약의 삼박자다. Claude Code는 프로젝트를 이미 이해하고 있으므로 "CLAUDE.md 참조"라는 한 마디가 수십 줄의 설명을 대신한다.

프로젝트 초기화

이 프로젝트를 세팅해줘. CLAUDE.md 읽고 기술 스택에 맞는 폴더 구조, 패키지 설치, 설정 파일, .gitignore, README를 생성.

기능 구현

[기능명]을 구현해줘. docs/prd.md의 [섹션] 스펙을 따르고 기존 코드 패턴을 유지. 테스트 포함, 실행해서 통과 확인.

디버깅

[에러 메시지]가 발생한다. 1. 원인을 분석해줘 2. 수정 방안을 제시해줘 3. 수정 후 테스트 통과 확인 기존 기능을 깨뜨리지 마.

리팩토링

[파일/모듈]을 리팩토링해줘. 외부 동작은 변경하지 마. 리팩토링 전후 테스트 결과가 동일해야 해. 변경 이유를 커밋 메시지에 포함.

코드 리뷰

현재 브랜치의 변경사항을 리뷰해줘. 보안 취약점, 성능 문제, 타입 안전성, 에러 처리 누락, 테스트 커버리지를 확인. 심각도별(P0/P1/P2)로 정리.

데이터베이스

[테이블/모델]을 추가해줘. 마이그레이션 파일 생성, 기존 데이터와의 호환성 확인, 마이그레이션 실행 후 롤백 스크립트 포함.

API 문서

현재 API 엔드포인트를 분석하고 OpenAPI 3.1 스펙 문서를 생성해줘. 요청/응답 예시 포함, docs/api.yaml에 저장.

성능 최적화

[파일/모듈]의 성능을 분석해줘. N+1 쿼리, 불필요한 렌더링, 메모리 누수, 캐싱 기회를 찾아서 구체적 개선안과 예상 효과를 제시.

Docker 배포

프로덕션 배포를 준비해줘. Docker 이미지 빌드 → 태그(git SHA) → docker compose up -d 헬스체크 통과 확인까지.

트러블슈팅

프로덕션에서 [증상]이 발생한다. 로그를 분석하고 원인을 추정해줘. 핫픽스 적용 → 테스트 → 배포까지. 기존 기능 영향도 확인.

좋은 프롬프트의 공통점은 하나다.
맥락, 태스크, 제약 — 이 세 가지가 명확하다.

Part V

컨텍스트 관리 전략

Claude Code의 컨텍스트 윈도우는 200K 토큰이다. 크지만 무한하지 않다. 대화가 길어지면 자동 압축(compaction)이 발동해서 이전 대화를 요약한다. 이 과정에서 중요한 맥락이 사라질 수 있다. 관리 전략이 필요하다.

Strategy 01

태스크 단위로 끊어라

하나의 세션에서 모든 것을 하려 하지 마라. 기능 하나 = 세션 하나. 세션이 끝나면 CLAUDE.md와 Skills가 다음 세션의 컨텍스트를 이어준다.

Strategy 02

지침에 기록하라

구두로 전달한 규칙은 사라진다. CLAUDE.md에 쓴 규칙은 영원하다. 세션 중 합의한 결정 사항은 즉시 지침 문서에 반영하라.

Strategy 03

압축 전에 저장하라

컨텍스트가 95%에 도달하면 자동 압축이 시작된다. 그 전에 /compact를 수동으로 실행하거나 새 세션을 시작하라. 핵심 결정은 파일에 남겨라.

컨텍스트 관리 치트시트
/compact        ← 수동 컨텍스트 압축
/clear          ← 대화 히스토리 초기화
/cost           ← 현재 세션 토큰 사용량 확인
/memory         ← 세션 간 기억 관리
/help           ← 전체 명령어 목록
/review         ← 커스텀 명령 (직접 정의)
/deploy         ← 커스텀 명령 (직접 정의)

도구는 바뀐다.
워크플로우는 남는다

Claude Code가 아니더라도 이 패턴은 유효하다. 지침을 설계하고, 파이프라인을 구성하고, 프롬프트를 구조화하는 능력. 그것이 에이전틱 시대의 개발자 역량이다.