Claude Code 기본 사용법, 설치부터 첫 실행까지 따라하기

Claude Code를 막 깔았는데 터미널 화면만 보면 막막하셨죠? 어떤 명령어부터 쳐야 할지, 코드가 망가지진 않을지 걱정되는 마음 잘 압니다. 저도 똑같이 헤매다가 정리한 흐름이라, 이 글만 따라오면 첫 작업까지 차근차근 끝낼 수 있어요.

Claude Code로 시작하기 전에 알아둘 핵심 개념

Claude Code는 한마디로 터미널에서 대화하며 코드 작업을 돕는 도구입니다. 무언가 거창한 자동화 기계라기보다, 옆자리에 앉은 동료에게 말로 부탁하듯 요청을 던지면 코드를 읽고 고치고 새로 만들어주는 작업 방식이라고 생각하면 편해요. 처음 쓸 때는 이걸 채팅처럼 가볍게 시작해도 됩니다. 거창한 명령어를 외울 필요 없이, 하고 싶은 일을 한국어로 또박또박 말하면 됩니다.

중요한 건 기대 수준을 제대로 잡는 거예요. Claude Code는 VS Code 같은 편집기를 완전히 대체하는 도구가 아닙니다. 코드를 읽고, 수정하고, 생성하고, 리뷰하는 과정을 빠르게 보조하는 작업 파트너에 가깝죠. 그래서 편집기는 그대로 켜두고, 반복되거나 막히는 부분만 Claude Code에게 맡기는 식으로 함께 쓰는 게 자연스럽습니다. 이렇게 역할을 나눠 생각하면 입문 과정이 훨씬 덜 부담스러워요.

한국어로 요청해도 되냐고 자주 묻는데, 전혀 문제없습니다. 오히려 비전공자라면 모국어로 정확하게 의도를 전달하는 편이 결과가 좋아요. 특히 코드 설명 듣기, 작은 수정 맡기기, 문서나 주석 작성 같은 작업에서 체감 효과가 큽니다. 초보자가 처음 잡아야 할 개념은 아래 다섯 가지 정도면 충분합니다.

대화형 요청 방식: 명령어 암기보다 자연스러운 말로 부탁하는 흐름
프로젝트 문맥 이해: 실행한 폴더 안의 파일을 바탕으로 답한다는 점
터미널 중심 실행: GUI 버튼이 아니라 텍스트 입력으로 움직인다는 점
파일 단위 수정 흐름: 어떤 파일을 어떻게 바꿀지 명확히 지정하는 습관
결과 검토 후 반영하는 습관: 바로 믿지 말고 확인한 뒤 적용하기

설치 방법과 개발 환경 준비

설치가 가장 큰 진입 장벽이라는 말, 정말 공감합니다. macOS, Windows, Linux는 각자 터미널 환경이 다르기 때문에, 설치 전에 내가 쓰는 셸이 무엇인지와 명령을 실행할 권한이 있는지를 먼저 확인하는 게 안전해요. 윈도우 사용법을 찾는 분이라면 기본 명령 프롬프트보다 PowerShell이나 Windows Terminal 환경에서 진행하는 편이 훨씬 매끄럽습니다.

확인 항목	왜 필요한가	초보자 체크 포인트
운영체제 종류	설치 방식과 명령이 달라짐	맥인지 윈도우인지 먼저 구분
터미널 환경	셸 종류에 따라 동작 차이	윈도우는 PowerShell 권장
실행 권한	설치 중 권한 오류 방지	관리자 권한 필요 여부 확인
네트워크 상태	설치 파일 다운로드에 필요	안정적인 연결에서 진행
설치 후 버전	정상 설치 여부 판단	버전 확인 명령이 응답하는지

설치 자체보다 더 중요한 건 설치 이후의 확인 과정입니다. 버전 확인과 기본 실행 테스트까지 마쳐야 비로소 실제 사용 준비가 끝난 거예요. 업데이트나 호환성은 처음부터 깊게 파고들 필요 없이, 설치 직후 최소한의 항목만 점검하면 됩니다. 아래 순서대로 따라가 보세요.

