이 페이지의 목차
이 페이지의 목차
확인 날짜 안내
공식 문서 Claude Code 작동 방식(원본 날짜 미상, 수집 2026-10-18) 기준이다. 이 원본은 입문 개요라 세션 선택 창 단축키, 같은 세션을 두 터미널에서 열 때, 체크포인트 세부, 메시지 대기열 규칙은 다른 문서로 넘긴다.
Claude Code로 일하는 중에 "멈추고, 고치고, 되돌리고, 이어 가고, 갈라 보는" 방법이다. 처음 쓰는 사람이라면 "실수해도 되돌릴 수 있는 범위와 없는 범위"부터 확인하는 데 쓴다.
준비물(필요한 것)#
| 필요한 것 | 내용 |
|---|---|
| Claude Code를 쓰는 곳 하나 | 터미널, 데스크톱 앱, IDE 확장, claude.ai/ |
| 작업할 폴더 | 세션은 claude를 실행한 현재 디렉터리에 묶인다 |
| 되돌리기 기준을 하나 더 두려면 git | 체크포인트는 git과 별개이고, 링크 파일· |
| 병렬 세션을 돌리려면 git worktree | 브랜치마다 별도 디렉터리를 만들어 세션을 나눈다 |
| 바깥 시스템 동작을 막으려면 권한 모드· | 데이터베이스· |
1. 일하는 중에 끼어들기#
원본은 처음부터 다시 하지 않고 언제든 방향을 바꿀 수 있다고 말한다. 두 방법이 있다. Claude Code 작동 방식
| 방법 | 무엇이 일어나나 (원본 기준) | 이럴 때 |
|---|---|---|
Esc | 즉시 멈춘다. 실행 중인 도구 호출 | 엉뚱한 방향으로 가고 있어 지금 멈춰야 할 때 |
정정을 입력하고 Enter | 멈추지 않는다. 메시지가 대기열에 표시되고, Claude가 도구 호출 중이면 그 호출들이 끝나는 대로 같은 턴 안에서 읽고 다음 단계 전에 조정한다 | 하던 일은 계속하되 다음 단계에 반영시키고 싶을 때 |
"이럴 때" 열은 편집자 정리다. 원본은 두 방법의 동작만 설명한다.
첫 시도가 틀렸을 때도 새로 시작하지 않고 대화로 다듬는다. 원본 예: "Fix the login bug" → (Claude가 조사하고 시도) → "That's not quite right. The issue is in the session handling." → (Claude가 접근을 조정). Claude Code 작동 방식
2. 맡길 때는 지시 대신 위임#
원본은 유능한 동료에게 맡기듯 맥락과 방향을 주고 세부는 Claude가 알아내게 하라고 한다. 어떤 파일을 읽고 어떤 명령을 돌릴지 지정할 필요가 없다고 말한다. Claude Code 작동 방식
원본 예시 프롬프트:
The checkout flow is broken for users with expired cards.
The relevant code is in src/payments/. Can you investigate and fix it?예시에 담긴 것은 증상(만료된 카드 사용자의 결제 흐름이 깨짐), 관련 위치(src/payments/), 맡길 일(조사하고 고치기)이다. 편집자 연결: 공식 컨텍스트 창 문서는 프롬프트를 구체적으로 써 읽는 파일을 줄이라고 한다. Claude Code 컨텍스트 창 두 원본을 함께 보면 "어떻게"는 맡기되 "무엇이 문제고 어디쯤인지"는 주는 것으로 볼 수 있다.
3. 되돌리기: 체크포인트#
파일을 편집하기 전에 Claude Code가 현재 내용을 스냅샷한다. Claude Code 작동 방식
- 문제가 생기면
Esc를 두 번 눌러 이전 상태로 되감는다. - 또는 Claude에게 되돌려 달라고 한다.
되돌릴 수 있는 범위와 없는 범위 (원본 기준). Claude Code 작동 방식
| 되돌릴 수 있다 | 되돌릴 수 없다 |
|---|---|
| Claude가 편집한 파일 변경 | 원격 시스템에 미친 동작 |
| 대화를 재개한 뒤에도 남은 체크포인트 | 심볼릭 링크· |
- 체크포인트는 git과 별개다. Claude Code 작동 방식
- 원본은 원격 동작을 권한 모드와 권한 규칙으로 통제하라고 한다. 되돌릴 수 없는 동작이 걱정되면 그 동작이 묻지 않고 돌지 않게 모드와 규칙을 고른다. → 권한 모드, Claude Code 권한 모드 고르기Claude Code 작동 방식
- (2026-10-18 기준) 스킬을 백그라운드 포크로 돌리면 그 편집은 세션 체크포인트 밖에서 일어난다. 그 뒤
/rewind는 대화에서 Claude가 이미 편집한 파일만 복원하고, 스킬이 그 밖의 파일에 한 편집은 남으니 git으로 되돌린다. Claude Code 스킬 → 서브에이전트
4. 이어 가기와 갈라 보기: 세션#
세션은 독립적이다. 새 세션은 이전 대화 없이 빈 컨텍스트 창으로 시작하고, 세션을 넘어 남길 것은 자동 메모리(Auto memory)와 메모리(CLAUDE.md)가 맡는다. 대화는 메시지·도구 사용·결과가 ~/.claude/projects/ 아래 평문 JSONL 파일로 로컬에 저장되고, 이 기록 덕분에 되감기·재개·포크가 된다. 경로, 보존 기간, 지우는 법은 원본이 ~/.claude 애플리케이션 데이터 문서로 넘긴다. Claude Code 작동 방식
| 하고 싶은 것 | 명령 (원본 그대로) | 결과 |
|---|---|---|
| 하던 대화를 이어 가기 | claude --continue 또는 claude --resume | 같은 세션 ID로 다시 열고 기존 대화에 이어 쓴다 |
| 원래 세션을 남긴 채 새 세션으로 갈라 보기 | --fork-session 또는 / | 기록을 새 세션 ID로 복사하고 원래 세션은 그대로 둔다 |
| 지난 세션 고르기 | / 선택 창 | 기본은 현재 worktree의 세션, 단축키로 다른 worktree· |
공식 CLI 문서가 더하는 세부 (2026-10-21 기준): Claude Code CLI 레퍼런스 → Claude Code CLI 플래그
--continue는 현재 디렉터리의 가장 최근 대화를 열되,claude -p·Agent SDK로 만든 세션과 첫 프롬프트가/loop인 세션은 건너뛴다. 이것들까지 이으려면claude -p --continue를 쓴다.--resume은 ID·이름 대신 세션 transcript.jsonl의 절대 경로도 받는다. ID로 찾을 때는 현재 프로젝트와 git worktree, 그다음 이 기기의 다른 모든 프로젝트를 찾는다(v2.1.223 이전에는 현재 프로젝트와 worktree만).--name(-n)으로 이름을 붙이면claude --resume <name>으로 연다.-p실행을 남기지 않으려면--no-session-persistence(print 모드 전용, 재개할 수 없음).- 재개해도 시스템 프롬프트는 첫 요청 때 기록한 것을 컴팩션 전까지 쓴다. 재개하며
--append-system-prompt같은 시스템 프롬프트 플래그를 바꾸거나 빼면 그 변화는 컴팩션 때나 새 대화에서 반영된다. 기본 동작이다. 기록하지 않는 예외(--system-prompt-snapshot off, 클라우드 세션 밖의--bare등)는 Claude Code CLI 플래그.
평문 JSONL 저장에 대해 편집자 메모: 원본은 대화가 평문 파일로 로컬에 남는다고만 말한다. 고객 자료를 다루는 세션이라면 이 파일이 어디에 얼마나 남는지를 원본이 링크한 애플리케이션 데이터 문서로 확인한 뒤 안내한다.
5. 브랜치와 병렬 세션#
- 세션은 현재 디렉터리에 묶인다. 브랜치를 바꾸면 Claude는 새 브랜치의 파일을 보지만 대화 기록은 그대로라, 바꾸기 전에 나눈 이야기를 기억한다. Claude Code 작동 방식
- 세션이 디렉터리에 묶이므로 git worktree로 브랜치마다 별도 디렉터리를 만들어 Claude 세션을 병렬로 돌릴 수 있다. Claude Code 작동 방식
- (2026-10-21 기준) worktree 세션에서 "Yes, and don't ask again" 승인이 저장되는
.claude/settings.local.json은 메인 체크아웃 루트의 파일이다. 저장소 하위 디렉터리에서 시작해도 저장소 루트의 파일을 쓴다(예외 조건과 v2.1.211 전 동작은 Claude Code 설정 파일). 공유.claude/settings.json은 세션의 주 작업 디렉터리에서 읽는다. Claude Code 설정 파일과 우선순위
- (2026-10-21 기준) worktree 세션에서 "Yes, and don't ask again" 승인이 저장되는
됐는지 확인하는 법#
- 정정 메시지가 들어갔는지: 멈추지 않고 입력한 정정은 대화에 대기열(queued)로 표시된다. Claude가 도구 호출 중이면 그 호출들이 끝나는 대로 같은 턴 안에서 읽는다(1절). Claude Code 작동 방식
- 세션이 남았는지: 대화는
~/.claude/projects/아래 평문 JSONL 파일로 저장된다./resume선택 창에 현재 worktree의 세션이 보이고, 단축키로 다른 worktree·프로젝트까지 넓힐 수 있다(4절). Claude Code 작동 방식 - 이어 쓰기와 갈라 보기 구분:
--continue·--resume은 같은 세션 ID로 다시 열고,--fork-session·/branch는 새 세션 ID를 만들며 원래 세션은 그대로 둔다(4절). Claude Code 작동 방식 - 되감기가 됐는지: 원본에는 되감은 뒤 확인하는 방법이 따로 없다. 되돌릴 수 있는 범위와 없는 범위는 3절 표로 확인한다. Claude Code 작동 방식
언제 쓰고 언제 쓰지 않는가#
- 체크포인트는 Claude가 편집한 파일을 되돌릴 때 쓴다. 데이터베이스·API·배포처럼 바깥에 미친 동작에는 기대지 않는다. 원본이 체크포인트할 수 없다고 밝힌 범위다. Claude Code 작동 방식
- 원본은 체크포인트가 git과 별개라고만 말하고 git을 대신한다고 하지 않는다. 편집자 해석: 링크 파일과 백그라운드 포크 편집은 체크포인트 밖이므로, 이런 작업에서는 git 커밋을 되돌리는 기준점으로 함께 두는 편이 안전하다고 볼 수 있다. Claude Code 작동 방식, Claude Code 스킬
- 원본은 포크(
--fork-session,/branch)의 동작만 말하고 용도는 말하지 않는다. 편집자 해석: 포크는 기록을 새 세션 ID로 복사하고 원래 세션을 그대로 두므로, 지금까지의 맥락을 유지한 채 다른 접근을 시험할 때 쓸 수 있다고 볼 수 있다. 근거는 원본의 "copies the history into a new session ID, leaving the original unchanged" 문장이다. Claude Code 작동 방식 관련 없는 일로 넘어갈 때는 원본 기준으로/clear가 맞다. Claude Code 컨텍스트 창 → 장기 작업 컨텍스트 관리 - 대화로 말한 지시는 컴팩션으로 사라질 수 있다. 세션을 이어 가도 계속 지켜야 할 규칙은 CLAUDE.md에 둔다. Claude Code 작동 방식, Claude Code 권한 모드
관련#
- 에이전트 루프 — 사람도 루프 안에 있다는 원본 설명
- Claude Code — 실행 환경(Local·Cloud·Remote Control)과 인터페이스
- 권한 모드 — 되돌릴 수 없는 동작의 통제