AI 코딩 어시스턴트의 시대가 본격적으로 열렸어요. 그중에서도 클로드 코드(Claude Code)는 터미널에서 직접 동작하는 에이전틱 코딩 도구로, 기존 IDE 플러그인과는 다른 접근 방식을 취하고 있어요. 이 글에서는 클로드 코드를 처음 접하는 분들을 위해, 설치부터 핵심 설정까지 하나씩 짚어볼게요.
1. 클로드 코드 설치하기
클로드 코드는 운영체제별로 설치 방법이 조금씩 달라요. 아래 표를 참고하여 본인의 환경에 맞는 명령어를 실행해 주세요.
| 운영체제 | 설치 명령어 |
|---|---|
| macOS (Homebrew) | brew install --cask claude-code |
| macOS / Linux / WSL | curl -fsSL https://claude.ai/install.sh \| bash |
| Windows CMD | curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd |
macOS 사용자라면 두 가지 방법 중 하나를 선택할 수 있어요. Homebrew를 이미 사용 중이라면 brew 명령어가 업데이트와 관리가 편리하고, Homebrew가 없거나 Linux/WSL 환경이라면 curl 방식을 사용하면 돼요. 기능상 차이는 없으니 본인 환경에 맞는 방법을 선택하세요.
설치가 완료되면, 터미널에서 claude를 입력하여 실행할 수 있어요. 최초 실행 시에는 인증 과정을 거치게 되며, 화면의 안내에 따라 로그인하면 돼요.
만약 아마존 베드록(AWS Bedrock)이나 구글 클라우드 버텍스(Google Cloud Vertex)를 통해 클로드 코드를 사용하고 싶다면, 각 클라우드 제공사별로 별도의 설정이 필요해요. 공식 문서에서 해당 가이드를 확인할 수 있어요.
- AWS Bedrock 설정 가이드:
https://code.claude.com/docs/en/amazon-bedrock - Google Cloud Vertex 설정 가이드:
https://code.claude.com/docs/en/google-vertex-ai
클로드 코드의 설치는 일반적인 CLI 도구 설치와 크게 다르지 않아요. Node.js나 Python을 터미널에서 설치해 본 경험이 있다면, 거의 동일한 흐름이라고 보시면 돼요. 중요한 것은 “설치 후
claude한 번 실행해서 인증까지 마치는 것”이에요. 이 단계를 넘기면 바로 프로젝트에 사용할 수 있어요.
2. 프로젝트에 클로드 코드 적용하기
1) 프로젝트 디렉토리에서 클로드 시작하기
클로드 코드는 특정 프로젝트 폴더 안에서 실행할 때 가장 효과적으로 동작해요. 원하는 프로젝트 디렉토리로 이동한 뒤, 터미널에서 claude를 입력하면 해당 프로젝트의 맥락 안에서 대화를 시작할 수 있어요.
cd my-project
claude
이 상태에서 클로드에게 질문을 하거나 작업을 요청하면, 클로드는 현재 디렉토리의 파일들을 기반으로 답변을 생성해요. 하지만 프로젝트를 처음 시작할 때는 클로드가 코드베이스의 전체 구조를 아직 파악하지 못한 상태이기 때문에, 한 가지 중요한 초기화 작업이 필요해요.
2) /init 커맨드로 코드베이스 이해시키기
/init 커맨드는 클로드에게 “이 프로젝트 전체를 한 번 훑어보고 파악해 줘”라고 요청하는 것과 같아요. 이 명령어를 실행하면 클로드는 다음과 같은 정보를 분석해요.
- 프로젝트의 목적과 아키텍처
- 주요 명령어와 핵심 파일
- 코딩 패턴과 디렉토리 구조
# 클로드 실행 후
/init
분석이 끝나면 클로드는 그 결과를 CLAUDE.md라는 파일에 정리하여 저장해요. 이때 파일 생성 권한을 묻는 메시지가 나타나는데, Enter를 눌러 개별 승인하거나, Shift+Tab을 눌러 세션 동안 자유롭게 파일을 쓸 수 있도록 허용할 수 있어요.
/init은 새 팀원이 첫 출근했을 때 선임 개발자가 프로젝트 구조를 설명해 주는 온보딩 과정과 비슷해요. 이 과정을 거치지 않으면 클로드가 프로젝트의 맥락 없이 일반적인 답변만 하게 되므로, 새 프로젝트에서 클로드를 쓸 때는 반드시/init부터 실행하는 습관을 들이는 것이 좋아요.
3. CLAUDE.md 파일: 클로드를 위한 프로젝트 설명서
CLAUDE.md는 클로드 코드의 핵심 설정 파일이라고 할 수 있어요. 이 파일은 두 가지 역할을 해요.
- 프로젝트의 주요 명령어, 아키텍처, 코딩 스타일 등을 클로드에게 안내하는 가이드 역할
- 사용자가 원하는 특정 지시사항을 클로드에게 전달하는 커스텀 프롬프트 역할
중요한 점은, 이 파일의 내용이 클로드에게 보내는 모든 요청에 자동으로 포함된다는 것이에요. 즉, 매번 같은 맥락을 반복해서 설명할 필요 없이, CLAUDE.md에 한 번 적어두면 클로드가 항상 그 내용을 참고하게 돼요. 프로젝트 전용 시스템 프롬프트(System Prompt)라고 이해하시면 돼요.
1) 세 가지 CLAUDE.md 파일의 차이
클로드 코드는 용도에 따라 세 가지 위치의 CLAUDE.md 파일을 인식해요. 각각의 파일은 공유 범위와 적용 대상이 다르므로, 상황에 맞게 사용하는 것이 좋아요.
| 파일 | 위치 | 공유 여부 | 적용 범위 | 대표 용도 |
|---|---|---|---|---|
CLAUDE.md |
프로젝트 루트 | Git에 커밋하여 팀 전체 공유 | 해당 프로젝트 | 빌드 명령어, 아키텍처 설명, 코딩 컨벤션 |
CLAUDE.local.md |
프로젝트 루트 | 공유되지 않음 (개인용) | 해당 프로젝트 | 개인 워크플로우, 실험적 지시사항 |
~/.claude/CLAUDE.md |
홈 디렉토리 | 공유되지 않음 (개인용) | 기기 내 모든 프로젝트 | 선호하는 코딩 스타일, 공통 규칙 |
이 구조를 실제 업무에 비유하면 이렇게 생각할 수 있어요.
CLAUDE.md는 팀 위키에 올라가는 프로젝트 개발 가이드입니다. 모든 팀원(그리고 클로드)이 같은 규칙을 따르도록 하는 공식 문서예요.CLAUDE.local.md는 본인 모니터에 붙여놓는 개인 메모입니다. “나는 이 프로젝트에서 이렇게 작업한다”라는 개인 선호를 적어두는 공간이에요.~/.claude/CLAUDE.md는 어떤 프로젝트를 열든 항상 적용되는 나만의 작업 원칙입니다. 예를 들어, “모든 코드에서 한국어 주석을 사용해줘”처럼 프로젝트와 무관하게 항상 지키고 싶은 규칙을 여기에 적어둘 수 있어요.
세 가지
CLAUDE.md파일은 회사의 문서 체계와 비슷해요. 전사 공통 규칙(홈 디렉토리), 팀 규칙(프로젝트 CLAUDE.md), 그리고 내 개인 업무 노트(CLAUDE.local.md)가 각각 존재하는 셈이에요. 이 계층 구조 덕분에, 팀과 공유해야 할 규칙과 개인적으로만 적용할 규칙을 깔끔하게 분리할 수 있어요.
2) # 기호로 지시사항 추가하기 (메모리 모드)
CLAUDE.md 파일을 직접 열어 편집할 수도 있지만, 더 간편한 방법이 있어요. 클로드가 활성화된 터미널에서 # 기호를 입력하면 ‘메모리 모드(Memory Mode)’가 활성화돼요. 이 모드에서 작성한 내용은 CLAUDE.md 파일에 자동으로 병합돼요.
# 주석은 최소한으로 사용하고, 복잡한 로직에만 주석을 달아줘
위처럼 입력하면 클로드가 해당 지시 사항의 핵심 내용을 간추려 CLAUDE.md에 적절히 추가해 줘요. 이 방법은 클로드가 반복적으로 같은 실수를 할 때 특히 유용할 수 있어요. 예를 들어, 클로드가 코드에 불필요하게 많은 주석을 다는 습관이 있다면, 위와 같이 메모리에 등록해 두면 이후 대화에서도 해당 규칙을 지키게 돼요.
3) @ 기호로 특정 파일 참조하기
클로드에게 특정 파일의 내용을 직접 보여주고 싶을 때는 @ 기호를 사용해요. @ 뒤에 파일 경로를 입력하면, 해당 파일의 내용이 요청에 자동으로 포함돼요.
이 프로젝트의 인증 흐름을 설명해줘 @src/auth
위와 같이 입력하면, 클로드는 src/auth 경로와 관련된 파일 목록을 보여주고, 선택한 파일의 내용을 대화 맥락에 포함시켜요.
이 기능은 CLAUDE.md 파일 안에서도 활용할 수 있어요. 프로젝트의 여러 작업에서 공통적으로 참조해야 하는 파일이 있다면, CLAUDE.md에 아래와 같이 적어둘 수 있어요.
데이터베이스 구조는 @prisma/schema.prisma 파일에 정의되어 있어요.
데이터 구조에 대한 질문이 있을 때 이 파일을 참고하세요.
이렇게 설정해 두면, 클로드가 매 요청마다 해당 파일의 내용을 자동으로 참조하게 돼요. 데이터베이스 스키마처럼 프로젝트 전반에 걸쳐 자주 참조되는 파일에 특히 유용한 방법이에요.
#은 클로드에게 “이건 앞으로 계속 기억해”라고 말하는 것이고,@는 “이 파일을 지금 당장 보고 참고해”라고 말하는 것이에요. 하나는 장기 기억, 다른 하나는 즉각적인 참조라고 생각하면 구분이 쉬워요. 두 기능을 잘 조합하면, 매번 같은 설명을 반복하지 않아도 클로드가 프로젝트를 깊이 이해한 상태에서 작업할 수 있게 돼요.
4) 주의사항
~/.claude/agents/ 디렉토리 안에 README.md 파일이 존재하면, 클로드 코드가 이를 에이전트 정의 파일로 인식하면서 아래와 같은 에러가 발생할 수 있어요.
Error: Agent file is missing required frontmatter field: name
이 경로에 있는 .md 파일은 CLAUDE.md와 달리 에이전트 파일로 취급되며, name 필드가 포함된 프론트매터(frontmatter)가 반드시 있어야 해요. README.md처럼 설명용으로 넣어둔 파일도 예외가 아니에요.
해결 방법은 두 가지예요.
~/.claude/agents/경로에서README.md를 삭제하거나 다른 경로로 옮기기- 또는 파일 상단에 유효한 프론트매터를 추가하기
~/.claude/agents/디렉토리는 에이전트 정의 파일만 두는 공간으로 관리하는 것이 좋아요. 메모나 설명이 필요하다면 해당 내용은CLAUDE.md에 작성하는 것을 권장해요.
4. 스크린샷으로 정확하게 소통하기
코드만으로 설명하기 어려운 UI 관련 요청이 있을 때, 스크린샷은 매우 효과적인 소통 수단이 돼요. 예를 들어, “이 버튼의 위치를 오른쪽으로 옮겨줘”라고 텍스트로 설명하는 것보다, 해당 화면을 캡처해서 보여주는 것이 훨씬 빠르고 정확해요.
클로드 코드 터미널에서 스크린샷을 붙여넣는 방법은 운영체제에 따라 달라요.
| 운영체제 | 스크린샷 찍기 단축키 |
|---|---|
| macOS | Cmd + Shift + 4 (영역 선택) / Cmd + Shift + 3 (전체 화면) |
| Windows | Win + Shift + S (영역 선택) / Print Screen (전체 화면) |
| Linux | Print Screen / Shift + Print Screen (영역 선택) |
스크린샷 활용은 디자이너가 개발자에게 수정 사항을 전달할 때 Figma 화면에 직접 코멘트를 다는 것과 비슷해요. “헤더 영역의 여백이 너무 넓어요”라고 말로만 전달하면 해석이 달라질 수 있지만, 화면을 직접 보여주면 오해의 여지가 크게 줄어들어요. 특히 프론트엔드 작업에서 스크린샷은 텍스트 설명 수십 줄을 대체할 수 있는 강력한 도구예요.
5. 사전 계획 기능 (플래닝 모드, Planning Mode)
1) 사전 계획 기능(플래닝 모드, Planning Mode)이란?
단순한 코드 수정이라면 클로드에게 바로 요청해도 충분하지만, 여러 파일에 걸쳐 변경이 필요하거나 아키텍처 수준의 판단이 필요한 복잡한 작업에서는 클로드가 먼저 충분히 조사하고 계획을 세우는 것이 더 효과적일 수 있어요.
사전 계획 기능은 바로 이런 상황을 위한 기능이에요. 이 모드를 활성화하면 클로드는 코드를 바로 수정하지 않고, 다음과 같은 과정을 먼저 거쳐요.
- 프로젝트 내의 관련 파일들을 폭넓게 탐색
- 변경 사항에 대한 상세한 구현 계획을 수립
- 사용자에게 계획을 제시하고 승인을 대기
- 승인을 받은 후에만 실제 코드 변경을 실행
2) 활성화 방법
사전 계획 기능(플래닝 모드)은 Shift + Tab을 눌러 활성화할 수 있어요.
| 현재 상태 | 키 입력 | 결과 |
|---|---|---|
| 일반 모드 | Shift + Tab 2회 |
Planning Mode 활성화 |
| 자동 승인 모드 (Auto-accept) | Shift + Tab 1회 |
Planning Mode 활성화 |
사전 계획 기능(플래닝 모드)이 활성화되면 프롬프트 영역에 해당 모드가 켜져 있다는 표시가 나타나므로, 현재 상태를 쉽게 확인할 수 있어요.
3) 언제 사용하면 좋을까?
사전 계획 기능(플래닝 모드)은 다음과 같은 상황에서 특히 효과적이에요.
- 코드베이스 전반에 대한 폭넓은 이해가 필요한 작업
- 여러 파일이나 컴포넌트에 걸친 변경이 필요한 경우
- 리팩토링처럼 기존 구조를 크게 바꾸는 작업
- 클로드가 놓칠 수 있는 엣지 케이스(Edge Case)를 사전에 확인하고 싶은 경우
사전 계획 기능(플래닝 모드)은 건축에서 설계도를 먼저 그리는 것과 같아요. 작은 선반을 만들 때는 바로 못을 박아도 되지만, 집 전체의 배관을 교체하려면 도면을 먼저 검토해야 하는 것과 같은 이치예요. 복잡한 작업일수록 “계획 먼저, 실행 나중”이라는 원칙이 AI 코딩에서도 유효해요.
6. 추론 수준 설정 (Thinking Modes)
1) 추론 수준 설정(띵킹 모드, Thinking Modes)이란?
추론 수준 설정(띵킹 모드)은 클로드가 문제를 풀 때 얼마나 깊이 생각할지를 조절하는 기능이에요. 모드에 따라 클로드에게 할당되는 추론 토큰(Reasoning Token)의 양이 달라지며, 더 높은 단계를 선택할수록 더 정교한 분석과 추론이 가능해져요.
2) 5가지 추론 단계
| 단계 | 모드 이름 | 추론 깊이 | 적합한 작업 |
|---|---|---|---|
| 1 | Think | 기본 추론 | 단순 질문, 간단한 코드 수정 |
| 2 | Think more | 확장 추론 | 중간 난이도의 로직 구현 |
| 3 | Think a lot | 심층 추론 | 복잡한 비즈니스 로직, 설계 판단 |
| 4 | Think longer | 장시간 추론 | 난이도 높은 디버깅, 최적화 |
| 5 | Ultrathink | 최대 추론 | 알고리즘 설계, 아키텍처 수준의 의사결정 |
단계가 올라갈수록 클로드가 더 많은 토큰을 사용하여 생각하기 때문에, 응답 시간이 길어지고 비용도 높아질 수 있어요. 따라서 모든 작업에 최대 단계를 사용하기보다는, 작업의 복잡도에 맞게 적절한 단계를 선택하는 것이 효율적이에요.
3) 사전 계획 기능(플래닝 모드)와 추론 수준 설정(띵킹 모드)의 차이
두 기능은 이름만 들으면 비슷해 보이지만, 해결하려는 문제의 성격이 달라요.
| 구분 | 사전 계획 기능(플래닝 모드) | 추론 수준 설정(띵킹 모드) |
|---|---|---|
| 초점 | 넓이 (프로젝트 전반 탐색) | 깊이 (단일 문제에 대한 추론) |
| 적합한 상황 | 여러 파일에 걸친 대규모 변경 | 복잡한 로직, 어려운 버그 |
| 비유 | 지도를 펼쳐놓고 전체 경로를 계획하는 것 | 한 지점에서 깊이 파고드는 것 |
물론 두 기능을 함께 사용할 수도 있어요. 프로젝트 전반을 파악한 뒤(Planning Mode), 특정 복잡한 로직에 대해 깊이 있는 추론(Thinking Modes)을 요청하는 방식으로 조합하면 가장 효과적이에요. 다만, 두 기능 모두 추가 토큰을 소비하므로 비용을 고려하여 사용하는 것이 좋아요.
추론 수준 설정(띵킹 모드)은 시험 문제를 풀 때의 전략과 비슷해요. 객관식 상식 문제에는 빠르게 답을 고르면 되지만, 서술형 증명 문제에는 연습장에 풀이 과정을 충분히 적어가며 풀어야 정확도가 올라가는 것처럼요. 클로드에게도 “이 문제는 연습장을 많이 써도 돼”라고 허용해 주는 것이 추론 수준 설정의 역할이에요.
7. 수행 중단 및 대화 되감기
1) Esc 한 번: 현재 작업 중단
클로드가 잘못된 방향으로 작업을 진행하고 있거나, 요청과 다른 작업을 시작했을 때는 Esc 키를 한 번 눌러 즉시 중단시킬 수 있어요.
이 기능은 클로드가 여러 작업을 한꺼번에 처리하려 할 때 특히 유용해요. 예를 들어, 하나의 함수에 대한 테스트만 요청했는데 클로드가 전체 모듈의 테스트 계획을 세우기 시작한다면, Esc를 눌러 멈춘 후 범위를 좁혀서 다시 요청할 수 있어요.
또한 Esc로 중단한 직후 # 기호를 활용하여 메모리에 올바른 접근법을 등록해 두면, 같은 실수가 반복되는 것을 방지할 수 있어요.
Esc (중단) → # 테스트는 한 번에 하나의 함수만 작성해줘
2) Esc 두 번: 이전 대화 시점으로 되감기
대화가 길어지면 중간에 쌓인 디버깅 기록이나 실패한 시도들이 맥락을 오히려 방해할 수 있어요. 이때 Esc를 두 번 연속으로 누르면, 이전에 보냈던 메시지 목록이 표시되고, 원하는 시점으로 대화를 되돌릴 수 있어요.
이 기능으로 할 수 있는 것들은 다음과 같아요.
- 클로드가 프로젝트에 대해 학습한 유용한 맥락은 유지
- 불필요하거나 혼란을 주는 대화 이력은 제거
- 특정 시점부터 다른 방향으로 작업을 재시작
Esc한 번은 “잠깐, 멈춰봐”이고,Esc두 번은 “아까 그 시점으로 돌아가자”이에요. 문서 작업에서Ctrl + Z(실행 취소)와 비슷한 개념이라고 생각하면 돼요. 특히 긴 대화에서 방향이 꼬였을 때, 처음부터 다시 시작하지 않고 유용한 맥락은 살린 채 특정 지점으로 돌아갈 수 있다는 점이 핵심이에요.
8. 대화 맥락 관리 명령어
마지막으로, 대화가 길어졌을 때 맥락을 효율적으로 관리할 수 있는 두 가지 보조 명령어를 알아두면 좋아요.
1) /compact: 대화 요약하기
/compact 명령어는 지금까지의 대화 내용을 요약하여, 핵심 정보만 남긴 상태로 대화를 이어갈 수 있게 해줘요. 클로드가 프로젝트에 대해 많은 것을 학습한 상태에서 관련된 다음 작업으로 넘어갈 때 유용해요.
2) /clear: 대화 초기화
/clear 명령어는 대화 이력을 완전히 삭제하고 백지 상태에서 다시 시작해요. 이전 작업과 전혀 관련 없는 새로운 작업을 시작할 때 적합해요.
| 명령어 | 동작 | 적합한 상황 |
|---|---|---|
/compact |
대화를 요약하고 핵심 맥락만 유지 | 관련 작업을 이어서 할 때 |
/clear |
대화 이력 완전 삭제 | 완전히 새로운 작업을 시작할 때 |
/compact는 회의록을 정리하는 것이고,/clear는 화이트보드를 깨끗이 지우는 것이에요. 둘 다 “대화가 길어져서 클로드가 집중하지 못하는 것 같다”고 느낄 때 꺼내 쓸 수 있는 도구예요. 이전 맥락이 도움이 되는 상황이라면/compact를, 오히려 방해가 되는 상황이라면/clear를 선택하면 돼요.
마무리
지금까지 클로드 코드의 설치부터 핵심 설정, 그리고 일상적으로 사용하게 될 주요 기능들을 살펴보았어요. 정리하면 다음과 같아요.
| 단계 | 핵심 내용 |
|---|---|
| 설치 | OS별 명령어로 설치 후 claude 실행 및 인증 |
| 프로젝트 적용 | 프로젝트 디렉토리에서 /init으로 코드베이스 파악 |
| CLAUDE.md | 세 가지 파일로 팀 규칙 / 개인 설정 / 글로벌 설정 관리 |
| 소통 도구 | #(메모리), @(파일 참조), 스크린샷으로 정확한 지시 |
| 작업 모드 | Planning Mode(넓은 탐색), Thinking Modes(깊은 추론) |
| 흐름 제어 | Esc(중단/되감기), /compact(요약), /clear(초기화) |
클로드 코드는 단순히 코드를 대신 작성해 주는 도구가 아니라, 프로젝트의 맥락을 이해하고 함께 작업하는 개발 파트너에 가까워요. 오늘 소개한 설정들을 잘 활용하면, 클로드가 여러분의 프로젝트를 더 깊이 이해한 상태에서 더 정확한 결과물을 만들어낼 수 있을 거예요.
클로드 코드 시리즈