Claude Code 완전 입문: 터미널 AI 에이전트로 코드베이스 자동화하기

"Copilot이나 Cursor와 뭐가 다른가?" — Claude Code를 처음 접하는 개발자에게 가장 많이 받는 질문이다. 차이는 단 한 가지 지점에서 갈린다. 기존 도구들이 커서 앞에 코드 한 줄을 제안하는 _자동완성_이라면, Claude Code는 "JWT 인증을 추가해줘"라는 자연어 한 마디로 여러 파일에 걸친 기능 구현을 직접 수행하는 _자율 에이전트_다. 파일을 읽고, 계획을 세우고, 코드를 수정하고, 테스트를 돌리고, 실패하면 원인을 분석해 다시 수정한다 — 이 모든 루프를 사람 개입 없이 반복한다.

Claude Code는 "AI가 코드를 대신 짜준다"는 도구가 아니라, 개발자가 목표를 설정하고 AI가 실행을 맡는 협업 시스템이다. 이 관점의 전환을 이해하고 나면, CLAUDE.md로 규칙을 사전에 가르치고 Plan Mode로 실행 전 계획을 검토하는 패턴이 왜 이 도구의 핵심인지 납득이 된다.

백엔드 개발 경험이 있는 분이라면 핵심 개념부터 순서대로 읽기를 권한다. 이미 Copilot이나 Cursor를 쓰고 있다면 장단점 분석부터 시작해도 된다. 도입 여부를 검토 중인 분은 마치며의 3단계 실행 가이드가 가장 빠른 진입점이다.

핵심 개념

Claude Code란 무엇인가

Claude Code는 Anthropic이 개발한 에이전트 기반 코딩 CLI(Command Line Interface) 도구다. 2025년 2월 베타 출시, 2025년 5월 정식(GA) 출시되었으며, 핵심 철학은 명확하다: 터미널에서 자연어로 목표를 주면, 코드베이스를 이해하고 계획을 세우고 실행까지 스스로 한다.

에이전트(Agent)란? 단순히 질문에 답하는 것을 넘어, 목표를 달성하기 위해 여러 도구를 순차적으로 사용하며 스스로 결정을 내리는 AI 시스템을 말한다. Claude Code는 파일 읽기 → 수정 계획 → 코드 작성 → 테스트 실행 → 오류 수정이라는 루프를 반복한다.

에이전트 루프(Agentic Loop)

Claude Code가 일반적인 코드 자동완성 도구와 가장 크게 다른 점이 바로 이 루프다. 사용자가 목표를 입력하면 다음 사이클이 자동으로 돌아간다.

css

[목표 입력]
    ↓
[코드베이스 분석 — 관련 파일 탐색 및 이해]
    ↓
[계획 수립 — 어떤 파일을 어떻게 수정할지 결정]
    ↓
[실행 — 코드 작성, 파일 수정]
    ↓
[테스트 실행 — 결과 검증]
    ↓
[실패 시 오류 분석 → 수정 반복]
    ↓
[완료 보고]

이 루프를 가능하게 하는 기술적 기반이 Claude Sonnet 4.6 / Opus 4.6 모델 계열이 지원하는 대용량 컨텍스트 윈도우다. 수만 줄 규모의 모노레포도 전체를 한 번에 파악할 수 있다. 사용 모델과 플랜에 따라 정확한 토큰 한도가 다르므로, 최신 스펙은 공식 문서에서 확인하는 것이 가장 정확하다.

CLAUDE.md — 프로젝트 헌법

Claude Code는 대화를 시작할 때마다 프로젝트 루트의 CLAUDE.md 파일을 읽는다. 이 파일은 AI에게 프로젝트 규칙을 가르치는 "헌법" 역할을 한다. 한 번만 잘 작성해두면 이후 모든 세션에서 일관된 품질의 결과를 얻을 수 있다.

yaml

# 프로젝트 규칙
 
- 패키지 매니저: pnpm만 사용 (npm, yarn 금지)
- 코드 스타일: TypeScript strict mode
- 테스트: 반드시 실제 DB 사용 (mock 금지)
- 커밋 메시지: 한국어 허용, imperative mood
 
