Claude Code CLI로 프로젝트 자동화하기 - 실전 워크플로우

Claude Code CLI로 프로젝트 자동화하기 - 실전 워크플로우

2026년 4월 기준 | AI 개발 가이드

요약: Claude Code는 Anthropic이 만든 터미널 기반 AI 코딩 에이전트입니다. GUI 에디터 없이 터미널에서 자연어로 코드를 작성하고, 리팩토링하고, 테스트를 돌리는 도구인데요. 3개월간 실제 프로젝트에서 사용하면서 느낀 점을 정리했습니다. 설치부터 CLAUDE.md 활용, 실전 워크플로우까지 CLI 기반 개발의 모든 것을 다룹니다.

목차

• Claude Code란 무엇인가
• 설치 및 초기 설정
• 실전 워크플로우 4가지
• CLAUDE.md로 프로젝트 컨텍스트 관리하기
• Cursor/Copilot과 뭐가 다른가
• 실전 팁 모음
• 주의할 점
• 마무리

1. Claude Code란 무엇인가

Claude Code는 Anthropic에서 만든 터미널 기반 AI 코딩 에이전트입니다. Cursor나 Copilot처럼 에디터 안에서 동작하는 게 아니라, 터미널에서 직접 실행합니다. 쉽게 말해서 "터미널에 앉아있는 시니어 개발자"라고 생각하면 됩니다.

처음 들으면 "왜 굳이 터미널에서?"라는 의문이 들 수 있습니다. 저도 처음엔 그랬습니다. Cursor 쓰면 되지, 왜 CLI를 쓰나? 그런데 실제로 써보면 생각이 바뀝니다. 터미널에서 동작한다는 건 곧 파일 시스템, git, 패키지 매니저, 빌드 도구에 직접 접근할 수 있다는 뜻이거든요.

일반적인 GUI 기반 코딩 도구들은 "코드 편집"에 초점이 맞춰져 있습니다. 파일을 열고, 수정하고, 저장하는 흐름이죠. 반면 Claude Code는 편집만 하는 게 아니라 테스트도 돌리고, 빌드도 하고, git 커밋까지 합니다. 개발의 전체 사이클을 터미널 안에서 처리할 수 있는 겁니다.

현재 Claude Code는 Claude Opus 4와 Sonnet 4 모델을 기반으로 동작하며, 100만 토큰의 컨텍스트 윈도우를 지원합니다. 대규모 코드베이스도 한 번에 파악할 수 있다는 얘기입니다.

2. 설치 및 초기 설정

설치는 놀라울 정도로 간단합니다. Node.js가 깔려있다면 한 줄이면 끝납니다.

# 1. Claude Code 글로벌 설치
npm install -g @anthropic-ai/claude-code

# 2. 프로젝트 폴더로 이동
cd ~/my-project

# 3. 실행 (처음 실행하면 브라우저에서 인증 진행)
claude

# 4. 인증 완료 후 바로 대화 시작
"이 프로젝트 구조를 분석하고 README에 정리해줘"

인증 방식은 두 가지입니다. Anthropic Console에서 API 키를 발급받아 환경 변수로 설정하거나, Max 구독이 있으면 브라우저 OAuth로 로그인할 수 있습니다. 개인적으로는 Max 구독을 추천합니다. API 종량제는 리팩토링 한 번에 $3~5가 나가는 경우가 있어서, 많이 쓰는 분은 정액제가 유리합니다.

설치 후 첫 실행하면 현재 디렉토리의 파일 구조를 자동으로 파악합니다. 별도의 인덱싱 과정이 필요 없어서, Cursor처럼 "인덱싱 중..." 하고 기다릴 필요가 없습니다.

3. 실전 워크플로우 4가지

설치했으면 이제 써봐야겠죠. 제가 실제 프로젝트에서 가장 많이 쓰는 워크플로우 4가지를 공유합니다.

워크플로우 1: 프로젝트 초기 세팅

새 프로젝트를 시작할 때 보일러플레이트 만드는 게 제일 귀찮습니다. Claude Code에게 시키면 폴더 구조부터 설정 파일까지 한 번에 만들어줍니다.

# 프로젝트 세팅 예시
mkdir my-api && cd my-api
claude

