[Claude] Claude Code CLI 명령어 완전 정복: 터미널에서 AI와 협업하는 실전 가이드

 

안녕하세요!

재아군의 관찰인생입니다.

 

오늘은 Anthropic이 만든 터미널 기반 AI 코딩 도구 Claude Code CLI의 명령어를 완전 정복해 보겠습니다.

IDE를 벗어나 터미널에서 AI와 직접 협업하는 시대가 왔습니다. Claude Code는 단순한 채팅 도구가 아니라, 파일을 읽고 쓰고, 테스트를 돌리고, Git 커밋까지 해주는 에이전틱 코딩 도구입니다.

 

이 글은 Claude Code를 처음 접하는 분부터, 이미 사용 중이지만 고급 기능을 활용하고 싶은 분까지 모두를 위해 작성되었습니다.

 

 

 

1. Claude Code CLI란?

 

핵심 정의

 

Claude Code는 Anthropic이 개발한 에이전틱 코딩 도구(Agentic Coding Tool)입니다. 터미널에서 실행되며 자연어로 지시하면 코드를 직접 읽고, 편집하고, 터미널 명령어를 실행하고, Git 작업까지 수행합니다.

 

Claude Code는 "AI에게 지시하는 도구"가 아니라 "AI와 페어 프로그래밍하는 터미널 환경"입니다.

 

기존 AI 코딩 도구(Copilot 자동완성, ChatGPT 코드 생성)와의 가장 큰 차이점은 에이전트 방식이라는 점입니다. Claude Code는 단순히 코드를 제안하는 게 아니라, 코드베이스를 직접 탐색하고, 파일을 수정하고, 빌드와 테스트를 실행하는 등 자율적으로 작업을 수행합니다.

 

설치 및 시작

 

# npm으로 전역 설치
npm install -g @anthropic-ai/claude-code

# 프로젝트 디렉토리에서 실행
cd my-project
claude

# 비대화형 모드 (CI/CD, 스크립트용)
claude -p "이 프로젝트의 디렉토리 구조를 설명해줘"

# 특정 모델 지정
claude --model claude-sonnet-4-6

 

설치 후 claude를 입력하면 대화형 REPL(Read-Eval-Print Loop)이 시작됩니다. 프로젝트 루트에서 실행하면 자동으로 코드베이스 컨텍스트를 인식합니다.

 

 

---

2. 핵심 CLI 옵션 & 실행 모드

 

주요 CLI 플래그

 

플래그	용도	예시
-p, --print	비대화형 모드 (결과 출력 후 종료)	claude -p "버그 찾아줘"
--model	사용할 모델 지정	claude --model claude-opus-4-6
--allowedTools	허용할 도구 지정	claude --allowedTools "Bash,Read,Write"
--continue	마지막 대화 이어서 진행	claude --continue
--resume	특정 세션 ID로 대화 재개	claude --resume abc123
--dangerouslySkipPermissions	권한 확인 생략 (CI용, 주의 필요)	claude -p --dangerouslySkipPermissions "..."

 

3가지 실행 모드

 

1) 대화형 모드 (Interactive) — 가장 기본적인 모드입니다. claude를 실행하면 진입합니다. 자연어로 대화하며 작업을 지시합니다.

 

2) 비대화형 모드 (Non-interactive) — claude -p "질문"으로 실행합니다. 결과를 stdout으로 출력하고 종료하므로 셸 스크립트나 파이프라인에 적합합니다.

 

# 파이프로 입력 전달
cat error.log | claude -p "이 에러 로그 분석해줘"

# 다른 명령어와 조합
claude -p "package.json 의존성 중 보안 취약점 있는 거 알려줘" | tee report.txt

 

3) CI/자동화 모드 — --dangerouslySkipPermissions 플래그와 함께 사용합니다. GitHub Actions 등에서 PR 리뷰 자동화, 코드 생성 등에 활용합니다.

 

---

3. 슬래시 커맨드 완전 정리

 

Claude Code 대화형 모드에서 /로 시작하는 슬래시 커맨드는 빠른 조작을 가능하게 합니다. 실무에서 가장 자주 사용하는 명령어를 카테고리별로 정리했습니다.

 

 

세션 & 컨텍스트 관리

 

명령어	기능	사용 시점
/clear	대화 컨텍스트 초기화	주제를 완전히 바꿀 때
/compact	대화 내용 요약 후 컨텍스트 압축	긴 작업 중 컨텍스트 한계 도달 시
/status	현재 세션 상태 확인 (토큰, 모델 등)	사용량 확인이 필요할 때

 

설정 & 권한

 

명령어	기능
/permissions	도구 권한 설정 조회 및 관리
/model	사용 중인 모델 변경
/config	Claude Code 설정 파일 열기/수정

 

코드 작업 & 리뷰

 

명령어	기능
/review	현재 코드 변경 사항 리뷰
/pr-comments	PR 코멘트 확인 및 반영

 

유틸리티

 