# 빌드 & 테스트 명령어
- Build: `pnpm build`
- Test: `pnpm test`
 
# 아키텍처 규칙
- 비즈니스 로직은 Service에, Controller는 thin하게 유지

"테스트: 반드시 실제 DB 사용 (mock 금지)"를 명시하는 이유: Claude Code를 포함한 AI 도구는 테스트를 작성할 때 기본적으로 mock을 선택하는 경향이 있다. 그러나 mock 테스트는 실제 DB 스키마 변경, 마이그레이션 오류, 트랜잭션 동작 차이를 잡아내지 못한다. 이 규칙 한 줄이 통합 레벨의 신뢰도를 확보한다.

팁: CLAUDE.md는 팀 전체가 공유하는 파일이다. "pnpm만 사용", "mock DB 금지"처럼 과거에 팀원이 실수했거나 AI가 잘못 선택했던 패턴을 명시적으로 금지하면, 이후 세션의 결과 품질이 눈에 띄게 향상된다.

Plan Mode — 초보자에게 필수인 안전망

Plan Mode는 Claude Code가 코드를 실제로 수정하기 전에 계획만 먼저 보여주고 승인을 기다리는 모드다. 변경 전에 "이 파일들을 이런 방식으로 바꾸겠다"는 계획서를 먼저 받아볼 수 있어, 예상치 못한 수정을 방지하는 데 효과적이다. 진입 방법은 대화 중 Shift+Tab을 누르거나, 실행 시 --plan 플래그를 사용하면 된다.

권한 관리 — 보수적인 설계

파일 수정, 셸 명령 실행 등 시스템에 영향을 주는 작업은 기본적으로 사용자의 명시적 허가를 요청한다. 이는 의도치 않은 파괴적 변경을 막기 위한 설계다. 특정 작업을 항상 허용하거나 거부하도록 설정을 조정할 수 있다.

실전 적용

예시 1: 설치부터 첫 번째 기능 구현까지

공식 설치 방법은 npm을 통한 전역 패키지 설치다. Node.js 18 이상이 필요하다.

bash

# 공식 설치
npm install -g @anthropic-ai/claude-code
 
# 프로젝트 디렉토리에서 실행
cd my-project
claude
 
# 자연어로 기능 구현 요청
claude "로그인 API에 JWT 인증을 추가해줘. \
  액세스 토큰 만료는 15분, 리프레시 토큰은 7일로 설정해줘"

Claude Code는 이 명령 하나로 다음 작업을 자동 수행한다.

단계	수행 내용
1. 분석	기존 인증 관련 파일 탐색 및 구조 파악
2. 계획	수정이 필요한 파일 목록과 변경 방식 결정
3. 실행	JWT 라이브러리 설치, 미들웨어 작성, 라우터 수정
4. 검증	기존 테스트 실행 후 실패 시 자동 수정

예시 2: Plan Mode로 안전하게 대규모 리팩터링

# --plan 플래그로 Plan Mode 진입 (또는 대화 중 Shift+Tab)
claude --plan "전체 코드베이스에서 콜백 패턴을 async/await으로 변환해줘"

Plan Mode에서 Claude Code는 실제 수정 전에 계획을 먼저 출력한다. 아래는 응답 예시다(실제 출력 형식과 다를 수 있음).

bash

수정 계획:
1. src/utils/fileHelper.js — readFile 콜백 → async/await 변환 (3곳)
2. src/api/userRouter.js — 미들웨어 체인 재구성 (5곳)
3. src/services/emailService.js — 전체 재작성 필요 (12곳)
총 20개 파일, 약 87곳 수정 예정
실행할까요? [y/n]

계획을 먼저 검토하고 승인하면 실제 수정이 시작된다. 예상보다 수정 범위가 크거나 의도와 다른 방향이면 이 단계에서 방향을 바꿀 수 있다.

예시 3: 자율 테스트 루프

# 테스트를 통과할 때까지 자동으로 수정 반복
claude "현재 실패하는 테스트를 모두 통과시켜줘. \
  단, 테스트 코드 자체는 수정하지 말고 구현 코드만 수정해"