운영체제와 터미널 환경을 확인합니다
자신에게 맞는 설치 방식을 선택합니다
설치 명령을 실행합니다
버전 확인 명령으로 설치 결과를 점검합니다
업데이트 가능 여부를 가볍게 확인합니다
기본 실행 테스트로 정상 동작을 확인합니다

로그인, 연결, 초기 세팅값 정리

설치는 끝났는데 그다음에 뭘 해야 할지 모르겠다는 막막함, 여기서 풀어보겠습니다. 보통 로그인이나 인증이 필요한데, 순서는 단순해요. 먼저 계정을 연결하고, 그다음 권한 범위를 확인하면 됩니다. 계정 연결과 권한 확인이 중요한 이유는, 이게 제대로 되어 있어야 작업 요청이 막힘없이 처리되기 때문이에요. 처음 세션을 안전하게 시작하려면 아래 최소 항목만 챙기면 충분합니다.

로그인 상태 확인: 인증이 정상적으로 끝났는지
작업 폴더 확인: 어떤 폴더에서 실행 중인지
권한 범위 확인: 파일 읽기와 수정 권한이 있는지
기본 세팅값 점검: 기본 설정으로도 충분한 상태인지
테스트 요청 1회 실행: 간단한 질문으로 동작 확인

환경 변수, API 연결, 세부 세팅값 같은 항목은 솔직히 처음부터 건드릴 필요가 없어요. 이런 것들은 필요한 경우에만 손대는 항목으로 분류해두면 부담이 확 줄어듭니다. 기본 설정만으로도 입문 단계의 작업은 대부분 무리 없이 진행됩니다.

혹시 설정을 잘못 만졌더라도 너무 겁먹지 마세요. 초기화나 재설정으로 처음 상태로 되돌릴 수 있습니다. 되돌릴 길이 있다는 걸 알고 시작하면 이것저것 시도해보는 마음도 한결 편해져요. 처음엔 최소 설정으로 출발하고, 익숙해진 뒤 하나씩 손대는 게 가장 안전한 길입니다.

터미널에서 실행하는 기본 흐름

이제 첫 세션을 처음부터 끝까지 돌려볼 차례입니다. Claude Code를 터미널에서 시작하는 이유는, 작업할 폴더 안으로 들어가서 실행하면 그 안의 파일들을 문맥으로 삼아 답하기 때문이에요. 그래서 어떤 디렉터리에서 실행하느냐가 결과 품질에 직접 영향을 줍니다. 엉뚱한 폴더에서 실행하면 정작 필요한 파일을 보지 못한 채 답하게 되거든요.

또 하나, 인터페이스를 화면 가득한 GUI처럼 기대하지 마세요. 세션 안에서 내가 말을 건네고 결과를 받아보는 대화 구조라고 이해하는 편이 훨씬 자연스럽습니다. 아래 흐름을 그대로 따라가 보면 감이 잡힐 거예요.

터미널을 엽니다
작업할 디렉터리로 이동합니다
해당 폴더에서 Claude Code를 실행합니다
프로젝트 문맥이 제대로 잡혔는지 확인합니다
하고 싶은 작업을 프롬프트로 입력합니다
응답과 실행 결과를 확인합니다
이어서 다음 요청으로 넘어갑니다

여기서 꼭 들이고 싶은 습관이 하나 있어요. 응답을 받았다고 바로 믿고 넘어가지 말고, 결과를 읽어보고 미흡하면 추가 질문으로 정확도를 끌어올리는 겁니다. 한 번에 완벽을 바라기보다 대화를 주고받으며 다듬는다는 마음이면 훨씬 좋은 결과를 얻을 수 있습니다.

자주 쓰는 기본 명령어와 도움말 읽는 법

명령어를 전부 외워야 한다는 부담은 내려놓으셔도 됩니다. 핵심은 도움말과 사용 예시를 통해 그때그때 필요한 걸 찾아내는 거예요.

실행 시작: 작업 폴더에서 도구를 켜는 단계
도움말 확인: 사용 가능한 옵션을 스스로 탐색
버전 확인: 현재 버전과 정상 동작 점검
현재 작업 대상 확인: 어떤 파일과 폴더를 보고 있는지
파일 관련 요청: 특정 파일을 읽거나 열어달라는 요청
코드 생성 요청: 새 함수나 파일을 만들어달라는 요청
코드 수정 요청: 기존 코드를 고쳐달라는 요청
오류 재시도 또는 점검: 잘못된 결과를 다시 살펴보는 흐름

