개발자를 위한 Claude CLI 완벽 가이드 – 터미널에서 AI를 200% 활용하는 법
Claude CLI란?
Claude CLI(Command Line Interface)는 Anthropic이 제공하는 터미널 기반 AI 코딩 어시스턴트입니다. VS Code 같은 GUI 에디터 없이도 터미널에서 직접 Claude와 대화하며 코드를 작성하고, 파일을 수정하고, 프로젝트를 탐색할 수 있습니다. 특히 SSH 환경이나 서버 작업 시 강력한 위력을 발휘합니다.
설치 방법
Claude CLI는 npm을 통해 간단하게 설치할 수 있습니다.
npm install -g @anthropic-ai/claude-code설치 후 최초 실행 시 Anthropic 계정 인증이 필요합니다.
claude
# 브라우저가 열리며 OAuth 인증 진행기본 실행과 대화
인터랙티브 모드
가장 기본적인 사용법은 프로젝트 디렉토리에서 claude를 실행하는 것입니다.
cd ~/my-project
claude실행하면 대화형 REPL이 시작되며, 자연어로 질문하거나 작업을 요청할 수 있습니다. Claude는 현재 디렉토리의 파일 구조와 코드를 자동으로 인식합니다.
원샷(One-shot) 모드
대화형 모드 없이 단일 명령을 바로 실행하고 싶을 때는 -p (print) 플래그를 사용합니다.
# 단일 질문 후 결과만 출력
claude -p "이 프로젝트의 디렉토리 구조를 설명해줘"
# 파이프와 조합하여 사용
cat error.log | claude -p "이 에러 로그를 분석해서 원인을 알려줘"이 모드는 스크립트나 CI/CD 파이프라인에 통합할 때 특히 유용합니다.
핵심 명령어와 플래그 총정리
자주 쓰는 실행 옵션
| 명령어/플래그 | 설명 | 예시 |
|---|---|---|
claude |
인터랙티브 모드 시작 | claude |
claude -p |
원샷 모드 (stdout 출력) | claude -p "함수 설명해줘" |
claude -r |
이전 대화 이어서 진행 | claude -r |
claude --model |
사용할 모델 지정 | claude --model claude-sonnet-4-6 |
claude --allowedTools |
허용할 도구 제한 | claude --allowedTools Read,Grep |
claude --output-format |
출력 형식 지정 | claude -p --output-format json "분석해줘" |
대화 중 슬래시 명령어
인터랙티브 모드에서 사용할 수 있는 슬래시 명령어들입니다.
| 명령어 | 설명 |
|---|---|
/help |
도움말 표시 |
/clear |
대화 컨텍스트 초기화 |
/compact |
대화 내용을 요약하여 컨텍스트 절약 |
/cost |
현재 세션의 토큰 사용량 및 비용 확인 |
/model |
사용 중인 모델 변경 |
/fast |
빠른 응답 모드 토글 |
/permissions |
권한 설정 확인 및 변경 |
/commit |
변경사항을 git commit |
실전 활용 예시
1. 코드 리뷰 및 리팩토링
# 특정 파일의 코드 리뷰 요청
claude -p "src/auth/login.ts 파일을 리뷰하고 개선점을 알려줘"
# 리팩토링 직접 실행
claude
> src/utils/helpers.ts에서 중복된 유틸 함수들을 하나로 합쳐줘2. 테스트 코드 자동 생성
claude
> src/services/userService.ts에 대한 단위 테스트를 Jest로 작성해줘.
> 엣지 케이스도 포함해줘.Claude는 파일을 직접 읽고 분석한 뒤, 적절한 테스트 파일을 생성합니다.
3. 파이프라인 연동 – 로그 분석
# 최근 에러 로그 분석
tail -100 /var/log/app/error.log | claude -p "이 에러들의 패턴을 분석하고 근본 원인을 추정해줘"
# git diff를 넘겨서 변경사항 요약
git diff HEAD~3 | claude -p "이 변경사항을 한국어로 요약해줘"4. 프로젝트 초기 설정 자동화
claude
> Spring Boot 3.2 + Kotlin + Gradle 프로젝트를 생성해줘.
> PostgreSQL JPA 설정과 Docker Compose도 포함해줘.5. 데이터베이스 마이그레이션 스크립트 생성
claude
> users 테이블에 phone_number 컬럼(VARCHAR 20, nullable)을 추가하는
> Flyway 마이그레이션 스크립트를 V3__add_phone_number.sql로 만들어줘CLAUDE.md로 프로젝트 컨텍스트 설정하기
프로젝트 루트에 CLAUDE.md 파일을 생성하면 Claude가 매 세션마다 자동으로 읽어 프로젝트의 맥락을 파악합니다. 이 파일은 프로젝트의 “사용 설명서” 역할을 합니다.
# CLAUDE.md 예시
## 프로젝트 개요
- Spring Boot 3.2 기반 REST API 서버
- Java 21, Gradle 빌드
## 코딩 컨벤션
- 변수명: camelCase
- 패키지 구조: 도메인 기반 (domain/user, domain/order)
- 모든 API는 /api/v1 prefix 사용
## 빌드 및 테스트
- 빌드: ./gradlew build
- 테스트: ./gradlew test
- 로컬 실행: docker-compose up -d && ./gradlew bootRun이렇게 설정해두면 Claude가 프로젝트의 컨벤션을 자동으로 따르며, 매번 같은 설명을 반복할 필요가 없습니다.
권한(Permission) 시스템 이해하기
Claude CLI는 파일 읽기, 쓰기, 명령어 실행 등의 작업에 대해 권한 시스템을 적용합니다.
권한 모드 3가지
- Ask mode (기본): 모든 파일 수정과 명령어 실행 전에 사용자 확인을 요청합니다.
- Auto-edit mode: 파일 읽기/쓰기는 자동 허용하되, bash 명령어는 확인을 요청합니다.
- Full auto mode: 모든 작업을 자동으로 수행합니다. CI/CD 파이프라인 용도에 적합합니다.
# 특정 도구만 자동 허용하여 실행
claude --allowedTools Edit,Write,Read -p "README.md를 업데이트해줘"설정 파일(~/.claude/settings.json)에서 프로젝트별로 세밀하게 권한을 관리할 수도 있습니다.
// ~/.claude/settings.json
{
"permissions": {
"allow": [
"Read",
"Glob",
"Grep",
"Bash(npm test)",
"Bash(npm run build)"
]
}
}CI/CD 파이프라인에서 활용하기
Claude CLI는 비대화형(non-interactive) 환경에서도 작동하므로 GitHub Actions 등과 연동할 수 있습니다.
# GitHub Actions 워크플로우 예시
name: AI Code Review
on: [pull_request]
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Claude CLI
run: npm install -g @anthropic-ai/claude-code
- name: Run AI Review
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
git diff origin/main | claude -p \
--output-format json \
"이 PR의 코드를 리뷰하고 개선점을 JSON으로 정리해줘"유용한 팁 모음
컨텍스트 관리
긴 대화를 하다 보면 컨텍스트 윈도우가 가득 찰 수 있습니다. /compact 명령어로 이전 대화를 요약하여 컨텍스트를 확보하세요.
> /compact
# 이전 대화가 요약되어 컨텍스트 공간 확보멀티 턴 작업 시 대화 이어가기
# 이전 세션 이어서 작업
claude -r
> 아까 만들던 API에 페이지네이션 기능도 추가해줘특정 파일만 집중 작업
대규모 프로젝트에서 특정 파일들만 작업하고 싶다면 명시적으로 파일을 지정하세요.
claude
> @src/controllers/orderController.ts @src/services/orderService.ts
> 이 두 파일의 에러 핸들링을 개선해줘비용 모니터링
> /cost
# 현재 세션: 입력 15,234 토큰, 출력 3,421 토큰
# 예상 비용: $0.12마무리
Claude CLI는 터미널에서 벗어나지 않고도 AI의 도움을 받을 수 있는 강력한 도구입니다. 특히 파이프라인 연동, CLAUDE.md를 통한 프로젝트 컨텍스트 설정, 권한 시스템을 활용한 안전한 자동화가 핵심 장점입니다.
처음에는 claude -p로 간단한 질문부터 시작하고, 점차 인터랙티브 모드와 CI/CD 연동으로 확장해 나가는 것을 추천합니다. 터미널 중심 개발 워크플로우를 선호하는 개발자라면, Claude CLI가 생산성을 확실히 한 단계 끌어올려 줄 것입니다.
Photo by Nemuel Sereti on Pexels