명령어	기능
/help	도움말 보기
/doctor	설치 상태 진단 및 문제 해결
/cost	현재 세션의 토큰 사용량 및 비용 확인
/logout	현재 인증 해제

 

Pro Tip: /를 입력하면 사용 가능한 모든 슬래시 커맨드가 자동완성으로 표시됩니다. 커스텀 스킬을 등록하면 여기에 함께 나타납니다.

 

---

4. CLAUDE.md — 프로젝트별 AI 지시서

 

Claude Code의 가장 강력한 기능 중 하나는 CLAUDE.md 파일입니다. 프로젝트 루트에 이 파일을 두면, Claude가 매 세션 시작 시 자동으로 읽어 프로젝트 컨텍스트를 파악합니다.

 

 

CLAUDE.md에 포함해야 할 내용

 

# CLAUDE.md

## Build & Run
npm install
npm run dev        # 개발 서버
npm run build      # 프로덕션 빌드
npm test           # 테스트 실행

## Architecture
- Next.js 15 App Router 사용
- src/app/ 아래 페이지 구성
- src/lib/ 에 유틸리티 함수
- Prisma ORM, PostgreSQL

## Coding Conventions
- TypeScript strict mode
- 함수형 컴포넌트 + React hooks만 사용
- 테스트: Vitest + Testing Library
- 커밋 메시지: Conventional Commits

## Environment Variables
- DATABASE_URL: PostgreSQL 연결 문자열
- NEXT_PUBLIC_API_URL: API 서버 주소

 

CLAUDE.md의 3가지 스코프

 

위치	스코프	Git 추적	용도
./CLAUDE.md	프로젝트 전체	O (팀 공유)	빌드 명령, 아키텍처, 컨벤션
./CLAUDE.local.md	프로젝트 (개인)	X (.gitignore)	개인 선호사항, 로컬 경로
~/.claude/CLAUDE.md	전역 (모든 프로젝트)	X	전역 선호사항, 공통 규칙

 

핵심 포인트: CLAUDE.md는 팀 전체가 공유하고, CLAUDE.local.md는 개인 설정에 사용하세요. 이렇게 분리하면 팀 컨벤션은 통일하면서 개인 워크플로우는 자유롭게 유지할 수 있습니다.

 

---

5. 내장 도구(Tools) & 권한 시스템

 

Claude Code는 내부적으로 여러 도구(Tools)를 사용해 작업을 수행합니다. 사용자는 이 도구들에 대한 권한을 세밀하게 제어할 수 있습니다.

 

주요 내장 도구

 

도구	기능	권한 레벨
Read	파일 읽기	자동 허용
Write	새 파일 생성	확인 필요
Edit	기존 파일 수정	확인 필요
Bash	터미널 명령어 실행	확인 필요
Glob / Grep	파일 패턴 검색 / 내용 검색	자동 허용
Agent	하위 에이전트 생성 (병렬 작업)	확인 필요
WebFetch / WebSearch	웹 페이지 가져오기 / 검색	확인 필요

 

권한 모드 설정

 

Claude Code에서 /permissions를 실행하면 도구별 권한을 설정할 수 있습니다. settings.json에서도 직접 관리 가능합니다.

 

// .claude/settings.json
{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git *)",
      "Write(src/**)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force *)"
    ]
  }
}

 

권한 설정의 핵심 원칙은 최소 권한(Least Privilege)입니다. 읽기 도구는 자동으로 허용하되, 파일 쓰기와 명령어 실행은 패턴으로 세밀하게 제어하세요.

 

---

6. Hooks & MCP — 자동화와 확장의 핵심

 

Hooks: 이벤트 기반 자동화

 

Hooks는 Claude Code의 특정 이벤트에 반응하여 셸 명령어를 자동 실행하는 기능입니다. "파일 저장 후 자동으로 린트 실행", "커밋 전에 테스트 실행" 같은 자동화를 구현할 수 있습니다.

 

// .claude/settings.json 에서 hooks 설정 예시
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx eslint --fix $CLAUDE_FILE_PATH"
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "echo '명령어 실행 중: $CLAUDE_TOOL_INPUT'"
      }
    ]
  }
}

 

주요 Hook 이벤트:

• PreToolUse: 도구 실행 전 — 검증, 로깅, 차단에 활용
• PostToolUse: 도구 실행 후 — 린트, 포맷팅, 알림에 활용
• Notification: Claude가 알림을 보낼 때 — 슬랙 연동 등

 

MCP 서버: 외부 도구 연결

 

MCP(Model Context Protocol)는 Claude Code에 외부 도구를 연결하는 표준 프로토콜입니다.

데이터베이스, Slack, Jira, 모니터링 시스템 등을 Claude Code의 도구로 추가할 수 있습니다.

 

# MCP 서버 추가
claude mcp add my-db --transport stdio -- npx @modelcontextprotocol/server-postgres $DATABASE_URL