명령어 용도	언제 쓰는가	초보자 실수
도움말 확인	옵션이 헷갈릴 때	문서만 보고 헤매기
버전 확인	설치 직후나 업데이트 후	확인 없이 바로 작업 시작
작업 대상 확인	요청 전 문맥 점검	엉뚱한 폴더에서 실행
파일 요청	특정 파일을 다룰 때	파일명을 모호하게 전달
코드 생성	새 기능이 필요할 때	목표를 두루뭉술하게 요청
코드 수정	기존 코드를 고칠 때	한 번에 너무 큰 수정 요청

명령어 오류가 나면 도구 탓부터 하지 마세요. 대부분은 입력 형식이 틀렸거나, 실행 위치가 잘못됐거나, 권한 문제인 경우가 많습니다. 이 세 가지부터 차분히 점검하면 의외로 금방 해결됩니다. 그리고 버전 확인과 도움말 읽는 법을 초반에 익혀두면, 나중에 업데이트로 화면이 조금 바뀌어도 스스로 적응하기가 훨씬 수월해져요.

프로젝트 연결과 파일 탐색의 기본

Claude Code는 어느 폴더에서 실행했느냐에 따라 보는 범위가 달라집니다. 프로젝트 루트, 즉 전체를 아우르는 최상위 폴더에서 실행하면 프로젝트 구조 전반을 문맥으로 삼습니다. 반면 하위 폴더에서 실행하면 그 안쪽 파일만 보게 되죠. 작업 성격에 따라 둘을 구분해 쓰는 게 좋은데, 전체 구조를 함께 봐야 하는 작업이면 루트에서, 특정 부분만 손볼 거면 좁은 폴더에서 실행하는 식입니다.

파일 탐색과 디렉터리 관리가 정확할수록 문맥 이해도 좋아지고, 결국 응답 품질도 올라갑니다. 어디에 무슨 파일이 있는지 흐릿한 상태로 요청하면, 의도와 다른 결과가 나오기 쉬워요. 그래서 작업 전에 현재 위치와 핵심 파일을 한 번 정리하고 시작하는 습관이 큰 도움이 됩니다.

현재 경로 확인: 지금 어느 폴더에 있는지
핵심 폴더 파악: 소스 코드와 설정이 어디 있는지
설정 파일 위치 확인: 프로젝트 설정이 담긴 파일
수정 대상 파일 열기: 손볼 파일을 미리 확인
저장소 상태 확인: 변경 이력이 깔끔한지
작업 범위 좁히기: 한 번에 다룰 영역 정하기

VS Code를 함께 쓰는 분도 많을 텐데, 따로 떨어진 환경을 오갈 필요 없이 VS Code 안의 터미널 패널에서 그대로 실행해도 됩니다. 편집기에서 파일을 눈으로 보면서 터미널로 요청을 던지면, 어떤 파일이 어떻게 바뀌는지 곧바로 확인할 수 있어 초보자에게 특히 편한 흐름이에요.

프롬프트 입력으로 코드 읽기, 수정, 생성하기

이제 실제 작업의 핵심인 프롬프트 입력입니다. 결과를 좌우하는 건 결국 요청을 얼마나 구체적으로 주느냐예요.

파일 요약 요청: 이 파일이 무슨 역할인지 정리해달라고 하기
특정 함수 설명 요청: 함수 하나의 동작을 풀어달라고 하기
작은 수정 요청: 한 군데만 콕 집어 고쳐달라고 하기
새 함수 생성 요청: 목표와 입출력을 명시해 만들어달라고 하기
주석 또는 문서 작성 요청: 설명이나 문서를 채워달라고 하기
수정 전 검토 요청: 바꾸기 전에 영향 범위를 먼저 확인하기