이 패턴은 특히 강력하다. Claude Code는 pnpm test 실행 → 실패 로그 분석 → 원인 코드 수정 → 재실행의 루프를 사람 개입 없이 반복한다. CLAUDE.md에 테스트 명령어를 명시해두면 어떤 프로젝트에서도 동일하게 동작한다.

예시 4: Python 프로젝트에서 보안 취약점 점검

Claude Code는 TypeScript/Node.js 전용이 아니다. Python, Go 등 어떤 언어 기반 프로젝트에서도 동일하게 동작한다.

# Python FastAPI 프로젝트에서 보안 취약점 점검
claude "@app/api/routes.py @app/models/user.py \
  이 엔드포인트들에서 SQL injection 취약점이나 \
  인증 우회 가능한 부분을 찾아서 수정해줘"

python

# 수정 전 — 취약한 문자열 포맷 쿼리
@app.get("/users/{user_id}")
async def get_user(user_id: str):
    query = f"SELECT * FROM users WHERE id = {user_id}"  # SQL injection 위험
    result = await db.execute(query)
    ...
 
# Claude Code가 파라미터 바인딩 방식으로 자동 교체한 결과
@app.get("/users/{user_id}")
async def get_user(user_id: int, db: AsyncSession = Depends(get_db)):
    result = await db.execute(select(User).where(User.id == user_id))
    user = result.scalar_one_or_none()
    ...

예시 5: 특정 파일을 컨텍스트로 고정

# @멘션으로 특정 파일을 명시적으로 컨텍스트에 포함
claude "@src/types/user.ts @src/api/userRouter.ts \
  이 타입 정의를 기반으로 유저 CRUD API를 완성해줘"

대형 코드베이스에서 관련 없는 파일까지 분석하는 낭비를 줄이고, 정확도를 높이는 데 효과적인 패턴이다.

장단점 분석

장점

Claude Code가 가장 빛나는 구간은 CLAUDE.md가 잘 설정된 환경에서의 중간 난이도 작업이다. 반복적인 보일러플레이트 작성, 일관된 패턴 적용, 테스트 수정 루프처럼 목표가 명확하고 검증 기준이 있는 작업에서 체감 생산성 향상이 가장 크다(사용자 보고 기준).

항목	내용
대형 컨텍스트 이해	복잡한 모노레포나 레거시 코드베이스를 전체적으로 파악 가능
자율 실행	테스트 → 오류 수정 → 재실행 루프를 사람 개입 없이 반복
터미널 네이티브	vim, tmux, zsh 등 기존 워크플로와 자연스럽게 통합
다언어 지원	TypeScript, Python, Go, Rust 등 언어 제약 없이 동작
확장성	MCP, Skills, Hooks로 팀과 프로젝트에 맞게 커스터마이징 가능

단점 및 주의사항

항목	내용	대응 방안
가격	전문 용도의 실질적 진입점은 Max 플랜($100/월)	팀 계정으로 비용 분산, 도입 전 무료 체험으로 효과 측정
사용량 제한	플랜에 따라 rate limit 존재 (최신 기준은 공식 요금제 페이지 확인)	중요 작업을 집중 처리하거나 상위 플랜 고려
프롬프트 품질 의존	모호한 지시에는 일관성 없는 결과	CLAUDE.md에 규칙을 명시하고, 구체적인 지시 습관화
에디터 통합 한계	공식 익스텐션이 VS Code, JetBrains만 지원	터미널 + 에디터 병행 사용 또는 지원 에디터로 전환
프로덕션 직접 배포 위험	검토 없이 프로덕션에 반영 시 위험	반드시 PR 리뷰 프로세스 유지, 자동 배포 파이프라인에 단독 진입 금지

MCP(Model Context Protocol)란? Claude Code가 외부 서비스(데이터베이스, 모니터링 도구, 내부 API 등)와 표준화된 방식으로 연결하기 위한 프로토콜이다. MCP 서버를 연결하면 Claude Code가 직접 DB를 조회하거나 Slack 메시지를 읽는 등 도구 범위를 크게 확장할 수 있다.

실무에서 가장 흔한 실수

