19장. Claude Code 시작하기

지난 장에서는 AI와 협업할 때의 안전한 습관을 배웠습니다. 이제부터는 그 습관을 실제 도구 위에 올려볼 차례입니다. 4부의 첫 주자는 Claude Code입니다.

처음 이름을 들으면 뭔가 대단하고 어려운 도구처럼 느껴질 수 있습니다. 터미널에서 돌아가고, 파일도 읽고, 코드를 고치고, 명령도 실행한다니 괜히 겁부터 날 수 있습니다. 하지만 첫인상만 넘기면 의외로 감각은 단순합니다.

말로 설명하면, Claude Code가 프로젝트를 읽고 함께 일해 주는 방식입니다.

초보자에게 중요한 것은 모든 기능을 외우는 일이 아닙니다. 어떻게 켜고, 어떻게 물어보고, 어떤 흐름으로 검토하면 되는지 그 기본 리듬을 몸에 익히는 일입니다. 이 장에서는 바로 그 첫 리듬을 잡아보겠습니다.

Claude Code를 한 문장으로 이해하기

Claude Code는 터미널에서 실행되는 AI 코딩 도구입니다. 단순히 질문에 답만 하는 채팅창이 아니라, 프로젝트 폴더 안의 파일을 읽고, 관련 코드를 찾고, 여러 파일을 함께 수정하고, 필요한 명령을 실행하는 식으로 실제 작업 흐름에 들어옵니다.¹

이 차이는 생각보다 큽니다.

보통의 채팅형 AI는 여러분이 코드 조각을 복사해서 붙여 넣어야 맥락을 이해합니다. 하지만 Claude Code는 현재 프로젝트를 직접 살펴보며 "어느 파일을 봐야 하는지", "어디를 고쳐야 하는지", "수정 뒤 무엇을 확인해야 하는지"까지 이어서 도와줄 수 있습니다.¹²

쉽게 비유하면 이렇습니다.

브라우저 속 AI가 "설명 잘하는 상담원"에 가깝다면, Claude Code는 프로젝트 작업실 안으로 들어온 조수에 가깝습니다. 같은 AI라도 일하는 방식이 훨씬 실무적입니다.

초보자가 Claude Code를 좋아하게 되는 이유

초보자는 보통 코딩 도구를 두려워합니다. 어디를 눌러야 할지 모르고, 뭔가 잘못 건드리면 큰일이 날 것 같기 때문입니다. Claude Code가 입문자에게 특히 좋은 이유는, 많은 작업을 자연어로 시작할 수 있기 때문입니다.

예를 들어 여러분은 이렇게 말할 수 있습니다.

"이 프로젝트가 무엇을 하는지 설명해줘."

"회원가입 관련 파일을 찾아줘."

"로그인 버튼 문구만 바꿔줘."

"이 에러의 원인을 찾고, 수정 전 계획부터 보여줘."

이런 식의 요청은 초보자에게 아주 중요합니다. 왜냐하면 처음부터 정답 명령어를 외우지 않아도 되기 때문입니다. Claude Code는 낯선 프로젝트를 탐색하고, 관련 파일을 찾고, 버그를 추적하고, 테스트를 만들고, 리팩터링 계획을 세우는 공통 작업 흐름을 지원합니다.¹

또 하나 큰 장점이 있습니다. 기본적으로 파일 수정이나 명령 실행 전에 확인을 받는 구조라서, 무작정 질주하기보다 검토하면서 같이 가는 느낌이 강합니다.³ 초보자에게는 이 점이 특히 든든합니다. 너무 똑똑한 도구보다, 너무 빨리 망치지 않는 도구가 더 오래 갑니다.

첫 실행에서 느껴야 할 감각

Claude Code를 처음 켰을 때 가장 먼저 해야 할 일은 "엄청난 기능 구현"이 아닙니다. 오히려 아주 소박한 첫 질문이 좋습니다.

프로젝트 폴더에서 Claude Code를 실행한 뒤, 먼저 현재 프로젝트를 설명해 달라고 해보세요. Builder의 입문 가이드도 초반에는 코드베이스를 탐색하는 질문부터 시작하라고 권합니다.³

예를 들면 이런 식입니다.

• 이 프로젝트가 무엇을 하는지 쉬운 말로 설명해줘.

• 주요 폴더와 역할을 알려줘.

• 로그인과 관련된 파일이 어디에 있는지 찾아줘.

• 지금 내가 초보자라면 어디부터 읽어야 하는지 추천해줘.

이 단계의 목적은 코드를 바꾸는 것이 아닙니다. 프로젝트를 무서운 검은 상자에서, 이름이 붙은 방들의 집으로 바꾸는 것입니다.