작업 유형	좋은 요청 예시	확인해야 할 결과
코드 읽기	이 파일의 핵심 흐름을 요약해줘	설명이 실제 코드와 맞는지
작은 수정	이 함수의 변수명만 바꿔줘	다른 부분이 안 깨졌는지
함수 생성	입력과 출력을 정해 함수 작성	요구한 조건을 충족하는지
주석 작성	이 함수에 한국어 주석 추가	내용이 정확하고 간결한지
문서 작성	이 모듈 설명 문서 초안 작성	빠진 항목이 없는지

추상적인 요청보다 파일명, 함수명, 목표, 제약 조건을 함께 주면 결과가 눈에 띄게 좋아집니다. 코드 수정은 한 번에 크게 맡기지 말고 작은 단위로 나눠 요청하고, 그때마다 결과를 검토한 뒤 다음으로 넘어가세요. 망가질까 봐 걱정되는 마음, 이 방식이면 크게 줄어듭니다. 특히 주석 생성, 문서 작성, 반복되는 함수 작성 같은 일에서는 손이 확 가벼워지는 걸 직접 느끼실 거예요.

코드 리뷰, 디버깅, 테스트 실행에 활용하는 방법

Claude Code를 만능 디버거로 보면 실망할 수 있어요. 더 현실적인 그림은, 오류의 원인 후보를 정리해주고 버그를 재현할 단계를 구조화해주는 보조 도구입니다. 최종 판단은 사람이 하되, 막막한 출발점을 잡아주는 역할이라고 생각하면 딱 맞습니다. 오류 메시지를 그대로 붙여넣고 무엇이 문제일지 후보를 정리해달라고 하면, 어디부터 살펴봐야 할지 길이 보여요.

변경사항 검토와 코드 리뷰에서는 무엇이 바뀌었고 왜 바뀌는지를 짚는 질문이 핵심입니다. 단순히 고쳐달라고 하기보다, 이 수정이 어떤 영향을 주는지 함께 물어보면 위험한 변경을 미리 걸러낼 수 있어요. 아래 요청들을 상황에 맞게 활용해보세요.

변경 요약 요청: 무엇이 어떻게 바뀌었는지 정리
위험한 수정 지점 찾기: 부작용 가능성이 큰 부분 점검
오류 메시지 해석: 메시지가 가리키는 원인 풀이
버그 재현 단계 정리: 문제를 다시 만들어내는 순서
테스트 아이디어 제안: 검증할 시나리오 후보
리팩토링 후보 찾기: 정리하면 좋은 부분 식별
코드 품질 점검 요청: 가독성과 구조 살펴보기

테스트 실행 결과가 나오면 거기서 멈추지 말고, 그 결과를 근거로 후속 요청을 이어가세요. 실패한 테스트의 원인을 묻고, 수정안을 받아 다시 확인하는 반복이 디버깅의 기본 리듬입니다.

Git과 저장소 작업을 함께 다루는 실전 흐름

코드를 고치다 보면 결국 Git과 마주치게 됩니다. 너무 복잡하게 생각할 필요는 없고, 핵심은 수정 전후로 저장소 상태를 확인하고 변경사항을 검토하는 습관이에요. 이렇게만 해도 실수로 엉뚱한 걸 덮어쓰는 사고를 크게 줄일 수 있습니다. 작업을 시작하기 전과 마치기 전, 두 시점에 상태를 한 번씩 확인한다고 기억해두세요.

작업 전 상태 확인: 시작 시점의 깨끗한 상태 점검
변경 파일 검토: 어떤 파일이 바뀌었는지 확인
브랜치 확인: 지금 어느 브랜치에서 작업 중인지
커밋 전 diff 점검: 실제 변경 내용을 눈으로 검토
동기화 전 최종 검토: 원격에 올리기 전 마지막 확인

브랜치 작업과 커밋 메시지 작성은 초보자가 자주 놓치는 부분이에요. 처음부터 복잡한 전략을 짤 필요 없이, 작업 단위로 브랜치를 나누고 변경 내용을 명확한 커밋 메시지로 남기는 최소한의 흐름만 지켜도 충분합니다. 커밋 메시지가 막막하면 변경 요약을 받아 다듬는 데 Claude Code를 활용해도 좋아요.

