읽고, 고치고, 커밋까지 | Claude와 첫 대화

다섯 번의 대화로 코드 읽기부터 파일 수정·실수 복구·git 커밋까지 첫 개발 사이클을 한 번에 돌리며 권한 흐름을 체험합니다

Overview

Claude Code 를 깔고 첫 세션까지 띄웠습니다. 도구는 준비됐지만, 자연어 한 줄로 코드가 어떻게 움직이는지는 직접 부딪쳐야 감이 옵니다.

이번 레슨은 작은 Todo 앱을 받아 코드 읽기 → 한 파일 깊이 보기 → README 수정 → 실수 복구 → git 커밋 까지 다섯 번의 대화로 첫 개발 사이클을 끝냅니다. 매 단계에서 Claude 가 어떤 도구를 쓰고 어떤 권한이 필요한지 직접 관찰합니다.

학습 목표

Claude 가 답을 추측하지 않고 파일을 직접 읽으며 답하는 모습을 관찰합니다.
@ 로 한 파일에 집중시켜 답변 정확도를 올립니다.
쓰기 작업에서 권한 승인 흐름과 Always allow 의 위험성을 체험합니다.
Esc+Esc 와 Checkpoint 로 잘못된 변경을 되돌립니다.
자연어로 git 커밋을 지시하고 결과를 ! 로 확인합니다.

시작하기 전 확인사항

Claude Code 설치·로그인 완료 (claude --version 으로 확인)
VS Code 또는 시스템 터미널 사용 가능

이 저장소에는 강의 Q&A 도우미(/qna)가 미리 등록돼 있습니다. 강의 내용이 헷갈릴 때 Claude Code 입력창에 한국어로 그냥 물어보시면 됩니다. "Skill 이 뭐였지?" 처럼 강의에서 다룬 개념을 묻거나, "Context Window 다시 설명해줘" 같은 질문에 자동으로 활성화됩니다. 이 도우미가 어떻게 들어왔는지는 Chapter 06 의 "기존 Skill 가져다 쓰기" 레슨에서 다시 다룹니다.

다섯 번의 대화로 진행됩니다. 읽기에서 쓰기로 한 단계씩 옮겨가며, Claude 가 어떤 도구를 쓰고 어떤 권한이 필요한지 직접 관찰합니다.

읽기는 자유롭게, 쓰기·셸 실행은 승인 후 진행됩니다

VS Code 통합 터미널에서 Claude Code 를 실행합니다.

claude

Step 1: 프로젝트가 뭐하는지 묻기

긴 프롬프트는 Shift+Enter 로 줄바꿈

Claude Code 입력창에서 Enter 는 메시지를 바로 전송합니다. 여러 줄로 프롬프트를 쓰고 싶다면 Shift+Enter 또는 Ctrl+J 로 줄바꿈을 넣으세요. 이미지를 붙여넣을 땐 Ctrl+V 를 씁니다.

Claude Code 입력창에 다음을 입력하고 Enter 를 누릅니다.

이 프로젝트가 뭐하는 프로젝트야?

Claude 는 답을 추측하지 않습니다. README.md, package.json, 주요 소스 파일을 직접 열어 읽고 그 결과를 바탕으로 답합니다. 터미널에서 어떤 파일을 여는지 실시간으로 확인할 수 있습니다.

Chapter 01 에서 본 Tool Use 가 실제로 작동하는 장면입니다. 읽기 작업은 승인 없이 자유롭게 진행됩니다.

프로젝트 규모에 따라 탐색 시간이 다릅니다

작은 프로젝트는 몇 초면 충분하지만, 큰 프로젝트는 더 많은 파일을 훑어야 합니다. Claude 가 파일을 읽는 중이라면 Ctrl+C 로 중단하지 말고 기다려 주세요.

Step 2: @ 로 한 파일에 집중시키기

전체를 훑었으니 이번에는 한 파일을 깊게 봅니다.

@app/page.tsx이 파일이 하는 일을 설명해줘

