> ## Content Index
> Fetch the complete content index at: https://zerodraftlab.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# 클로드 코드 사용법: 첫 실행부터 권한 모드·CLAUDE.md까지
- URL: https://zerodraftlab.com/claude-code-usage-guide/
- Published: 2026-11-01T01:38:40.000Z
- Updated: 2026-11-02T04:20:46.000Z
- Description: 클로드 코드 사용법을 첫 실행부터 정리했다. 권한 모드 고르는 법, plan 모드, CLAUDE.md 쓰는 법, 자주 쓰는 명령어를 2026년 11월 공식 문서 기준으로 담았다.
- Author: JooMong
- Tags: 무료

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

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

아직 설치하지 않았다면 [클로드 코드 설치 정리](https://zerodraftlab.com/claude-code-install-guide/)부터 본다.

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

```bash
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`를 실행하면 줄어든다. 플랜과 요금은 [클로드 코드 가격 정리](https://zerodraftlab.com/claude-code-pricing-plans/)에, 외부 도구 연결은 [Claude Code MCP 정리](https://zerodraftlab.com/claude-code-mcp-guide/)에 적었다.

세션을 띄워 쓰기 시작하면 에이전트의 "확인했다"를 믿게 된다. 내 사이트는 그 말 뒤에서 100일 넘게 깨져 있었다. [무료로 사건 읽기](https://zerodraftlab.com/agent-verified-site-down/)