CLAUDE.md 없이 사용하기: 프로젝트 규칙을 매번 대화에서 설명해야 하고, 세션마다 결과가 달라진다. 첫날 30분을 투자해 CLAUDE.md를 작성하면 이후 모든 작업의 품질이 달라진다.
Plan Mode를 건너뛰고 바로 실행하기: 특히 대규모 리팩터링이나 낯선 코드베이스에서 계획 검토 없이 실행하면, 예상치 못한 범위의 파일이 수정되는 경우가 생긴다. 처음에는 반드시 --plan 플래그 또는 Shift+Tab으로 Plan Mode를 활성화하고 시작하자.
모호한 지시로 무한 반복하기: "이 코드 개선해줘"처럼 추상적인 지시는 일관성 없는 결과를 낳는다. "이 함수의 시간 복잡도를 O(n²)에서 O(n log n)으로 줄여줘"처럼 구체적인 목표와 제약 조건을 함께 제시해야 한다.

마치며

Claude Code는 "AI가 코드를 대신 짜준다"는 도구가 아니라, 개발자가 목표를 설정하고 AI가 실행을 맡는 협업 시스템이다. 이 관점의 전환이 이 도구를 잘 쓰는 핵심이다. 목표를 명확히 정의하고, CLAUDE.md로 규칙을 사전에 가르치고, Plan Mode로 실행 전 검토하는 습관을 들이면 단순 코드 자동완성 도구와는 비교할 수 없는 생산성을 경험할 수 있다.

지금 바로 시작할 수 있는 3단계:

설치 후 기존 프로젝트에서 실행: npm install -g @anthropic-ai/claude-code 후 프로젝트 루트에서 claude 실행 (상세 설치 과정은 위 예시 1 참고)
CLAUDE.md 작성: 패키지 매니저, 코드 스타일, 테스트 방식, 금지 사항을 5~10줄로 정리해 프로젝트 루트에 저장
Plan Mode로 첫 작업 시도: --plan 플래그 또는 Shift+Tab으로 Plan Mode를 활성화한 뒤, 현재 해결하고 싶은 버그나 기능 하나를 자연어로 요청하고 계획을 검토

다음 시리즈

CLAUDE.md 고급 활용법 — Skills, Hooks, MCP를 조합해 팀 전체의 AI 워크플로를 표준화하는 방법을 다룬다. 팀원 모두가 같은 품질의 결과를 얻도록 Claude Code 환경을 설계하는 실전 가이드다.

참고 자료

Claude

Claude Code 완전 입문: 터미널 AI 에이전트로 코드베이스 자동화하기

핵심 개념

Claude Code란 무엇인가

에이전트(Agent)란? 단순히 질문에 답하는 것을 넘어, 목표를 달성하기 위해 여러 도구를 순차적으로 사용하며 스스로 결정을 내리는 AI 시스템을 말한다. Claude Code는 파일 읽기 → 수정 계획 → 코드 작성 → 테스트 실행 → 오류 수정이라는 루프를 반복한다.

에이전트 루프(Agentic Loop)

Claude Code가 일반적인 코드 자동완성 도구와 가장 크게 다른 점이 바로 이 루프다. 사용자가 목표를 입력하면 다음 사이클이 자동으로 돌아간다.

css

[목표 입력]
    ↓
[코드베이스 분석 — 관련 파일 탐색 및 이해]
    ↓
[계획 수립 — 어떤 파일을 어떻게 수정할지 결정]
    ↓
[실행 — 코드 작성, 파일 수정]
    ↓
[테스트 실행 — 결과 검증]
    ↓
[실패 시 오류 분석 → 수정 반복]
    ↓
[완료 보고]

CLAUDE.md — 프로젝트 헌법

yaml

# 프로젝트 규칙
 
- 패키지 매니저: pnpm만 사용 (npm, yarn 금지)
- 코드 스타일: TypeScript strict mode
- 테스트: 반드시 실제 DB 사용 (mock 금지)
- 커밋 메시지: 한국어 허용, imperative mood
 
# 빌드 & 테스트 명령어
- Build: `pnpm build`
- Test: `pnpm test`
 
