클로드 코드 사용법: 첫 실행부터 권한 모드·CLAUDE.md까지

클로드 코드 사용법을 첫 실행부터 정리했다. 권한 모드 고르는 법, plan 모드, CLAUDE.md 쓰는 법, 자주 쓰는 명령어를 2026년 11월 공식 문서 기준으로 담았다.

공유
클로드 코드 사용법: 첫 실행부터 권한 모드·CLAUDE.md까지

클로드 코드(Claude Code)는 프로젝트 폴더에서 claude를 실행하고 할 일을 말로 적으면 움직인다. 처음에 익힐 것은 세 가지다. 작은 일부터 시키는 순서, 어디까지 묻지 않고 실행할지 정하는 권한 모드, 프로젝트 규칙을 적어 두는 CLAUDE.md다. 아래 내용은 2026년 11월 1일에 Anthropic 공식 퀵스타트, 권한 모드 문서, 모범 사례 문서에서 확인했다.

본문의 "Astra 첨언"은 OpenAI Codex의 GPT-6 Astra가 이 글을 읽고 남긴 말이다. 사람의 사용 경험담이 아니라 코딩 에이전트 관점의 판단이다.

아직 설치하지 않았다면 클로드 코드 설치 정리부터 본다.

클로드 코드 첫 세션은 읽기부터 시킨다

cd 프로젝트_폴더
claude

파일을 일일이 지정하지 않아도 된다. Claude Code가 필요한 파일을 직접 읽는다. 공식 퀵스타트의 첫 질문은 아래와 같은 것들이다.

what does this project do?
explain the folder structure
where is the main entry point?

한국어로 적어도 된다. 답을 읽으면 Claude Code가 프로젝트를 제대로 파악했는지 고치기 전에 알 수 있다.

Astra 첨언. 첫 요청에 "현재 수정된 파일을 확인하고, 기존 변경은 보존해줘"를 함께 적는다. 시작할 때의 변경 목록이 없으면 사용자가 하던 수정과 에이전트가 만든 수정을 나중에 구분하기 어렵다.

그다음 작은 수정을 시킨다

퀵스타트는 함수 하나를 추가하는 작은 일로 시작한다. Claude Code는 알맞은 파일을 찾아 변경을 보여 주고, 물어볼 때 승인하면 적용한다. 요청은 구체적일수록 좋다. 공식 문서의 예시를 옮기면 이렇다.

  • 약한 요청: "버그 고쳐줘"
  • 나은 요청: "잘못된 비밀번호를 넣으면 빈 화면이 나오는 로그인 버그를 고쳐줘"

"이 코드베이스를 개선해줘" 같은 막연한 요청은 넓은 탐색을 부른다. 그만큼 사용량도 많이 든다.

클로드 코드 권한 모드는 Shift+Tab으로 바꾼다

권한 모드는 Claude Code가 묻지 않고 실행할 수 있는 범위다. 세션 중에 Shift+Tab을 누르면 바뀐다.

모드묻지 않고 실행하는 범위어울리는 일
default읽기만모든 행동을 직접 검토할 때, 민감한 작업
acceptEdits읽기, 파일 수정, mkdir·mv 같은 흔한 파일 명령코드를 검토하며 반복할 때
plan읽기, 그리고 auto 모드를 쓸 수 있으면 분류기가 승인한 명령바꾸기 전에 코드를 살펴볼 때
auto전부. 백그라운드 안전 검사가 함께 돈다긴 작업, 승인 요청을 줄이고 싶을 때
bypassPermissions전부격리된 컨테이너와 가상 머신에서만

v2.1.283 이상의 터미널과 VS Code 세션은 auto로 시작한다. 처음부터 하나씩 확인하고 싶으면 default로 바꾸면 된다.

bypassPermissions는 조심해야 한다. 공식 문서는 이 모드가 프롬프트 인젝션(외부 내용에 숨은 지시로 에이전트를 조종하는 공격)과 의도하지 않은 행동을 막아 주지 않는다고 적는다. 그래서 실제 컴퓨터를 건드릴 수 없는 격리 환경에서만 쓰라고 안내한다.

복잡한 일은 plan 모드로 계획부터 받는다

규모가 큰 변경은 plan 모드에서 시작한다. Claude Code가 코드를 살펴보고 접근 방식을 제안하면, 승인한 뒤에 구현으로 넘어간다. 방향이 틀렸을 때 다시 하는 비용을 줄이는 절차다.

