서론

Claude Code는 Anthropic사가 제공하는 AI 지원 개발 도구입니다. CLI, 데스크톱 앱, Web 버전(claude.ai/code), IDE 확장 기능으로 이용할 수 있으며, 코딩, 디버깅, 리팩터링(Refactoring) 등 개발의 다양한 상황에서 AI가 지원해 줍니다.

이 기사에서는 Claude Code의 내장 기능의 전체 모습을 입문자용으로 해설합니다.

대상 독자:

• Claude Code를 막 사용하기 시작한 분
• 어떤 기능이 있는지 알고 싶은 분
• 기본적인 사용법을 이해하고 싶은 분

이 기사에서 알 수 있는 내용:

• Claude Code의 기본적인 사용법
• 주요 내장 기능 (Read, Edit, CLAUDE.md, Agent, Plan 등)
• 초기 설정 시 설정해야 할 기능
• 다음에 학습해야 할 내용

1. Claude Code란

1.1 Claude Code의 특징

• AI 어시스턴트 (AI Assistant): Claude (Sonnet 4.5 등)가 코드를 읽고, 편집하고, 실행을 지원
• 멀티 플랫폼 (Multi-platform): CLI, 데스크톱, Web, IDE 확장
• 파일 조작 (File Operation): 로컬 파일의 읽기/쓰기, 검색, 편집
• 명령 실행 (Command Execution): 셸(Shell) 명령, 스크립트 실행
• Git 통합 (Git Integration): 브랜치 생성, 커밋(Commit), PR 생성

1.2 기본적인 사용법

CLI 버전 실행

claude

대화 예시

사용자: "이 프로젝트의 구조를 알려줘"
Claude: 프로젝트를 탐색하여 파일 구성을 설명
사용자: "README에 설치 절차를 추가해줘"
...

2. 기본적인 도구

Claude Code는 다음 도구들을 사용하여 태스크(Task)를 실행합니다.

2.1 Read: 파일 읽기

사용자: "src/main.py의 내용을 확인해줘"
Claude: Read(src/main.py) → 파일 내용 표시

특징:

• 큰 파일은 범위 지정으로 읽기 (offset, limit)
• PDF 파일도 읽기 가능 (페이지 지정)
• Jupyter Notebook도 대응

2.2 Edit: 파일 편집

사용자: "이 함수에 Docstring을 추가해줘"
Claude: Edit(src/main.py, old_string, new_string)

특징:

• 차이점(Diff)만 전송 (효율적)
• 편집 전에 반드시 Read로 파일을 확인
• 여러 곳을 동시에 편집 가능

2.3 Write: 신규 파일 생성

사용자: "tests/test_main.py를 생성해줘"
Claude: Write(tests/test_main.py, content)

주의:

• 기존 파일의 편집에는 Edit를 사용
• Write는 덮어쓰기를 하므로 기존 파일에는 사용하지 않음

2.4 Bash: 명령 실행

사용자: "테스트를 실행해줘"
Claude: Bash(pytest tests/ -v)

특징:

• 셸(Shell) 명령을 실행
• git, npm, pytest 등의 도구를 이용 가능
• run_in_background로 백그라운드 실행도 가능

3. CLAUDE.md: 가장 먼저 설정해야 할 프로젝트 컨텍스트

3.1 CLAUDE.md란

프로젝트 루트에 배치하는 마크다운(Markdown) 파일로, Claude Code가 대화 시작 시 자동으로 읽어 들입니다.

역할:

• 프로젝트의 전체 모습을 AI에게 전달
• 코딩 규약 및 개발 흐름(Flow) 정의
• 자주 사용하는 명령을 기록

3.2 기본적인 작성법

# 프로젝트명
## 기술 스택
- Python 3.11
...

3.3 왜 가장 먼저 설정해야 하는가

CLAUDE.md가 있으면 Claude Code는:

• 프로젝트의 기술 스택을 이해
• 코딩 규약에 따른 제안
• 자주 사용하는 명령을 파악

권장: Claude Code를 사용하기 시작하면, 먼저 CLAUDE.md를 작성합시다.