# 아키텍처 규칙
- 비즈니스 로직은 Service에, Controller는 thin하게 유지

"테스트: 반드시 실제 DB 사용 (mock 금지)"를 명시하는 이유: Claude Code를 포함한 AI 도구는 테스트를 작성할 때 기본적으로 mock을 선택하는 경향이 있다. 그러나 mock 테스트는 실제 DB 스키마 변경, 마이그레이션 오류, 트랜잭션 동작 차이를 잡아내지 못한다. 이 규칙 한 줄이 통합 레벨의 신뢰도를 확보한다.

팁: CLAUDE.md는 팀 전체가 공유하는 파일이다. "pnpm만 사용", "mock DB 금지"처럼 과거에 팀원이 실수했거나 AI가 잘못 선택했던 패턴을 명시적으로 금지하면, 이후 세션의 결과 품질이 눈에 띄게 향상된다.

Plan Mode — 초보자에게 필수인 안전망

권한 관리 — 보수적인 설계

실전 적용

예시 1: 설치부터 첫 번째 기능 구현까지

공식 설치 방법은 npm을 통한 전역 패키지 설치다. Node.js 18 이상이 필요하다.

bash

# 공식 설치
npm install -g @anthropic-ai/claude-code
 
# 프로젝트 디렉토리에서 실행
cd my-project
claude
 
# 자연어로 기능 구현 요청
claude "로그인 API에 JWT 인증을 추가해줘. \
  액세스 토큰 만료는 15분, 리프레시 토큰은 7일로 설정해줘"

Claude Code는 이 명령 하나로 다음 작업을 자동 수행한다.

단계	수행 내용
1. 분석	기존 인증 관련 파일 탐색 및 구조 파악
2. 계획	수정이 필요한 파일 목록과 변경 방식 결정
3. 실행	JWT 라이브러리 설치, 미들웨어 작성, 라우터 수정
4. 검증	기존 테스트 실행 후 실패 시 자동 수정

예시 2: Plan Mode로 안전하게 대규모 리팩터링

# --plan 플래그로 Plan Mode 진입 (또는 대화 중 Shift+Tab)
claude --plan "전체 코드베이스에서 콜백 패턴을 async/await으로 변환해줘"

Plan Mode에서 Claude Code는 실제 수정 전에 계획을 먼저 출력한다. 아래는 응답 예시다(실제 출력 형식과 다를 수 있음).

bash

수정 계획:
1. src/utils/fileHelper.js — readFile 콜백 → async/await 변환 (3곳)
2. src/api/userRouter.js — 미들웨어 체인 재구성 (5곳)
3. src/services/emailService.js — 전체 재작성 필요 (12곳)
총 20개 파일, 약 87곳 수정 예정
실행할까요? [y/n]

계획을 먼저 검토하고 승인하면 실제 수정이 시작된다. 예상보다 수정 범위가 크거나 의도와 다른 방향이면 이 단계에서 방향을 바꿀 수 있다.

예시 3: 자율 테스트 루프

# 테스트를 통과할 때까지 자동으로 수정 반복
claude "현재 실패하는 테스트를 모두 통과시켜줘. \
  단, 테스트 코드 자체는 수정하지 말고 구현 코드만 수정해"

예시 4: Python 프로젝트에서 보안 취약점 점검

Claude Code는 TypeScript/Node.js 전용이 아니다. Python, Go 등 어떤 언어 기반 프로젝트에서도 동일하게 동작한다.

# Python FastAPI 프로젝트에서 보안 취약점 점검
claude "@app/api/routes.py @app/models/user.py \
  이 엔드포인트들에서 SQL injection 취약점이나 \
  인증 우회 가능한 부분을 찾아서 수정해줘"

python

# 수정 전 — 취약한 문자열 포맷 쿼리
@app.get("/users/{user_id}")
async def get_user(user_id: str):
    query = f"SELECT * FROM users WHERE id = {user_id}"  # SQL injection 위험
    result = await db.execute(query)
    ...
 
# Claude Code가 파라미터 바인딩 방식으로 자동 교체한 결과
@app.get("/users/{user_id}")
async def get_user(user_id: int, db: AsyncSession = Depends(get_db)):
    result = await db.execute(select(User).where(User.id == user_id))
    user = result.scalar_one_or_none()
    ...