@ 를 입력하면 파일 경로 자리에서 탭 자동완성이 동작합니다. 지정한 파일이 Claude 의 Context 로 직접 들어가기 때문에, "page.tsx 설명해줘" 처럼 검색을 시키는 쪽보다 답이 더 정확하고 빠릅니다.

Claude 는 함수의 역할, 데이터 흐름, 다른 파일과의 관계를 정리해 답합니다.

Step 3: README 수정하기

여기서부터 Claude 가 파일을 수정합니다. 읽기와 달리 쓰기는 승인을 거칩니다.

README 의 Contributors 섹션에 "내 이름 - Frontend Developer" 를 추가해줘

수정을 시도하면 권한 프롬프트가 나타납니다.

Claude wants to edit README.md

Allow?  [y] Yes  [a] Always allow  [n] No

세 가지 선택지의 의미는 다음과 같습니다.

y (Yes): 이번 한 번만 허용합니다. 다음에 같은 도구를 쓰면 다시 묻습니다.
a (Always allow): 이 도구를 앞으로도 자동 허용하고 settings.json 에 저장합니다. 편하지만 위험합니다.
n (No): 거부합니다. Claude 가 다른 방법을 찾거나 다음 지시를 기다립니다.

y 로 이번 한 번만 허용해 봅니다. 수정이 끝나면 변경 내용이 diff 로 표시됩니다. 추가된 줄은 초록색, 삭제된 줄은 빨간색입니다.

Always allow 는 신중하게

Always allow 는 그 도구 전체를 무조건 자동 허용합니다. 예를 들어 Bash 를 한 번 Always allow 로 풀어두면 그 뒤로는 어떤 셸 명령도 묻지 않고 실행됩니다. 실수로 잘못 허용했다면 /permissions 명령으로 허용 목록을 확인하고 제거합니다.

Step 4: Esc+Esc 로 되돌리기

Step 3 의 결과가 예상과 다를 수 있습니다. Contributors 섹션 대신 README 맨 위에 적혔거나, "내 이름" 이 그대로 들어갔거나. 이때 Esc 를 빠르게 두 번 누르면 Rewind 가 작동합니다. Claude 의 마지막 행동을 통째로 되돌립니다.

되돌린 뒤 더 구체적인 지시로 다시 요청합니다.

README 의 Contributors 섹션(맨 아래)에 "토이크레인 - Frontend Developer" 한 줄만 추가해줘

구체적인 지시일수록 원하는 결과에 가깝습니다.

Step 5: git 커밋하기

마지막은 변경사항 저장입니다.

변경사항 커밋해줘

Claude 는 git add 와 git commit 을 실행합니다. 셸 명령어 실행에도 승인이 필요합니다.

Claude wants to run: git add README.md

Allow?  [y] Yes  [a] Always allow  [n] No

y 로 허용하면 Claude 가 변경 내용을 분석해 커밋 메시지를 자동으로 작성합니다. 결과는 ! Bash 모드로 빠르게 확인할 수 있습니다.

! git log --oneline -1

a1b2c3d docs: add contributor to README

! 를 입력창 맨 앞에 두면 Claude 를 거치지 않고 셸 명령이 그대로 실행됩니다. 빠른 상태 확인에 유용합니다.

다섯 번의 대화로 프로젝트 이해부터 파일 수정·실수 복구·git 커밋까지 끝났습니다.

실수 복구 심화: Checkpoint

Esc+Esc 는 마지막 한 행동만 되돌립니다. 그런데 Claude 가 다섯 단계쯤 진행한 뒤, 처음부터 다른 방향이었어야 했다는 걸 깨닫는 순간이 있습니다.

이때 Checkpoint 를 씁니다. 작업 중간중간 자동으로 체크포인트가 찍혀 있어 원하는 시점까지 한 번에 돌아갈 수 있습니다.

Esc 를 빠르게 두 번 누르면 Rewind 창이 열리고, 거기서 한 단계 전 대신 더 이전 체크포인트를 고르면 됩니다. 자동 체크포인트는 학습자가 새 지시를 줄 때마다 찍히기 때문에 "그 지시 직전" 으로 돌아가는 데 가장 편합니다.

