Claude Code Guide

이번 블로그에서는 Claude Code에 대해 알아보고 활용하는 방법에 대한 글을 작성해보겠습니다.

 

What is Claude Code?

• Anthropic의 CLI 기반 AI 코딩 에이전트입니다.
• 코드베이스를 읽고, 파일을 편집하고, 명령을 실행하고, 개발 도구와 통합하는 에이전트 코딩 도구입니다.
• Fable 5.1, Sonnet 5, Opus 5 등 최신 모델을 사용하고 있습니다.
• 뛰어난 컨텍스트 관리 및 툴 호출 능력을 가지고 있습니다.

 

Initial Setup

• Mac / Linux 기준

# 설치
curl -fsSL <https://claude.ai/install.sh> | bash

# 프로젝트 시작
mkdir my-project
cd my-project
claude

• Windows 기준

# Powershell
irm <https://claude.ai/install.ps1> | iex

# CMD
curl -fsSL <https://claude.ai/install.cmd> -o install.cmd && install.cmd && del install.cmd

# 프로젝트 시작
mkdir my-project
cd my-project
claude

 

Chatting Mode (3가지)

Interactive

• 터미널 UI로 계속 대화합니다.
• 필요 시 권한 프롬프트가 뜨게 됩니다.

claude

Print / Headless

• 한 번 실행하고 응답을 stdout에 출력 후 종료합니다.

claude -p "질문"

Bare 모드

• headless보다도 더 가볍게 시작합니다.
• hooks, skills, 커스텀 커맨드, 서브에이전트, 플러그인, MCP 서버, auto memory, CLAUDE.md 자동 탐색을 전부 건너뜁니다.
• CI에서 어느 머신에서 실행해도 항상 같은 결과가 필요할 때 사용합니다.

claude --bare -p "..."

 

Permission Mode

• 세션 안에서 Claude가 확인 없이 어디까지 행동해도 되는가를 결정하는 설정입니다.
  CLI에서는 Shift+Tab으로 순환 전환 가능합니다.

모드 (config 값)	CLI 표시 이름	확인 없이 실행되는 것	용도
default	Manual	읽기(Read)만	민감한 작업, 모든 액션을 직접 검토
acceptEdits	Accept Edits	읽기 + 파일 편집 + 기본 파일시스템 명령(mkdir,touch,mv,cp 등)	이미 검토 중인 코드를 반복 수정할 때
plan	Plan Mode	읽기만 (auto 모드 사용 가능 시 classifier가 승인한 명령 포함)	변경 전에 코드베이스 탐색
auto	Auto Mode	거의 모든 것 (별도 분류기 모델이 백그라운드에서 안전성 검사)	장시간 작업, 프롬프트 피로 감소 - Pro/Max/Team 플랜의 기본값
dontAsk	Don't Ask	읽기 + 사전 승인된 도구만. 나머지는 전부 거부	잠금된 CI/스크립트 환경
bypassPermissions	Bypass Permissions	전부	격리된 컨테이너/VM 내부에서만 사용 권장

 

Memory System

• Claude Code의 각 세션은 매번 빈 컨텍스트로 시작합니다.
  세션 간 지식을 이어주는 장치가 두 가지 있습니다.

	CLAUDE.md	Auto Memory
작성 주체	사용자	Claude
내용	지시·규칙	학습한 내용·패턴
범위	프로젝트 / 사용자 / 조직	저장소 단위
로드 시점	세션 시작 시	세션 시작 시
용도	코딩 표준, 워크플로, 프로젝트 아키텍처	사용자 선호, 교정 사항, 코드로 알기 어려운 맥락

 

CLAUDE.md

• 팀 전체가 따라야 하는 코딩 컨벤션, 아키텍처 패턴, 보안 관련 코딩 규칙을 작성합니다.
• 팀이 주도적으로 관리하는 규칙·지침 파일입니다.
• 프로젝트 루트, 상위/하위 디렉토리, 사용자 홈 (~/.claude/CLAUDE.md) 등 여러 위치에 계층적으로 둘 수 있으며, 가까운 디렉토리의 내용이 우선 적용됩니다.

1. CLAUDE.md 위치와 우선순위