예시 5: 특정 파일을 컨텍스트로 고정

# @멘션으로 특정 파일을 명시적으로 컨텍스트에 포함
claude "@src/types/user.ts @src/api/userRouter.ts \
  이 타입 정의를 기반으로 유저 CRUD API를 완성해줘"

대형 코드베이스에서 관련 없는 파일까지 분석하는 낭비를 줄이고, 정확도를 높이는 데 효과적인 패턴이다.

장단점 분석

장점

항목	내용
대형 컨텍스트 이해	복잡한 모노레포나 레거시 코드베이스를 전체적으로 파악 가능
자율 실행	테스트 → 오류 수정 → 재실행 루프를 사람 개입 없이 반복
터미널 네이티브	vim, tmux, zsh 등 기존 워크플로와 자연스럽게 통합
다언어 지원	TypeScript, Python, Go, Rust 등 언어 제약 없이 동작
확장성	MCP, Skills, Hooks로 팀과 프로젝트에 맞게 커스터마이징 가능

단점 및 주의사항

항목	내용	대응 방안
가격	전문 용도의 실질적 진입점은 Max 플랜($100/월)	팀 계정으로 비용 분산, 도입 전 무료 체험으로 효과 측정
사용량 제한	플랜에 따라 rate limit 존재 (최신 기준은 공식 요금제 페이지 확인)	중요 작업을 집중 처리하거나 상위 플랜 고려
프롬프트 품질 의존	모호한 지시에는 일관성 없는 결과	CLAUDE.md에 규칙을 명시하고, 구체적인 지시 습관화
에디터 통합 한계	공식 익스텐션이 VS Code, JetBrains만 지원	터미널 + 에디터 병행 사용 또는 지원 에디터로 전환
프로덕션 직접 배포 위험	검토 없이 프로덕션에 반영 시 위험	반드시 PR 리뷰 프로세스 유지, 자동 배포 파이프라인에 단독 진입 금지

MCP(Model Context Protocol)란? Claude Code가 외부 서비스(데이터베이스, 모니터링 도구, 내부 API 등)와 표준화된 방식으로 연결하기 위한 프로토콜이다. MCP 서버를 연결하면 Claude Code가 직접 DB를 조회하거나 Slack 메시지를 읽는 등 도구 범위를 크게 확장할 수 있다.

실무에서 가장 흔한 실수

CLAUDE.md 없이 사용하기: 프로젝트 규칙을 매번 대화에서 설명해야 하고, 세션마다 결과가 달라진다. 첫날 30분을 투자해 CLAUDE.md를 작성하면 이후 모든 작업의 품질이 달라진다.
Plan Mode를 건너뛰고 바로 실행하기: 특히 대규모 리팩터링이나 낯선 코드베이스에서 계획 검토 없이 실행하면, 예상치 못한 범위의 파일이 수정되는 경우가 생긴다. 처음에는 반드시 --plan 플래그 또는 Shift+Tab으로 Plan Mode를 활성화하고 시작하자.
모호한 지시로 무한 반복하기: "이 코드 개선해줘"처럼 추상적인 지시는 일관성 없는 결과를 낳는다. "이 함수의 시간 복잡도를 O(n²)에서 O(n log n)으로 줄여줘"처럼 구체적인 목표와 제약 조건을 함께 제시해야 한다.

마치며

지금 바로 시작할 수 있는 3단계:

설치 후 기존 프로젝트에서 실행: npm install -g @anthropic-ai/claude-code 후 프로젝트 루트에서 claude 실행 (상세 설치 과정은 위 예시 1 참고)
CLAUDE.md 작성: 패키지 매니저, 코드 스타일, 테스트 방식, 금지 사항을 5~10줄로 정리해 프로젝트 루트에 저장
Plan Mode로 첫 작업 시도: --plan 플래그 또는 Shift+Tab으로 Plan Mode를 활성화한 뒤, 현재 해결하고 싶은 버그나 기능 하나를 자연어로 요청하고 계획을 검토