# Claude Code에게 자연어로 지시
> Express + TypeScript + Prisma로 REST API 프로젝트를 세팅해줘.
  ESLint, Prettier, Jest 설정도 포함하고,
  Docker Compose로 PostgreSQL 개발 환경도 만들어줘.
  폴더 구조는 src/routes, src/services, src/middleware로 나눠줘.

# Claude Code가 하는 일:
# - package.json 생성 및 의존성 설치 (npm install 실행)
# - tsconfig.json, .eslintrc, .prettierrc 설정
# - docker-compose.yml 생성
# - 폴더 구조 생성 + 기본 파일들 작성
# - prisma/schema.prisma 초기 설정
# - jest.config.ts 설정

Cursor에서 같은 작업을 하려면 채팅창에서 한 파일씩 생성하거나, Composer에서 지시를 내려야 합니다. Claude Code는 터미널에서 직접 mkdir, npm init, npm install까지 실행하니까 정말 한 번의 대화로 끝납니다.

워크플로우 2: 코드 리팩토링

제가 가장 자주 쓰는 패턴입니다. 레거시 코드를 개선할 때 Claude Code가 빛을 발합니다.

예를 들어 "src/services 폴더의 모든 서비스에서 콜백 패턴을 async/await로 바꿔줘" 같은 명령을 내리면, 관련 파일을 전부 찾아서 한꺼번에 수정합니다. 수정 전에 변경 계획을 먼저 보여주고, 승인하면 진행하는 식이라 실수할 일도 적습니다.

특히 좋은 점은 리팩토링 후에 바로 npm test를 실행해서 테스트가 깨지는지 확인해준다는 겁니다. 테스트가 실패하면 원인을 분석하고 수정까지 해줍니다. 이게 GUI 도구와의 결정적인 차이입니다.

워크플로우 3: 테스트 작성

솔직히 테스트 코드 작성이 귀찮아서 미루는 분 많죠. 저도 그랬는데, Claude Code를 쓰고 나서는 테스트 커버리지가 확 올라갔습니다.

# 테스트 작성 + 실행까지 한 번에
> src/services/userService.ts의 모든 public 메서드에 대해
  단위 테스트를 작성해줘.
  edge case도 포함하고, mock은 jest.mock으로 처리해줘.

# Claude Code 동작:
# 1. userService.ts를 읽고 의존성 분석
# 2. __tests__/userService.test.ts 파일 생성
# 3. DB, 외부 API 등 의존성을 jest.mock으로 처리
# 4. 정상 케이스 + 에러 케이스 + edge case 테스트 작성
# 5. npx jest userService.test.ts 실행
# 6. 실패하는 테스트가 있으면 원인 분석 후 수정

PASS src/__tests__/userService.test.ts
  UserService
    ✓ getUserById - 존재하는 유저 조회 (3ms)
    ✓ getUserById - 존재하지 않는 유저 조회 시 에러 (1ms)
    ✓ createUser - 정상 생성 (2ms)
    ✓ createUser - 중복 이메일 시 에러 (1ms)
    ✓ updateUser - 부분 업데이트 (2ms)
    ✓ deleteUser - soft delete 확인 (1ms)

Tests: 6 passed, 6 total

테스트를 작성하고, 실행하고, 결과를 확인하고, 실패하면 고치는 것까지 자동입니다. 사람이 할 일은 처음에 지시를 내리고, 마지막에 결과를 리뷰하는 것뿐입니다.

워크플로우 4: 디버깅

에러가 터졌을 때 Claude Code에게 에러 메시지를 그대로 붙여넣으면 됩니다. 로그를 분석하고, 관련 코드를 찾아서, 원인을 진단하고, 수정안을 제시합니다. 스택 오버플로우를 뒤질 필요가 없어집니다.

"npm run build에서 이런 에러가 나는데 고쳐줘"라고 하면 빌드 에러를 잡고, 다시 빌드까지 돌려서 확인합니다. 이 사이클이 터미널 안에서 자연스럽게 돌아가는 게 Claude Code의 강점입니다.

4. CLAUDE.md로 프로젝트 컨텍스트 관리하기

Claude Code를 제대로 활용하려면 CLAUDE.md를 반드시 알아야 합니다. 이게 숨겨진 핵심 기능입니다.