범위	경로	용도	공유 대상
관리 정책	macOS /Library/Application Support/ClaudeCode/CLAUDE.md Linux/WSL /etc/claude-code/CLAUDE.md Windows C:\Program Files\ClaudeCode\CLAUDE.md	조직 전체 정책 (IT/DevOps가 배포)	조직의 모든 사용자
사용자 지시	~/.claude/CLAUDE.md	모든 프로젝트에 적용되는 개인 설정	나만 (모든 프로젝트)
프로젝트 지시	./CLAUDE.md 또는 ./.claude/CLAUDE.md	팀 공유 지시 (버전관리로 공유)	팀원
로컬 지시	./CLAUDE.local.md	개인 프로젝트별 설정 (.gitignore 권장)	나만 (해당 프로젝트)

 

2. @path import 문법

See @README for project overview and @package.json for available npm commands.

# Additional Instructions
- git workflow @docs/git-instructions.md

• 상대 경로는 CLAUDE.md 파일 기준(작업 디렉토리 기준 아님)으로 해석됩니다.
• 재귀 import가 가능하며, 최대 깊이 4단계(hop)까지 허용됩니다.
• 백틱으로 감싸면(@README) import되지 않고 문자 그대로 표시됩니다.
• 작업 디렉토리 바깥을 가리키는 것은 최초 1회 승인 다이얼로그가 뜨게 됩니다.

Auto Memory

• Claude Code가 작업 중 유용한 컨텍스트를 자동으로 기록하고, 이후 세션에서 다시 불러오는 자동 메모리 기능입니다.
• 작업 흐름에서 발견한 프로젝트 패턴, 주요 명령어, 개인 선호도를 사용자 로컬 환경에서 프로젝트별로 MEMORY.md에 자동 저장합니다. (다음 세션 시작 시 이를 불러와 컨텍스트에 반영합니다.)
• Auto Memory는 Claude Code 설치 시 기본으로 활성화 되어 있습니다.
• MEMORY.md는 첫 200줄만 자동 로딩 되며, 상세 내용은 토픽 파일로 분리하도록 설계되어 있습니다.
• 그럼으로 /memory명령어로, 주기적으로 중요하지 않은 패턴을 주기적으로 정리하는 것을 권장합니다.

Lifecycle Hooks

Lifecycle(생명주기)은 Claude Code가 실행을 시작하고 작업을 수행한 뒤 종료하기까지의 전체 과정과 각 단계에서 발생하는 이벤트를 의미합니다. 5개 생명주기 훅(Lifecycle Hooks)은 다음과 같습니다.

훅	실행 시점	주요 용도
SessionStart	Claude Code 세션 시작 시	환경 초기화, 컨텍스트 설정
UserPromptSubmit	사용자가 프롬프트를 입력할 때	입력 검증·가공, 추가 컨텍스트 주입
PreToolUse	Claude가 도구를 실행하기 직전	실행 전 검증·차단·수정
PostToolUse	도구 실행이 끝난 직후	결과 확인, 후처리, 로그
Stop	Claude의 작업이 끝날 때	종료 시 검사, 정리 작업

 

전체 흐름은 아래와 같이 동작합니다.

Claude Code 실행
      │
      ▼
 SessionStart
      │
      ▼
사용자 프롬프트 입력
      │
      ▼
UserPromptSubmit
      │
      ▼
Claude가 작업 계획
      │
      ▼
PreToolUse ──→ 도구 실행 허용/차단
      │
      ▼
   Tool 실행
      │
      ▼
PostToolUse ──→ 결과 후처리
      │
      ▼
 Claude 작업 종료
      │
      ▼
    Stop

 

Commands

핵심 커맨드

• /compact - 대화 맥락 압축 및 요약
• /context - 컨텍스트·토큰 사용량 확인
• /model - AI 모델 전환
• /cost - 사용 비용 확인
• /review - 코드 리뷰 요청

세션 관리

• /clear - 현재 대화 내용 초기화
• /rewind - 이전 상태로 되돌리기
• /resume - 이전 세션 이어서 작업

프로젝트 · 메모리

• /init - CLAUDE.md 생성 및 프로젝트 초기화
• /memory - 메모리 확인·편집
• /todos - 작업 목록 확인

진단 · 연결

• /doctor - Claude Code 설치·환경 진단
• /status - 현재 상태 및 설정 확인
• /mcp - MCP 서버 및 연결 상태 확인

 

이것으로 Claude Code Guide 글을 마치겠습니다. 감사합니다!