Rewind 는 한 방향입니다

되돌린 뒤 다시 원래 상태로 돌아가는 redo 는 없습니다. 되돌렸다면 새 지시로 다른 방향을 잡고 진행하는 게 일반적입니다.

핵심 포인트 정리

다섯 단계의 순서는 우연이 아닙니다. 평소 개발자가 매일 도는 사이클을 그대로 따라갑니다.

읽기 (Step 1·2): 무엇이 있는지부터 봅니다. 추측 대신 실제 파일을 근거로 합니다.
이해: 읽은 내용을 바탕으로 무엇을 어떻게 바꿀지 결정합니다. 사람이 판단하는 자리입니다.
수정 (Step 3): 정해진 변경을 코드에 반영합니다. 쓰기·셸 실행은 승인이 필요하고, Always allow 는 신중하게 씁니다.
실수 복구 (Step 4): Esc+Esc 로 마지막 한 행동을, Checkpoint 로 여러 단계 전을 되돌립니다.
저장 (Step 5): 변경을 커밋해 다음 단계로 넘깁니다. 흐름의 마디입니다.

자연어 한 줄이 각 단계를 작동시키지만, "무엇을 만들지·결과가 맞는지" 의 판단은 여전히 사람의 몫입니다. Chapter 01 에서 본 "판단의 분업" 이 실전에서 도는 모습입니다.

Claude Code 에 대해 모르는 게 있으면 Claude Code 에게 물어보세요

Claude Code 의 기능·설정·단축키가 궁금할 때 외부 ChatGPT 나 Claude 웹에 물어보지 마세요. 같은 세션 안에서 직접 질문하는 편이 가장 빠릅니다. Claude Code 는 현재 프로젝트에 접근할 수 있어 상황을 파악하고 직접 조치까지 가능합니다. 내부적으로 claude-code-guide 라는 전문 서브에이전트가 Claude Code 자체에 대해 정확하게 답합니다. 명시적으로 부르고 싶으면 입력창에 @claude-code-guide 처럼 @ 뒤에 에이전트 이름을 입력하면 바로 호출됩니다.

FAQ

Q: Claude 가 파일을 너무 많이 읽어 시간이 오래 걸리면 어떻게 하나요?
- A: 탐색 범위를 좁혀 지시하면 됩니다. "src/api 폴더만 설명해줘" 처럼 범위를 명시하면 훨씬 빠르게 답합니다.
Q: 커밋 메시지를 직접 지정하려면 어떻게 하나요?
- A: 구체적으로 지시합니다. "변경사항을 'feat: add contributor section' 메시지로 커밋해줘" 라고 하면 그 메시지가 그대로 쓰입니다. 매번 지정하기 번거롭다면 반복 작업을 자동화할 수 있습니다 (Chapter 06 의 Custom Command).
Q: Claude 가 잘못된 파일을 수정하려 하면 어떻게 막나요?
- A: 승인 단계에서 n 으로 거부합니다. 작업이 차단되고 Claude 는 다른 방법을 시도하거나 다음 지시를 기다립니다. 이미 승인한 뒤라면 Esc+Esc 로 되돌립니다.
Q: Always allow 로 잘못 풀어둔 도구는 어디서 확인하나요?
- A: /permissions 명령을 실행하면 허용 도구 목록이 표시됩니다. 거기서 직접 제거할 수 있습니다. 자세한 활용은 다음 레슨에서 다시 다룹니다.

이어서 배울 내용

한 사이클을 끝내고 나면 두 가지가 마음에 걸립니다. 권한을 매번 묻는 흐름이 부담스럽고, 작업을 잠시 멈췄다가 다음에 또 켤 때 같은 자리에서 다시 시작하고 싶어집니다.

다음 레슨에서는 자주 마주치는 이 두 상황을 다루는 명령을 정리합니다.

세션 관리: --continue, --resume 으로 이전 세션 다시 열기와 /clear · /compact 의 차이
권한 모드: Shift+Tab 으로 default · acceptEdits · plan · auto 4가지 순환