CLAUDE.md는 프로젝트 루트에 두는 마크다운 파일인데, Claude Code가 실행될 때 자동으로 읽습니다. 여기에 프로젝트의 컨텍스트, 코딩 컨벤션, 주의사항 등을 적어두면 Claude Code가 그에 맞춰서 동작합니다.

# CLAUDE.md 예시

## 프로젝트 개요
이 프로젝트는 Express + TypeScript 기반의 이커머스 API입니다.
PostgreSQL을 사용하며, Prisma ORM으로 DB에 접근합니다.

## 코딩 컨벤션
- 변수명은 camelCase, 타입/인터페이스는 PascalCase
- 함수는 반드시 JSDoc 주석을 달 것
- 에러 처리는 커스텀 AppError 클래스를 사용할 것
- import 순서: 외부 패키지 → 내부 모듈 → 타입

## 테스트 규칙
- 단위 테스트는 Jest, E2E 테스트는 Supertest 사용
- 테스트 파일은 __tests__ 폴더에 위치
- 최소 커버리지: 80%

## 주의사항
- src/legacy/ 폴더는 건드리지 말 것 (마이그레이션 예정)
- 환경변수는 반드시 .env.example에 목록 추가
- main 브랜치에 직접 커밋 금지, PR 필수

이렇게 적어두면 Claude Code가 코드를 생성할 때 컨벤션을 따르고, 건드리면 안 되는 폴더는 피하고, 테스트 규칙에 맞춰서 테스트를 작성합니다. CLAUDE.md 없이 쓰는 것과 있을 때를 비교하면 결과물 품질 차이가 상당합니다.

추가로 ~/.claude/CLAUDE.md 경로에 글로벌 설정을 둘 수도 있습니다. 모든 프로젝트에 공통으로 적용할 규칙(예: "항상 한국어로 응답해줘", "커밋 메시지는 영어로")을 여기에 적으면 됩니다.

5. Cursor/Copilot과 뭐가 다른가

가장 많이 받는 질문입니다. "Cursor 있는데 왜 CLI를 쓰냐?" 솔직한 답을 드리면, 둘 다 쓰고 있습니다. 하지만 작업 성격에 따라 확실히 유리한 도구가 다릅니다.

비교 항목	Claude Code (CLI)	Cursor	GitHub Copilot
동작 환경	터미널 (에디터 무관)	전용 IDE (VS Code 포크)	VS Code/JetBrains 확장
시스템 명령 실행	자유자재 (git, npm, docker 등)	제한적 (터미널 통합)	에이전트 모드에서 가능
멀티파일 편집	강력 (파일 수 제한 없음)	강력 (Composer)	보통 (에이전트 모드)
코드 자동완성	없음 (대화형만)	우수 (Tab 자동완성)	우수 (Tab 자동완성)
대규모 리팩토링	최강 (테스트까지 자동 실행)	강력 (시각적 diff 제공)	보통
CI/CD 통합	네이티브 (GitHub Actions 등)	제한적	GitHub 생태계 통합
러닝 커브	중~상 (CLI 친숙도 필요)	중 (단축키 학습)	하 (설치 후 바로 사용)
가격 (개인)	$20/월 (Max) 또는 API 종량제	$20/월 (Pro)	$10/월 (Pro)

핵심 차이를 한 마디로 정리하면, Cursor와 Copilot은 "코드를 작성하는 것"에 최적화되어 있고, Claude Code는 "개발 작업을 수행하는 것"에 최적화되어 있습니다.

코드 한 줄 한 줄 쓰면서 실시간으로 자동완성을 받고 싶으면 Cursor가 낫습니다. 하지만 "이 프로젝트에 인증 시스템을 추가해줘"처럼 여러 파일에 걸친 작업을 통째로 맡기고 싶으면 Claude Code가 압도적입니다. 테스트 실행, 빌드 확인, git 커밋까지 한 사이클을 자동으로 돌려주니까요.

개인적으로는 이렇게 씁니다: 일상적인 코딩은 Cursor에서 하고, 리팩토링이나 새 기능 통째로 만들 때는 Claude Code를 켭니다. 둘이 충돌하지 않아서 병행 사용이 편합니다.

6. 실전 팁 모음