팀 작업이라면 더 신중해야 합니다. 변경을 자동으로 그냥 적용하기보다, 검토 가능한 제안 형태로 받아 사람이 확인한 뒤 반영하는 편이 훨씬 안전해요. 협업에서는 작은 신중함이 큰 사고를 막아줍니다.

초보자를 위한 실습 예시와 작업 자동화 첫걸음

읽기만 하면 금방 잊어버리니, 작은 예제 프로젝트나 가벼운 저장소에서 직접 손을 움직여보는 게 가장 좋습니다. 아래 다섯 가지를 차례로 해보세요.

README 요약 받기: 프로젝트 개요를 정리해달라고 하기
오류 메시지 원인 찾기: 메시지를 붙여넣고 원인 후보 묻기
반복되는 코드 정리 요청: 중복 부분을 정돈해달라고 하기
간단한 함수 추가: 작은 기능 하나를 만들어보기
테스트 초안 요청: 검증용 테스트 뼈대를 받아보기

실습 목표	입력 예시	기대 결과
문서 이해	이 README를 세 줄로 요약해줘	핵심을 짚은 짧은 요약
오류 진단	이 에러의 원인 후보를 알려줘	점검할 지점 목록
코드 정리	중복된 부분을 함수로 묶어줘	간결해진 코드 제안
기능 추가	이런 기능의 함수를 만들어줘	요구에 맞는 함수 초안
테스트 준비	이 함수의 테스트 초안 작성	검증 시나리오 뼈대

에이전트 기능이나 작업 자동화도 있지만, 처음부터 복잡한 흐름을 만들 필요는 없어요. 반복 작업을 줄여주는 보조 정도로만 가볍게 시작하면 됩니다. 그리고 대화 기록을 참고해 같은 요청을 점점 더 구체적으로 다듬어가는 방식이 학습 효율을 확 끌어올려줍니다. 처음엔 막연했던 요청이 회를 거듭할수록 또렷해지는 게 느껴질 거예요.

설치 오류와 실행 문제를 줄이는 점검 체크리스트

오류가 떴다고 해서 도구 자체가 문제라고 단정하지 마세요. 경험상 대부분은 경로, 권한, 명령 형식, 현재 폴더 중 하나입니다. 이 네 가지만 차분히 확인해도 상당수가 풀려요. 당황해서 이것저것 마구 바꾸기보다, 하나씩 순서대로 짚어보는 게 가장 빠른 길입니다.

실수를 줄이는 가장 확실한 베스트 프랙티스는 작은 변경부터 적용하는 거예요. 한 번에 크게 바꾸지 말고, 작게 고친 뒤 결과를 검토하고 다음 요청으로 넘어가는 흐름을 몸에 익히면 코드가 망가질 걱정이 크게 줄어듭니다. 아래 체크리스트를 곁에 두고 문제가 생길 때마다 위에서부터 점검해보세요.

현재 디렉터리 확인: 의도한 폴더에서 실행 중인지
설치 여부 재확인: 도구가 제대로 깔렸는지
버전 확인: 정상 버전이 응답하는지
로그인 상태 점검: 인증이 풀리지 않았는지
파일 권한 확인: 읽기와 수정 권한이 있는지
명령어 철자 확인: 입력 형식이 맞는지
테스트용 작은 요청부터 실행: 간단한 것으로 동작 확인
변경사항 검토 후 저장 또는 커밋: 확인을 거쳐 반영하기

Claude Code 기본 사용법, 막막함을 자신감으로 바꾸기

처음엔 터미널 화면 앞에서 어디부터 손대야 할지 막막했지만, 개념을 잡고 설치와 로그인을 끝낸 뒤 첫 실행 흐름과 명령어, 프롬프트 작성까지 따라오셨다면 이제 혼자서도 작은 작업을 시작할 수 있는 상태입니다. 핵심은 결국 작게 요청하고, 결과를 검토하고, 다음으로 이어가는 리듬이에요. 코드가 망가질까 봐 걱정했던 마음도 이 습관 하나면 한결 가벼워집니다. 저도 똑같이 헤매며 정리한 흐름인 만큼, 오늘은 작은 저장소 하나로 가볍게 한 번 실습해보시길 권합니다. 끝까지 읽어주셔서 고맙습니다.

About the author