Claude Code 기본 사용법: 첫 대화부터 코드 수정까지

Claude Code 기본 사용법: 첫 대화부터 코드 수정까지

설치는 끝났는데 뭘 어떻게 써야 할지 모르겠다면, 이 글이 답입니다. 프로젝트 탐색, 파일 편집, 명령어 실행, 권한 승인, 세션 관리, 키보드 단축키까지 Claude Code의 기본 사용법을 실전 예시와 함께 완전정리합니다.

Claude Code 기본 사용법

---

1. 세션 시작하기

기본 실행

cd /path/to/your/project
claude

Claude Code는 현재 디렉토리의 프로젝트를 기준으로 동작합니다. 반드시 작업할 프로젝트 폴더에서 실행하세요.

실행 옵션

명령	설명
claude	새 대화형 세션 시작
claude "할 일"	초기 프롬프트와 함께 시작
claude -p "질문"	원샷 모드 (답변 후 바로 종료)
claude -c	가장 최근 세션 이어서 작업
claude --resume	세션 목록에서 선택해서 재개
claude --resume auth-fix	이름으로 세션 재개

시작 화면

실행하면 환영 화면이 나타나며:

• 최근 대화 목록 표시
• 최근 Git 작업 기반의 자동 제안 프롬프트(회색)가 표시됨
• Tab을 누르면 제안 수락, 그냥 타이핑하면 무시

세션 시작하기

---

2. 효과적인 프롬프트 작성법

좋은 프롬프트 vs 나쁜 프롬프트

나쁜 예	좋은 예
"버그 고쳐줘"	"로그인 시 잘못된 비밀번호 입력하면 빈 화면이 나오는 버그 고쳐줘"
"기능 추가해줘"	"사용자 프로필 편집 API를 인증, 유효성 검사 포함해서 만들어줘"
"코드 개선해줘"	"UserService 클래스를 async/await으로 리팩토링해줘"

프롬프트 작성 5원칙

원칙	설명
구체적으로	무엇을, 어디서, 어떻게 원하는지 명확히
단계별로	복잡한 작업은 "1. ... 2. ... 3. ..."으로 분리
탐색 먼저	바로 수정하지 말고 "먼저 분석해줘" 후 구현 요청
검증 포함	"테스트 돌려서 확인해줘"를 포함
컨텍스트 제공	에러 메시지, 스택 트레이스, 기대 결과를 함께 전달

여러 줄 입력 방법

방법	단축키	지원 환경
백슬래시	\ + Enter	모든 터미널
Option+Enter	Option+Enter	macOS 기본
Shift+Enter	Shift+Enter	iTerm2, WezTerm, Ghostty, Kitty
Ctrl+J	Ctrl+J	모든 터미널
붙여넣기	직접 붙여넣기	코드 블록, 로그 등

VS Code, Alacritty 등에서 Shift+Enter가 안 되면 /terminal-setup 명령을 실행하세요.

@멘션으로 컨텍스트 지정

@를 입력하면 파일 경로 자동완성이 시작됩니다.

@src/utils/auth.js 이 파일의 로직 설명해줘

@src/components 이 폴더의 구조 알려줘

@package.json 과 @tsconfig.json 확인해서 설정 문제 찾아줘

효과적인 프롬프트 작성법

---

3. 파일 읽기 & 코드베이스 탐색

Claude Code는 요청에 따라 필요한 파일을 자동으로 찾아 읽습니다. 직접 파일을 열어줄 필요 없습니다.

Claude가 코드를 탐색하는 과정