처음 보는 집에 들어가면 거실이 어디고, 부엌이 어디고, 화장실이 어디인지부터 알아야 덜 헤매죠. 코드베이스도 같습니다. Claude Code는 그 집을 함께 둘러보는 안내자 역할을 꽤 잘합니다.¹

Claude Code가 잘하는 기본 작업

Claude Code는 처음부터 거대한 기능 구현보다, 다음 같은 기본 작업에서 진가가 잘 드러납니다.

• 낯선 프로젝트 구조를 빠르게 요약하기

• 특정 기능과 관련된 파일 찾기

• 에러 메시지의 원인 추적하기

• 기존 패턴을 따라 작은 수정 적용하기

• 테스트 실행이나 문서 정리 같은 반복 작업 돕기¹

여기서 중요한 포인트는 "작지만 실제적인 작업"입니다. 초보자라면 첫 승리를 크게 잡지 않는 편이 좋습니다. 홈 화면 제목 바꾸기, 버튼 스타일 정리하기, 목록 데이터가 어디서 오는지 찾기, 폼 입력 검증 하나 붙이기 같은 일이 훨씬 좋습니다.

왜냐하면 Claude Code의 진짜 매력은 한 번에 세상을 바꾸는 데 있지 않고, 작업의 마찰을 줄여주는 데 있기 때문입니다.

가장 먼저 익혀야 할 입력 방식

Claude Code를 쓸 때 초보자가 빨리 익히면 좋은 것은 복잡한 설정이 아니라 입력 방식입니다.

첫째, 그냥 자연스럽게 말하면 됩니다. 명령어를 기계처럼 외우지 않아도 됩니다. "이 파일 설명해줘", "이 에러 수정해줘", "이 버튼을 더 눈에 띄게 바꿔줘"처럼 말해도 됩니다.

둘째, 파일을 직접 가리키면 훨씬 정확해집니다. Claude Code는 @로 파일을 참조하는 방식을 지원합니다. 예를 들어 @src/app/page.tsx처럼 지정하면, "그 파일"이 무엇인지 애매하게 설명할 필요가 줄어듭니다.³

셋째, 대화는 짧고 선명할수록 좋습니다. "뭔가 로그인 쪽이 이상한데 전체적으로 다 봐줘"보다 "로그인 후 이동이 안 된다. 관련 파일을 찾고 원인을 먼저 설명해줘"가 훨씬 낫습니다.

이 감각은 앞으로 계속 중요합니다. 좋은 협업은 멋진 프롬프트보다 선명한 지목에서 시작합니다.

초보자에게 특히 유용한 첫 질문들

처음 며칠 동안은 아래 같은 질문 패턴만 잘 써도 충분합니다.

• 이 프로젝트 구조를 초보자 기준으로 설명해줘.

• 내가 수정해야 할 파일 후보를 먼저 찾아줘.

• 코드는 아직 바꾸지 말고, 어떤 방식으로 고칠지 계획부터 말해줘.

• 이 파일에서 핵심 함수가 무엇인지 알려줘.

• 바뀐 파일마다 왜 수정이 필요한지 설명해줘.

이 질문들의 공통점은 간단합니다. 바로 "먼저 이해하고, 그다음 수정한다"는 흐름입니다. 공식 문서도 복잡한 변경이나 코드 탐색에서는 먼저 계획을 세우는 흐름을 권장합니다.¹²

초보자일수록 이 순서가 중요합니다. 이해 없이 수정하면 결과를 검토하기가 어렵고, 검토 없이 승인하면 금방 불안해집니다.

권한 요청이 귀찮아도, 초반에는 친구다

Claude Code를 처음 쓰면 꽤 자주 멈춰 서는 느낌을 받을 수 있습니다. 파일을 수정하려고 해도, 명령을 실행하려고 해도 확인을 받기 때문입니다. 처음에는 "왜 이렇게 자꾸 물어보지?" 싶을 수 있습니다.

그런데 초보자에게 이 과정은 오히려 좋은 장치입니다.

Claude Code는 기본적으로 편집이나 셸 명령 실행 전에 승인을 받습니다.³ 이 덕분에 여러분은 무엇이 바뀌는지, 어떤 명령이 실행되는지 한 번 더 보고 판단할 수 있습니다. 즉, 도구가 너무 빨라서 사용자가 뒤처지는 상황을 줄여줍니다.

물론 익숙해지면 허용 규칙을 조금씩 조정해 반복 승인 피로를 줄일 수 있습니다.² 하지만 시작 단계에서는 권한 요청을 귀찮은 방해물로만 보지 않는 편이 좋습니다. 브레이크가 있는 자전거는 답답한 자전거가 아니라, 오래 탈 수 있는 자전거입니다.

Plan Mode는 초보자의 안전한 연습장이다

Claude Code의 강력한 기능 중 하나가 Plan Mode입니다. 이 모드에서는 코드를 바로 바꾸기보다, 먼저 읽고 분석해서 계획을 세우는 데 집중합니다.¹