# HTTP 방식 MCP 서버 추가
claude mcp add my-api --transport http https://api.example.com/mcp

# MCP 서버 목록 확인
claude mcp list

# MCP 서버 제거
claude mcp remove my-db

 

MCP 서버가 연결되면 Claude Code 안에서 자연어로 외부 시스템을 조작할 수 있습니다.

예를 들어 PostgreSQL MCP를 연결하면 "users 테이블에서 최근 가입자 10명 보여줘"라고 말하면 됩니다.

 

 

---

7. 경쟁 도구 비교: Claude Code vs Cursor vs GitHub Copilot vs Aider

 

비교 항목	Claude Code	Cursor	Copilot CLI	Aider
실행 환경	터미널 (CLI)	VS Code 포크 (IDE)	터미널 (CLI)	터미널 (CLI)
에이전트 방식	O (자율 작업)	O (Agent Mode)	X (단발성 응답)	O (자율 편집)
파일 직접 편집	O	O	X	O
MCP 지원	O (네이티브)	O	X	X
확장성	Hooks + MCP + Skills	VS Code 확장	제한적	설정 파일
최적 사용자	터미널 파워유저, 자동화 매니아	IDE 선호 개발자	GitHub 생태계 사용자	오픈소스 선호, 다양한 LLM 활용자

 

Claude Code가 빛나는 상황:

• 대규모 리팩토링이나 멀티 파일 변경이 필요할 때
• CI/CD 파이프라인에 AI 코드 리뷰를 통합하고 싶을 때
• MCP로 외부 시스템(DB, API, 모니터링)과 연동해야 할 때
• SSH 환경이나 원격 서버에서 작업할 때

 

---

8. 실전 워크플로우 & 베스트 프랙티스

 

워크플로우 1: 버그 수정

 

# 1. 에러 로그를 직접 전달
cat error.log | claude -p "이 에러의 원인을 찾고 수정해줘"

# 2. 또는 대화형으로 진행
claude
> 이 프로젝트에서 "TypeError: Cannot read property 'map' of undefined" 에러가 나와.
> 원인을 찾아서 수정해줘.

 

워크플로우 2: PR 리뷰 자동화

 

# GitHub Actions에서 PR 리뷰 자동화
# .github/workflows/claude-review.yml
- name: Claude Code Review
  run: |
    git diff origin/main...HEAD | claude -p \
      "이 diff를 리뷰해줘. 버그, 보안 취약점, 성능 이슈를 찾아줘." \
      --dangerouslySkipPermissions

 

워크플로우 3: 새 기능 개발

 

claude
> 사용자 프로필 페이지를 만들어줘.
> - /profile 라우트
> - 이름, 이메일, 프로필 이미지 표시
> - 프로필 수정 기능
> - Prisma에서 User 모델 사용
> - 기존 프로젝트 컨벤션 따라줘

 

5가지 베스트 프랙티스

 

1. CLAUDE.md를 항상 최신 상태로 유지하세요. 빌드 명령어, 아키텍처, 컨벤션이 정확할수록 Claude Code의 출력 품질이 올라갑니다.
2. 구체적으로 지시하세요. "코드 개선해줘" 보다 "이 함수의 N+1 쿼리 문제를 Prisma의 include로 해결해줘"가 훨씬 좋은 결과를 냅니다.
3. 권한은 최소한으로 설정하세요. Bash(npm test)처럼 허용할 명령어를 구체적으로 지정하세요.
4. /compact를 적극 활용하세요. 긴 작업 중에는 컨텍스트를 정리해야 Claude가 혼란 없이 작업을 이어갑니다.
5. Git 커밋은 자주 하세요. Claude Code가 파일을 직접 수정하므로, 중간중간 커밋해두면 언제든 되돌릴 수 있습니다.

 

---

마무리

 

오늘은 Claude Code CLI의 설치부터 핵심 명령어, 슬래시 커맨드, CLAUDE.md 설정, 권한 관리, Hooks, MCP 서버, 그리고 실전 워크플로우까지 총정리해 봤습니다.

 

핵심을 정리하면:

 

• Claude Code는 터미널에서 동작하는 에이전틱 코딩 도구로, 파일 편집부터 Git 작업까지 자율적으로 수행합니다
• CLAUDE.md로 프로젝트 컨텍스트를 제공하면 AI의 이해도가 비약적으로 향상됩니다
• Hooks와 MCP로 자동화와 외부 시스템 연동을 구현할 수 있습니다
• 권한 시스템으로 안전하게 AI의 행동 범위를 제어할 수 있습니다

 

터미널에서 AI와 협업하는 시대, Claude Code CLI로 개발 생산성을 한 단계 끌어올려 보세요.

 

이 글이 도움이 되셨다면 댓글과 공유 부탁드립니다.
Claude Code 활용에 대해 궁금한 점이 있다면 언제든 댓글로 남겨주세요!

 

다음 글에서 더 깊이 있는 내용으로 찾아뵙겠습니다.

감사합니다!