단계	도구	설명
1	Glob	파일 이름 패턴으로 검색 (예: **/*.ts)
2	Grep	파일 내용에서 텍스트/정규식 검색
3	Read	찾은 파일의 내용을 읽기

탐색 요청 예시

요청	Claude의 동작
"이 프로젝트가 뭘 하는 거야?"	package.json, README, 메인 파일 분석
"인증 로직이 어디에 있어?"	auth, login 키워드로 Grep 검색
"폴더 구조 설명해줘"	Glob으로 전체 구조 파악
"이 함수 호출하는 곳 찾아줘"	Grep으로 함수명 검색

팁: "먼저 코드를 분석해줘" → "그다음 수정해줘" 순서로 요청하면 더 정확한 결과를 얻을 수 있습니다.

파일 읽기 & 코드베이스 탐색

---

4. 파일 편집 & 새 파일 생성

편집 과정

Claude Code가 파일을 수정할 때의 흐름입니다.

단계	내용
1	Claude가 변경사항을 diff 형태로 제안
2	추가된 줄(초록), 삭제된 줄(빨강)이 하이라이트로 표시
3	사용자가 승인(Y) 또는 거부(N) 선택
4	승인하면 파일에 자동 적용

승인/거부 옵션

키	동작
Y (또는 Enter)	이 변경만 승인
A	이번 세션에서 모든 편집 자동 승인
N (또는 Esc)	이 변경 거부

편집 도구 종류

도구	용도
Edit	기존 파일 수정 (줄 단위 변경)
Write	새 파일 생성 (전체 내용 작성)

실전 예시: 유효성 검사 추가

> 회원가입 폼에 이메일 유효성 검사 추가해줘

Claude의 응답:

// src/forms/RegisterForm.tsx

+ function validateEmail(email: string): boolean {
+   return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+ }

  function handleSubmit(data: FormData) {
+   if (!validateEmail(data.email)) {
+     setError("올바른 이메일을 입력하세요");
+     return;
+   }
    // 기존 코드...
  }

→ Y를 누르면 파일에 즉시 적용됩니다.

파일 편집 & 새 파일 생성

---

5. 명령어 실행

Claude가 명령어를 실행하는 방식

Claude Code는 Bash 도구를 사용해 터미널 명령어를 직접 실행합니다.

> 테스트 돌려봐

→ Claude가 npm test (또는 프로젝트의 테스트 러너)를 실행

명령어 실행 시 권한

상황	동작
처음 실행하는 명령	승인 다이얼로그 표시
"항상 허용" 선택한 명령	자동 실행
settings.json에 등록된 명령	자동 실행

Bash 모드: 직접 실행

프롬프트에 !를 붙이면 Claude를 거치지 않고 직접 명령어를 실행합니다.

! npm test
! git status
! ls -la

• 명령어와 출력이 대화 컨텍스트에 추가됨
• Claude가 이 결과를 참고해서 다음 작업 수행 가능
• Esc 또는 Backspace로 Bash 모드 종료

백그라운드 실행

긴 작업은 Ctrl+B로 백그라운드에서 실행할 수 있습니다.

용도	예시
빌드	webpack, vite, make
테스트	jest, pytest
개발 서버	npm start, flask run
패키지 설치	npm install

명령어 실행

---

6. 권한 시스템 이해하기

권한 등급

도구 유형	예시	승인 필요
읽기 전용	파일 읽기, 검색	불필요 (자동)
Bash 명령	셸 명령 실행	필요 (영구 저장 가능)
파일 수정	편집, 새 파일 생성	필요 (세션 내 저장)

권한 모드 3가지

Shift+Tab으로 모드를 순환할 수 있습니다.

모드	동작	추천 상황
Normal (기본)	모든 수정/명령에 승인 요청	처음 사용, 민감한 작업
Auto-Accept	파일 편집 자동 승인, 명령은 승인	익숙해진 후
Plan	읽기만 가능, 수정 불가	코드 분석, 설계 단계

settings.json으로 권한 미리 설정

{
  "permissions": {
    "allow": [
      "Bash(npm test)",
      "Bash(npm run build)",
      "Bash(git status)"
    ],
    "deny": [
      "Bash(rm -rf *)"
    ]
  }
}

권한 규칙 우선순위

순위	레벨	설명
1	deny	거부 규칙이 항상 최우선
2	ask	매번 확인
3	allow	자동 허용

deny에 등록된 명령은 어떤 레벨에서도 허용할 수 없습니다. 위험한 명령어는 deny에 넣어두면 안전합니다.

권한 시스템 이해하기

---

7. 키보드 단축키 총정리

기본 조작

단축키	기능
Enter	메시지 전송
Ctrl+C	현재 입력/생성 취소
Ctrl+D	세션 종료
Esc	현재 입력 취소
?	키보드 단축키 도움말
/	슬래시 커맨드 시작
!	Bash 모드 진입

탐색 & 편집

단축키	기능
위/아래 화살표	이전 명령 탐색
Ctrl+R	명령 히스토리 검색
Tab	자동완성 수락
Ctrl+K	커서 뒤 삭제
Ctrl+U	전체 줄 삭제
Alt+B / Alt+F	단어 단위 커서 이동

모드 & 기능

단축키	기능
Shift+Tab	권한 모드 순환 (Normal → Auto → Plan)
Ctrl+L	터미널 화면 클리어 (대화는 유지)
Ctrl+O	상세 출력 토글
Ctrl+B	실행 중인 작업 백그라운드로
Ctrl+T	백그라운드 작업 목록
Ctrl+G	외부 에디터에서 프롬프트 편집
Alt+P	모델 전환
Alt+T	Extended Thinking 토글
Esc+Esc	되감기 (코드/대화를 이전 상태로)

권한 다이얼로그

단축키	기능
Y / Enter	승인
A	항상 허용
N / Esc	거부

 

키보드 단축키

---

8. 컨텍스트 관리

컨텍스트란?

Claude Code의 컨텍스트 윈도우(최대 200K 토큰)에는 대화 기록, 읽은 파일, 명령어 출력, CLAUDE.md 등이 쌓입니다. 이 용량이 차면 Claude의 성능이 떨어집니다.

컨텍스트 확인

/context

컬러 격자로 현재 사용량을 시각화해서 보여줍니다.

컨텍스트 관리 명령

명령	기능	언제 사용
/compact	대화를 요약하여 컨텍스트 확보	대화가 길어졌을 때
/compact API 변경에 집중	특정 주제에 집중하여 요약	핵심만 유지하고 싶을 때
/clear	대화 전체 초기화	완전히 새로 시작할 때

컨텍스트 절약 팁

방법	효과
CLAUDE.md에 지침 저장	매번 설명할 필요 없음
서브에이전트 활용	탐색 결과를 별도 컨텍스트에서 처리
/compact 자주 사용	불필요한 기록 정리
필요 없는 MCP 서버 제거	도구 정의가 컨텍스트를 차지함

중요: 긴 세션에서 처음에 말한 지침을 Claude가 잊는 것 같다면, CLAUDE.md에 해당 지침을 넣으세요. CLAUDE.md는 매 세션마다 자동으로 로드됩니다.

컨텍스트 관리

---

9. 세션 관리

세션 이름 지정

/rename auth-refactor

이름을 지정하면 나중에 쉽게 찾아서 재개할 수 있습니다.

세션 재개

방법	명령
가장 최근 세션	claude -c 또는 claude --continue
세션 목록에서 선택	claude --resume 또는 /resume
이름으로 재개	claude --resume auth-refactor
PR에 연결된 세션	claude --from-pr 123

세션 선택기 단축키

키	기능
↑/↓	세션 탐색
Enter	선택 & 재개
P	미리보기
R	이름 변경
/	검색
A	전체 프로젝트/현재 디렉토리 전환
B	현재 Git 브랜치 필터

세션 분기 (Fork)

claude --continue --fork-session

현재까지의 대화를 유지하면서 새로운 세션을 만듭니다. 원본 세션은 그대로 유지됩니다.

세션 관리

---

10. 실전 워크플로우 5가지

실전 1: 프로젝트 탐색

> 이 프로젝트가 뭘 하는 거야?
> 어떤 기술 스택을 사용해?
> 폴더 구조 설명해줘
> 인증 로직은 어디에 있어?

Claude가 Glob → Grep → Read를 자동 수행하며 프로젝트를 분석합니다.

실전 2: 코드 수정

> 회원가입 폼에 이메일 유효성 검사 추가해줘

Claude가 관련 파일을 찾고 → diff를 보여주고 → 승인하면 적용

실전 3: 테스트 실행 & 수정

> 테스트 돌려봐

실패하면:

> 실패한 테스트 고쳐줘

Claude가 에러 분석 → 수정 → 재실행까지 자동 수행

실전 4: Git 커밋

> 변경사항 커밋해줘

Claude가 git diff 확인 → 커밋 메시지 작성 → 승인 후 커밋

실전 5: 버그 수정

> TypeError: Cannot read property 'id' of undefined 에러가 나와.
> src/utils/getUserData.js에서 발생해

Claude가 파일 분석 → null 체크 추가 → 테스트 작성까지

 

실전 워크플로우 5가지

---

11. 자주 쓰는 슬래시 커맨드

커맨드	기능	사용 시점
/help	도움말	기능을 모를 때
/init	CLAUDE.md 생성	프로젝트 첫 설정
/model	모델 변경	Opus/Sonnet/Haiku 전환
/config	설정	권한, 모드 변경
/cost	비용 확인	토큰 사용량 체크
/compact	대화 요약	컨텍스트 부족할 때
/clear	대화 초기화	새로 시작할 때
/context	컨텍스트 사용량	느려졌을 때 확인
/diff	변경사항 보기	커밋 전 확인
/resume	세션 재개	이전 작업 이어서
/rename	세션 이름 지정	나중에 찾기 쉽게
/fast on	빠른 모드	속도 우선
/permissions	권한 확인	현재 설정 보기

자주 쓰는 슬래시 커맨드

---

마무리

Claude Code의 기본 사용법을 정리하면:

1. 세션 시작: 프로젝트 폴더에서 claude 실행
2. 자연어로 요청: 구체적으로, 단계별로
3. 파일 편집: diff를 확인하고 Y/N으로 승인
4. 명령어 실행: 권한 승인 후 자동 실행
5. 컨텍스트 관리: /compact로 요약, CLAUDE.md에 지침 저장
6. 세션 관리: /rename으로 이름 지정, claude -c로 재개

이것만 알면 Claude Code를 바로 업무에 활용할 수 있습니다. 다음 편에서는 슬래시 커맨드 전체를 상세히 다룹니다.

---

이전 글: [2편] Claude Code 설치 & 초기 설정 가이드
다음 글: [4편] 슬래시 커맨드 완전정리

---

면책 조항: 본 글은 교육 목적의 정보 제공용이며, Claude Code의 기능 및 요금제는 Anthropic의 정책에 따라 변경될 수 있습니다. 최신 정보는 공식 문서(docs.anthropic.com)를 참고하세요.