이 기능이 왜 좋을까요?

초보자는 아직 "어디를 고쳐야 하는지"보다 "무엇이 바뀔 가능성이 있는지"를 먼저 아는 편이 안전하기 때문입니다. Plan Mode는 마치 공사 전에 설계도를 먼저 펴보는 느낌에 가깝습니다.

이런 상황에서 특히 잘 맞습니다.

• 여러 파일이 함께 바뀔 것 같은 기능 추가

• 로그인이나 데이터 저장처럼 실수 비용이 큰 수정

• 코드베이스가 낯설어서 먼저 구조를 파악해야 하는 경우

• 당장 수정하지 않고, 접근 방법을 비교하고 싶은 경우

공식 문서에서도 Plan Mode는 복잡한 구현, 코드 탐색, 상호작용적인 개발에서 유용하다고 설명합니다.¹

초보자라면 이 한 문장을 기억해두면 좋습니다.

잘 모르겠으면 바로 고치게 하지 말고, 먼저 계획을 시켜라.

이 습관 하나만으로도 Claude Code는 훨씬 덜 무섭습니다.

추천하는 첫 작업 흐름: 탐색 → 계획 → 수정 → 확인

Claude Code를 처음 배울 때는 거창한 개인 비법보다, 반복 가능한 기본 흐름이 중요합니다. 입문자에게 가장 추천하는 흐름은 아래 네 단계입니다.

• 탐색: 이 기능과 관련된 파일, 데이터 흐름, 현재 구조를 설명받는다.

• 계획: 무엇을 바꿀지, 어떤 파일이 바뀔지 먼저 말하게 한다.

• 수정: 범위를 좁혀 실제 변경을 진행한다.

• 확인: 바뀐 내용, 실행 결과, 남은 위험 요소를 검토한다.

이 흐름은 공식 문서의 탐색과 계획 중심 권장 방식과도 잘 맞습니다.¹²

중요한 것은 속도가 아니라 리듬입니다. 처음부터 "한 번에 다 해줘"라고 하면 Claude Code의 장점이 오히려 흐려집니다. 반대로 이 리듬으로 가면 초보자도 도구를 통제하는 느낌을 갖기 쉽습니다.

실전에서 자주 쓰게 될 작업 패턴

이제 초보자가 실제로 가장 자주 쓰게 될 패턴을 몇 가지 살펴보겠습니다.

첫 번째는 설명받기 패턴입니다. 낯선 파일이나 함수가 보이면 바로 "이 코드가 무슨 역할인지 쉬운 말로 설명해줘"라고 묻습니다. 이 패턴은 공부와 실습을 동시에 하게 해줍니다.

두 번째는 찾아달라고 하기 패턴입니다. "글 목록 데이터는 어디서 불러오는지 찾아줘", "회원가입과 관련된 파일만 추려줘" 같은 요청입니다. 초보자는 파일 찾기만 빨라져도 자신감이 확 올라갑니다.

세 번째는 작은 수정 맡기기 패턴입니다. 문구 변경, 버튼 정리, 입력 검증 추가, 에러 메시지 개선처럼 범위가 선명한 작업을 맡깁니다. 여기서 작은 성공 경험이 쌓입니다.

네 번째는 원인 추적 패턴입니다. "이 에러 메시지를 보고 원인을 찾아줘. 코드는 바로 바꾸지 말고 후보부터 말해줘." 이런 방식은 디버깅을 배울 때 특히 좋습니다.

다섯 번째는 검토 요청 패턴입니다. "지금 수정한 파일별 역할을 설명해줘", "기존 기능을 깨뜨릴 수 있는 부분이 있는지 점검해줘"처럼 결과를 리뷰하게 만드는 방식입니다.

이 패턴들은 모두 화려하지 않습니다. 하지만 실무에서는 이런 반복이 서비스 완성도를 만듭니다.

CLAUDE.md는 '반복 설명 줄이기'용 메모장이다

Claude Code를 조금만 쓰다 보면 같은 설명을 자꾸 하게 됩니다. "우리는 Next.js를 쓴다", "새 라이브러리는 먼저 물어봐야 한다", "테스트는 이 명령으로 돌린다", "기존 폴더 구조는 크게 바꾸지 않는다" 같은 것들 말입니다.

이럴 때 등장하는 것이 CLAUDE.md입니다. 공식 문서에서는 이 파일을 매 세션 시작 시 읽는 프로젝트 지침 파일처럼 설명합니다.² 쉽게 말하면, AI 팀원을 위한 짧은 온보딩 문서입니다.

다만 초보자가 처음부터 이 파일을 거창하게 만들 필요는 없습니다. 오히려 짧을수록 좋습니다. 공식 가이드도 정말 필요한 규칙만 남기고 간결하게 유지하라고 권합니다.²³