진행 중에 방향이 틀어지면 Esc로 바로 멈춘다. /rewind를 입력하거나 입력창이 비어 있을 때 Esc를 두 번 누르면 되돌리기 메뉴가 열린다. 여기서 이전 시점의 대화와 코드를 복원한다. 다만 Bash 명령으로만 바꾼 파일, 대부분의 서브에이전트 수정, Claude Code 밖에서 고친 파일은 되돌아가지 않을 수 있다. 그런 변경은 Git으로 되돌린다.

끝났는지 확인할 방법을 함께 준다

공식 모범 사례는 Claude Code에게 돌려 볼 검사를 주라고 권한다. 테스트 케이스, 스크린샷, 기대 출력을 요청에 넣으면 Claude Code가 자기 결과를 스스로 확인한다.

이메일 형식 검사를 추가해줘.
user@example.com은 통과하고 user@는 실패해야 해.
다 고친 뒤 테스트를 돌려서 결과를 보여줘.

마지막 두 줄이 있으면 "고쳤습니다"라는 말 대신 실행 결과를 받는다. 이 예시는 공식 문서의 조언을 내가 문장으로 옮긴 것이다.

Astra 첨언. 버그 수정이라면 추가한 테스트가 수정 전 코드에서 실패하는지도 확인하게 한다. 수정 후에만 통과한 테스트로는 원래 버그를 잡는 검사인지 판단하기 어렵다.

CLAUDE.md에는 코드만 봐서 모르는 것만 적는다

CLAUDE.md는 세션마다 읽히는 프로젝트 지침 파일이다. /init을 실행하면 코드베이스를 바탕으로 초안이 만들어진다. 공식 문서는 그 뒤의 일이 주로 줄을 지우는 것이라고 설명하고, 200줄 아래로 유지하길 권한다. 모든 줄이 작업마다 Claude의 주의를 조금씩 쓰기 때문이다.

저장소에 테스트 명령이 있다면 가장 먼저 적을 줄은 그 실행 명령이다. 공식 문서도 이것을 가장 유용한 한 줄로 꼽는다.

예외 없이 지켜야 할 규칙은 CLAUDE.md로 부족할 수 있다. 문서에 적어도 따를지는 Claude가 그때그때 판단한다. 반드시 지켜야 하면 훅(특정 시점에 자동으로 도는 스크립트)으로 옮긴다. 개인 취향은 CLAUDE.local.md에 적고 .gitignore에 넣는다.

Git도 말로 시킨다

what files have I changed?
commit my changes with a descriptive message
create a new branch called feature/quickstart
help me resolve merge conflicts

되돌릴 수 있게 커밋을 자주 남겨 두면 실험하기 편하다. 이 문장은 공식 문서가 아니라 내 의견이다.

Astra 첨언. 커밋을 맡길 때는 이번 요청에 해당하는 파일과 변경 부분만 포함하도록 범위를 정한다. 같은 파일에 기존 작업이 섞여 있다면 파일 이름만 확인하지 말고 스테이징된 diff까지 검토한다.

클로드 코드 자주 쓰는 명령어

명령하는 일
claude대화 세션 시작
claude "할 일"첫 지시를 넣고 시작
claude -p "질문"한 번 답하고 종료
claude -c현재 폴더의 가장 최근 대화 이어가기
claude -r이전 대화 골라서 재개
/clear대화 기록 비우기. 다른 일로 넘어갈 때 쓴다
/usage사용량 확인
/model모델 변경
/help쓸 수 있는 명령 보기
/exit종료

사용량이 빨리 닳는다면

Claude Code는 요청마다 대화 전체를 보낸다. 그래서 하루 종일 열어 둔 세션에서는 한 줄 질문도 현재 대화 전체를 다시 처리하며 사용량을 쓴다. 비용은 캐시 적중 여부에 따라 달라진다. 관계없는 일로 넘어갈 때 /clear를 실행하면 줄어든다. 플랜과 요금은 클로드 코드 가격 정리에, 외부 도구 연결은 Claude Code MCP 정리에 적었다.

세션을 띄워 쓰기 시작하면 에이전트의 "확인했다"를 믿게 된다. 내 사이트는 그 말 뒤에서 100일 넘게 깨져 있었다. 무료로 사건 읽기

더 읽기