상세한 작성법: 실전적인 작성법이나 컨텍스트 열화 문제에 대해서는 하네스(Harness) 기능 상세 해설에서 설명하고 있습니다.

4. settings.json: 권한 관리와 환경 설정

4.1 settings.json이란

.claude/settings.json에서 프로젝트 고유의 설정을 정의합니다.

주요 용도:

• 자주 사용하는 명령의 자동 허용
• 환경 변수 (Environment Variables) 설정
• HOOK (자동 실행 명령) 정의

4.2 권한 관리 설정

자주 사용하는 명령을 자동 허용함으로써 매번 승인하는 과정을 생략할 수 있습니다:

{
"permissions": {
"allow": [
...

4.3 환경 변수 설정

프로젝트 모드 및 설정을 정의합니다:

{
"env": {
"PROJECT_MODE": "development",
...

4.4 초기 설정 시 권장 설정

{
"permissions": {
"allow": [
...

상세 내용: 하네스 (Harness) 기능 상세 해설에서 자세히 설명하고 있습니다.

5. Agent: 서브 에이전트에 의한 병렬 작업

5.1 Agent란

복잡한 태스크 (Task)나 탐색적인 작업을 **서브 에이전트 (Sub-agent)**에게 위임할 수 있습니다.

장점:

• 메인 대화 컨텍스트 (Context) 절약
• 병렬로 여러 조사를 실행
• 전문적인 태스크에 특화된 에이전트

5.2 Agent의 종류

Explore: 코드베이스 탐색

사용자: "인증 관련 코드를 모두 조사해줘"
Claude: Explore 에이전트 기동
→ 여러 파일을 병렬로 탐색하고 결과를 보고

용도:

• 대규모 코드베이스 탐색
• 특정 기능이 어디에 있는지 조사
• 의존 관계 파악

Plan: 구현 계획 수립

사용자: "신규 기능 구현 플랜을 작성해줘"
Claude: Plan 에이전트 기동
→ 아키텍처 (Architecture)를 검토하고 상세한 플랜을 제시

용도:

• 대규모 변경에 대한 사전 계획
• 여러 가지 접근 방식 비교
• 리스크 도출

general-purpose: 범용 태스크

사용자: "여러 API 문서를 조사해줘"
Claude: 범용 에이전트 기동

5.3 Agent의 활용 시점

• 사용할 때: 대규모 탐색, 독립적인 조사 태스크
• 사용하지 않을 때: 간단한 파일 읽기, 단일 파일 편집

6. Plan mode: 구현 전 계획 수립

6.1 Plan mode란

큰 변경을 구현하기 전에, 상세한 계획을 세워 사용자의 승인을 얻는 모드입니다.

6.2 Plan mode의 흐름

1. 탐색 페이즈 (Phase)
Explore 에이전트로 코드베이스를 조사
2. 설계 페이즈 (Phase)
...

6.3 Plan mode가 유용한 상황

• 여러 파일에 걸친 변경: 영향 범위가 넓음
• 아키텍처 변경: 설계 판단이 필요함
• 불명확한 점이 많음: 우선 조사 및 검토가 필요함

6.4 Plan mode의 예시

사용자: "인증 시스템을 JWT에서 OAuth로 전환하고 싶어"
Claude: Plan mode로 진입합니다
→ Phase 1: 인증 관련 코드를 모두 탐색 (Explore 에이전트)
...

7. Task 관리: 진행 상황의 가시화

7.1 Task 기능이란

여러 단계로 이루어진 태스크를 분해하고 진행 상황을 추적하는 기능입니다.

7.2 기본적인 사용법

사용자: "신규 기능을 구현해줘"
Claude: 태스크를 생성합니다
Task 1: 설계 [not_started]
...

7.3 Task 활용 시나리오

• 큰 태스크를 작게 분해
• 진행 상황을 한눈에 파악
• 세션 (Session)이 바뀌어도 상태를 유지

8. Memory: 대화로부터 학습하는 영구적인 기억

8.1 Memory란

Claude Code는 대화로부터 중요한 정보를 자동으로 추출하여 .claude/projects/[project]/memory/에 영구적으로 저장합니다.

CLAUDE.md와의 차이점:

• CLAUDE.md: 수동으로 작성하는 프로젝트 정보
• Memory: 대화로부터 자동으로 학습

8.2 Memory의 종류

• user: 사용자의 역할, 선호도, 숙련도
• feedback: 과거의 피드백, 실패 사례
• project: 프로젝트 진행 상황, 결정 사항
• reference: 외부 리소스에 대한 포인터 (Pointer)

8.3 기본적인 사용법

명시적인 기록

당신: 「프로젝트에서는 Pytest를 사용한다는 것을 기억해 둬」
Claude: Memory에 저장했습니다

자동 학습

대화 중에 중요한 정보를 자동으로 감지하여 저장합니다.

8.4 주의 사항

Memory는 시간이 지남에 따라 오래됩니다. 정기적인 정리가 필요합니다 (월 1회 권장).

상세 내용: 하네스(Harness) 기능 상세 해설에서 자세히 설명하고 있습니다.

9. SKILLS: 정형화된 태스크를 명령어로 자동화

9.1 SKILLS란

자주 사용하는 정형화된 태스크(Task)를 /skill-name 명령어로 등록할 수 있습니다.

배치 위치: .claude/skills/[skill-name].md

9.2 기본적인 작성 방법

<!-- .claude/skills/review.md -->
---
name: review
...

호출 방법:

당신: /review

9.3 자주 사용하는 SKILLS 예시

• /review: 코드 리뷰 (Code Review)
• /test: 테스트 실행 및 결과 분석
• /deploy: 배포 절차 실행

9.4 언제 사용해야 하는가

• 반복적으로 실행하는 태스크
• 체크리스트가 명확한 태스크
• 팀 내에서 절차를 통일하고 싶은 태스크

상세 내용: 하네스(Harness) 기능 상세 해설에서 실전 사례를 소개하고 있습니다.

10. HOOK: 이벤트 기반의 자동 실행

10.1 HOOK란

특정 이벤트 발생 시 자동으로 실행되는 명령어를 settings.json에서 정의할 수 있습니다.

주요 이벤트:

• session-start-hook: 세션 시작 시
• user-prompt-submit-hook: 프롬프트 전송 시
• tool-result-hook: 도구(Tool) 실행 후

10.2 기본적인 설정 예시

{
  "hooks": {
    "session-start-hook": "echo '개발 모드: 테스트 커버리지 80% 이상'",
    ...
  }
}

10.3 활용 사례

• 주의 환기: 프로젝트 고유의 제약 사항 표시
• 자동 체크: 편집 후 린트(Lint) 실행
• 통계 기록: 세션 정보를 로그(Log)에 기록

10.4 초보자를 위한 권장 사항

HOOK은 고급 기능입니다. 먼저 CLAUDE.md, settings.json, SKILLS를 능숙하게 다룬 후에 도입하세요.

상세 내용: 하네스(Harness) 기능 상세 해설에서 실전 패턴을 해설하고 있습니다.

11. MCP (Model Context Protocol): 외부 서비스 연동

11.1 MCP란

Claude Code가 외부 서비스와 연동하기 위한 프로토콜(Protocol)입니다.

예시:

• GitHub MCP: GitHub 리포지토리(Repository) 접근
• Filesystem MCP: 특정 디렉토리(Directory) 접근
• Slack MCP: Slack으로 메시지 전송

11.2 MCP 설정 예시

{
  "mcpServers": {
    "github": {
      ...
    }
  }
}

11.3 MCP 활용 사례

당신: 「GitHub의 issue #123을 확인해 줘」
Claude: GitHub MCP를 통해 issue를 가져옴
→ issue 내용을 표시
...

12. 기타 유용한 기능

12.1 Git 통합

당신: 「변경 사항을 커밋(Commit)해 줘」
Claude:
1. git status로 변경 사항 확인
...

12.2 프리뷰 및 실행

당신: 「웹 서버를 실행해 줘」
Claude: npm run dev (백그라운드 실행)
→ http://localhost:3000 에서 확인 가능

12.3 검색 및 탐색

당신: 「이 프로젝트에서 "authentication"이 사용된 곳을 모두 찾아줘」
Claude: grep 또는 Explore 에이전트(Agent)로 탐색

13. Claude Code 숙련을 위한 단계

Step 1: 초기 설정 (1일 차)

가장 먼저 이것부터 설정하세요:

• CLAUDE.md 작성

  • 프로젝트의 기술 스택 (Tech Stack)
  • 코딩 규약 (Coding Convention)
  • 자주 사용하는 명령어

• settings.json에서 권한 설정

  • 자주 사용하는 명령어 자동 허용
  • 매번 발생하는 승인 단계 생략

소요 시간: 30분~1시간

Step 2: 기본 조작 익히기 (1-2주)

• 파일 읽기 및 편집 요청
• 간단한 명령어 실행
• Git 커밋
• Memory 자동 학습

Step 3: 고급 기능 활용 (1개월)

• 자주 사용하는 태스크를 SKILLS에 등록
• Agent를 통한 복잡한 조사
• Plan mode로 대규모 변경 계획

상세: 하네스 (Harness) 기능 상세 해설

Step 4: 더욱 고급 기능 (2-3개월)

• HOOK을 통한 자동 체크 및 주의 환기
• MCP를 통한 외부 서비스 연동
• 정기적인 CLAUDE.md/Memory 유지보수

Step 5: 오케스트레이션 (Orchestration) 도구 검토 (필요 시)

여러 AI의 협업 동작이나 복잡한 워크플로우가 필요해지면, TAKT와 같은 오케스트레이션 도구를 검토합니다.

참고: AI 오케스트레이션 도구 선택 방법: TAKT 채택까지의 검토 프로세스

14. 자주 묻는 질문 (FAQ)

Q1. Claude Code는 무료로 사용할 수 있나요?

A. Claude Code는 무료로 사용할 수 있지만, 다음과 같은 플랜이 있습니다:

• Free: 제한 있음
• Pro: 월 $20 (토큰 제한 완화)
• Team: 팀용 플랜

Q2. 어느 파일까지 접근할 수 있나요?

A. 프로젝트 디렉토리 내의 파일에 접근할 수 있습니다. 설정에서 허용한 명령어만 실행 가능합니다.

Q3. 개인정보 보호는 안전한가요?

A. 로컬에서 실행되며, 명시적으로 전송하지 않는 한 코드는 Anthropic의 서버로 전송되지 않습니다. 설정에서 제어할 수 있습니다.

Q4. 다른 AI 도구와의 차이점은 무엇인가요?

• GitHub Copilot: 코드 완성 (Code Completion)에 특화
• Cursor: 에디터 통합
• Claude Code: 프로젝트 전체의 이해, 파일 조작, 명령어 실행에 강점

Q5. 팀에서 사용할 수 있나요?

A. 네. CLAUDE.md, SKILLS, settings.json을 Git으로 공유함으로써 팀 전체가 통일된 개발 경험을 실현할 수 있습니다.

15. 요약

Claude Code는 다기능 AI 개발 어시스턴트

• 기본 도구: Read, Edit, Write, Bash
• 초기 설정: CLAUDE.md, settings.json
• 고급 기능: Agent, Plan mode, 태스크 (Task) 관리
• 커스터마이징: Memory, SKILLS, HOOK
• 연동: MCP, Git 통합

우선 초기 설정부터 시작하세요

첫날에 CLAUDE.md와 settings.json을 설정하세요. 이것만으로도 Claude Code가 프로젝트를 이해하고 원활하게 작업할 수 있게 됩니다.

단계적으로 기능을 활용하세요

모든 기능을 한꺼번에 사용하려 하지 말고, 기본부터 시작하여 점진적으로 고급 기능을 활용해 나가세요.

다음 단계

더 자세히 배우기

오케스트레이션 도구 검토

시리즈 기사

• Claude Code 입문: 내장 기능의 전체 모습 (이 기사)
• Claude Code 하네스 기능 상세 해설: CLAUDE.md, SKILLS, HOOK으로 개발을 제어하기
• AI 오케스트레이션 도구 선택 방법: TAKT 채택까지의 검토 프로세스