처음에는 아래 정도면 충분합니다.

• 이 프로젝트의 핵심 기술 스택

• 자주 쓰는 실행 명령

• 꼭 지켜야 할 작업 규칙

• 건드리면 안 되는 영역

이 파일의 역할은 Claude Code를 똑똑하게 만드는 것보다, 헷갈리게 하지 않는 것에 가깝습니다.

대화가 길어질수록, 정리 기술이 중요해진다

Claude Code를 쓰다 보면 대화가 길어집니다. 처음에는 구조 설명, 그다음 파일 찾기, 이후 수정, 다시 에러 해결까지 이어지면 맥락이 금방 길어집니다. 공식 문서도 컨텍스트가 길어질수록 성능이 흔들릴 수 있으니 관리가 중요하다고 강조합니다.²

그래서 초보자가 빨리 익히면 좋은 명령이 있습니다. 바로 /clear, /compact, /resume 같은 세션 관리 기능입니다.¹³

/clear는 대화를 새로 시작하고 싶을 때 유용합니다. /compact는 긴 대화를 압축해서 핵심만 남기고 이어가게 도와줍니다. /resume은 이전 작업을 다시 불러올 때 좋습니다.¹³

이 기능들을 어렵게 생각할 필요는 없습니다. 책상 위가 어질러지면 정리하고 다시 일하는 것과 같습니다. Claude Code도 정리된 대화 위에서 더 잘 움직입니다.

처음부터 잘 쓰는 사람보다, 금방 다시 묻는 사람이 강하다

초보자가 Claude Code를 쓰며 가장 경계해야 할 것은 "한 번에 완벽하게 써야 한다"는 부담입니다. 실제로는 잘못 물어보는 것보다, 애매한 상태로 그냥 넘어가는 것이 더 위험합니다.

이해가 안 되면 바로 다시 물으면 됩니다.

"조금 더 쉬운 말로 설명해줘."

"왜 이 파일이 바뀌는지 한 줄씩 설명해줘."

"지금 답은 너무 넓어. 로그인 폼 UI만 다시 좁혀서 말해줘."

이런 재질문은 부끄러운 일이 아닙니다. 오히려 Claude Code를 잘 쓰는 사람일수록 방향을 자주 조정합니다. 강력한 도구일수록, 사용자 쪽의 짧은 수정 지시가 더 중요합니다.

초보자가 처음 일주일 동안 해보면 좋은 것

첫 일주일은 Claude Code를 시험하는 시간이 아니라, Claude Code와 호흡 맞추는 시간이라고 생각하면 좋습니다.

너무 큰 목표를 세우지 말고, 아래 같은 작은 경험을 차근차근 해보세요.

• 프로젝트 구조 설명받기

• 특정 기능 관련 파일 찾기

• 작은 문구 수정 맡기기

• 에러 메시지 원인 설명받기

• 수정 전 계획부터 받아보기

• 바뀐 파일 설명받기

• 대화가 길어졌을 때 /compact 써보기

• 반복 규칙을 CLAUDE.md에 한두 줄 적어보기

이 정도만 해도 감이 꽤 옵니다. Claude Code는 "엄청난 자동 개발 기계"로 시작할수록 실망하기 쉽고, "프로젝트를 같이 읽고 수정하는 조수"로 시작할수록 만족도가 높습니다.

이 장의 핵심: 첫 성공은 '큰 기능'이 아니라 '편안한 첫 대화'다

Claude Code의 진짜 시작은 설치 완료가 아닙니다. 첫 번째 자연스러운 대화, 첫 번째 작은 수정, 첫 번째 안전한 검토에서 시작됩니다.

처음부터 회원가입, 인증, 데이터베이스, 배포까지 다 맡기려 하지 않아도 됩니다. 오히려 이렇게 가볍게 출발하는 편이 좋습니다.

"이 프로젝트 설명해줘."

"이 파일 역할을 알려줘."

"이 버튼 문구만 바꿔줘."

"코드는 아직 바꾸지 말고 계획부터 보여줘."

이 네 문장만 편하게 쓸 수 있어도 Claude Code의 첫 문턱은 이미 넘은 것입니다.

강력한 도구는 기능이 많아서 오래 쓰이는 것이 아닙니다. 첫 경험이 덜 무서울 때 오래 씁니다. Claude Code도 마찬가지입니다. 초보자에게 필요한 것은 모든 기능의 숙달이 아니라, 이 도구와 대화할 수 있다는 감각입니다.

다음 장에서는 Claude Code와 나란히 많이 쓰이게 될 또 하나의 도구, Codex를 만나보겠습니다. 그때부터는 두 도구의 성격 차이도 조금씩 보이기 시작할 것입니다.

참고

¹Common workflows - Claude Code Docs

²Best Practices for Claude Code

³How to Use Claude Code (Beginner Guide)