팁 1: 슬래시 명령어를 활용하세요

Claude Code에는 유용한 슬래시 명령어들이 있습니다. /compact는 대화 내역을 요약해서 컨텍스트를 절약하고, /clear는 대화를 초기화합니다. 토큰을 아끼면서 긴 작업을 이어갈 수 있습니다.

팁 2: 한 번에 하나씩, 구체적으로 지시하세요

"프로젝트 전체를 리팩토링해줘"보다는 "src/services/auth.ts에서 bcrypt를 argon2로 교체하고, 관련 테스트도 수정해줘"처럼 구체적으로 지시하는 게 결과가 좋습니다. 범위가 명확할수록 정확도가 올라갑니다.

팁 3: --headless 모드로 자동화 파이프라인에 넣으세요

Claude Code는 claude --headless -p "프롬프트" 형식으로 비대화형 실행이 가능합니다. 이걸 CI/CD 파이프라인에 넣으면 PR이 올라올 때 자동으로 코드 리뷰를 하거나, 커밋마다 테스트를 보강하는 자동화를 만들 수 있습니다.

팁 4: git 상태를 활용하세요

Claude Code는 git 상태를 인식합니다. 수정된 파일이 있으면 그걸 기반으로 작업하고, 새로운 변경사항은 별도의 커밋으로 분리합니다. 작업 전에 깨끗한 git 상태를 유지하면 Claude Code의 변경사항을 쉽게 리뷰하고 되돌릴 수 있습니다.

7. 주의할 점

주의 1: 토큰 비용 관리
API 종량제를 사용하는 경우, 큰 코드베이스에서 작업하면 토큰 소모가 상당합니다. 한 세션에서 대규모 리팩토링을 하면 $5 이상 나오는 경우도 있습니다. Max 구독($20/월)으로 전환하거나, 작업 범위를 적절히 나눠서 진행하세요.

주의 2: 파일 시스템 접근 권한
Claude Code는 터미널 명령어를 실행할 수 있기 때문에, 위험한 명령(rm -rf, 프로덕션 DB 접근 등)이 실행될 가능성이 있습니다. 기본적으로 위험 명령은 사용자 승인을 받도록 되어 있지만, 항상 변경사항을 확인하는 습관을 들이세요. CLAUDE.md에 "프로덕션 환경 관련 명령은 실행하지 말 것"이라고 명시하는 것도 좋습니다.

주의 3: 실시간 자동완성은 없습니다
Cursor나 Copilot처럼 타이핑하면서 실시간으로 코드를 추천해주는 기능은 없습니다. Claude Code는 대화형 에이전트이기 때문에, 요청을 보내고 결과를 받는 방식입니다. 일상적인 코딩에서 자동완성이 필요하다면 다른 도구와 병행해서 쓰는 게 맞습니다.

8. 마무리

Claude Code를 3개월 정도 쓰면서 느낀 점을 한마디로 정리하면, "개발자의 작업 단위를 바꿔놓는 도구"라는 것입니다.

이전에는 "이 함수를 수정해야지"가 작업 단위였다면, 이제는 "이 기능을 추가해야지"가 작업 단위가 됩니다. 파일 하나하나 열어서 수정하는 게 아니라, 의도를 전달하면 여러 파일에 걸친 변경이 한 번에 이루어집니다.

물론 만능은 아닙니다. 복잡한 비즈니스 로직은 여전히 사람이 설계해야 하고, Claude Code가 만든 코드도 반드시 리뷰해야 합니다. 하지만 보일러플레이트 작성, 테스트 코드 생성, 리팩토링 같은 반복적이고 시간 먹는 작업에서는 확실히 생산성이 올라갑니다.

CLI에 거부감이 없는 개발자라면 한번 써보시길 강력 추천합니다. 처음에 CLAUDE.md 설정만 잘 해두면, 프로젝트를 이해하는 AI 페어 프로그래머가 터미널에 상주하게 됩니다. Cursor나 Copilot과 경쟁 관계가 아니라 보완 관계이니, 기존 도구와 함께 써보세요.

이 글은 2026년 4월 기준으로 작성되었습니다. AI 도구는 업데이트가 빈번하므로, 정확한 가격이나 기능은 Claude Code 공식 문서에서 확인해주세요.