파일 읽기·쓰기·편집

🎯 학습 목표

3강에서는 파일을 바꾸지 않는 질문으로 대화를 연습했습니다. 이번 강에서는 드디어 클로드 코드가 파일을 읽고, 만들고, 고치는 과정을 다룹니다. 이 과정의 원리를 알면 "왜 이렇게 수정했지?", "왜 편집이 실패했지?", "어떻게 되돌리지?" 같은 질문에 스스로 답할 수 있습니다.

• 파일을 다루는 핵심 도구인 Read·Write·Edit의 역할과 차이를 설명할 수 있습니다.
• Edit 도구가 정확한 문자열 치환 방식으로 동작한다는 점과 그 결과를 이해할 수 있습니다.
• 권한 확인에서 변경 내용을 검토하고 승인·거절하며, 권한 모드에 따라 승인 흐름이 어떻게 달라지는지 알 수 있습니다.
• 체크포인트와 git으로 잘못된 수정을 되돌릴 수 있습니다.

실습은 3강에서 준비한 연습용 git 저장소에서 진행합니다. 시작 전에 git status로 작업 트리가 깨끗한지 확인해 두세요. 깨끗한 상태에서 시작해야 클로드 코드가 바꾼 부분만 정확히 볼 수 있습니다.

🧰 파일을 다루는 세 가지 도구

이 섹션에서는 클로드 코드가 파일을 다룰 때 쓰는 도구의 종류와 각각의 성격을 살펴보겠습니다.

1강에서 "모델은 생각하고 도구는 행동한다"고 배웠습니다. 파일 작업도 마찬가지로, 모델이 직접 디스크에 쓰는 것이 아니라 정해진 도구(tool)를 호출합니다. 공식 도구 레퍼런스에 정리된 파일 관련 핵심 도구는 다음과 같습니다.

도구	하는 일	권한 필요
Read	파일 내용 읽기. 텍스트는 줄 번호와 함께, 이미지·PDF·Jupyter 노트북도 읽음	아니요
Edit	특정 파일의 일부분을 정확히 골라 수정	예
Write	파일을 새로 만들거나 전체를 덮어씀	예
NotebookEdit	Jupyter 노트북의 셀 단위 수정	예

표에서 가장 중요한 열은 권한 필요입니다. 읽기는 기본적으로 묻지 않고, 바꾸는 행동은 권한 대상입니다. 다만 Read도 작업 디렉터리 바깥의 경로를 읽을 때는 확인을 요청합니다. "읽기는 자유롭게, 쓰기는 통제한다"는 설계라고 이해하면 됩니다.

Edit과 Write의 차이도 꼭 구분하세요. Edit은 기존 파일의 필요한 부분만 바꾸고, Write는 파일 전체를 새 내용으로 씁니다. 그래서 새 파일을 만들 때는 Write, 기존 파일의 함수 하나를 고칠 때는 Edit이 쓰이는 것이 일반적입니다. 긴 파일을 Write로 통째로 덮어쓰면 의도치 않은 부분까지 바뀔 위험이 커지므로, 기존 파일 수정 결과를 검토할 때 전체가 교체됐는지 일부만 바뀌었는지 살펴보는 습관이 좋습니다.

검색 도구도 알아 두면 좋습니다. 공식 문서에 따르면 Windows에서는 파일명 패턴 검색 Glob과 내용 검색 Grep이 기본 도구에 포함되지만, macOS·Linux·WSL에서는 이 둘을 기본 도구에서 빼고 Bash 도구로 find와 grep을 실행해 검색합니다. 그래서 운영체제에 따라 화면에 보이는 도구 이름이 다를 수 있습니다.

✏️ Edit 도구의 원리: 정확한 문자열 치환

이 섹션에서는 Edit 도구가 파일을 어떻게 고치는지 원리 수준에서 살펴보겠습니다. 이 원리를 알면 편집 실패 메시지를 봐도 당황하지 않습니다.

Edit 도구는 old_string(찾을 문자열)과 new_string(바꿀 문자열)을 받아 앞의 것을 뒤의 것으로 바꿉니다. 공식 문서는 이 방식이 정규식이나 유사 매칭을 쓰지 않는 정확한 일치이며, 공백이나 들여쓰기가 한 글자만 달라도 찾지 못한다고 설명합니다.

[개념 도식] Edit 도구에 전달되는 정보
file_path  : src/utils/price.js
old_string : return price * 0.9;
new_string : return Math.round(price * 0.9);

위 도식은 "할인 가격을 반올림해 줘"라고 요청했을 때 Edit 도구에 전달되는 정보의 형태를 보여 줍니다. 첫 줄은 대상 파일, 둘째 줄은 파일에서 찾을 원래 코드, 셋째 줄은 바꿀 코드입니다. 파일의 나머지 부분은 건드리지 않습니다.

공식 문서는 Edit이 성공하려면 세 가지 검사를 통과해야 한다고 설명합니다.

1. 먼저 읽기(read-before-edit): 현재 대화에서 그 파일을 읽은 적이 있어야 합니다. 일부만 잘려서 읽힌 경우는 인정되지 않습니다. 최신 모델은 권한 확인 없이 읽을 수 있는 파일이면 읽지 않고도 편집할 수 있지만, 문서에 따르면 Claude Opus 4.6·Haiku 4.5와 그 이전 모델은 항상 먼저 읽어야 합니다.
2. 일치: old_string이 파일에 쓰인 그대로 존재해야 합니다.
3. 유일성: old_string이 파일에서 정확히 한 번만 나와야 합니다. 여러 번 나오면 주변 코드를 더 붙여 위치를 특정하거나, replace_all 옵션으로 모두 바꿉니다.

이 원리는 실무에서 두 가지 의미가 있습니다. 첫째, 편집 도중 "문자열을 찾을 수 없다"는 식의 실패가 보여도 대부분 클로드 코드가 다시 읽고 재시도하므로 크게 걱정할 필요는 없습니다. 둘째, 클로드 코드가 파일을 읽은 뒤 내가 에디터에서 같은 부분을 고치면 내용이 어긋날 수 있습니다. 클로드 코드가 작업하는 동안에는 같은 파일을 동시에 편집하지 않는 것이 안전합니다.

✅ 수정 요청과 승인 흐름

이 섹션에서는 실제로 수정을 요청하고, 권한 확인에서 변경 내용을 검토하는 흐름을 실습해 보겠습니다.

README.md에 "실행 방법" 섹션을 추가해 줘. 설치 명령과 실행 명령을 코드블록으로 넣어 줘.

이 요청을 보내면 클로드 코드는 먼저 README.md와 설정 파일(예: package.json)을 읽어 실행 명령을 확인하고, Edit 도구로 섹션을 추가하려 합니다. 이때 Manual 모드라면 변경 내용과 함께 허용할지 묻는 권한 확인이 나타납니다. 추가·삭제되는 줄을 보고 의도대로면 승인하고, 아니면 거절한 뒤 이유를 입력하면 됩니다. 3강에서 배운 대로 권한 확인에서 Esc를 누르면 거절로 처리됩니다.

승인 흐름은 권한 모드에 따라 달라집니다. 공식 문서 기준으로 정리하면 다음과 같습니다.

모드	묻지 않고 실행되는 것	적합한 상황
Manual (default)	읽기만	모든 행동을 직접 검토, 민감한 작업
acceptEdits	읽기, 파일 편집, mkdir·touch·mv·cp 등 흔한 파일 시스템 명령	편집 후 에디터나 git diff로 한꺼번에 검토
plan	읽기 위주(분석·계획)	수정 전에 코드베이스 탐색
auto	분류기의 안전 검사를 거친 대부분의 행동	긴 작업, 잦은 확인 피로 줄이기

Shift+Tab으로 모드를 바꿀 수 있고, acceptEdits 모드에서는 상태 표시줄에 ⏵⏵ accept edits on이 표시됩니다. 입문 단계에서는 Manual로 몇 번 승인 과정을 직접 겪어 보고, 흐름이 익숙해지면 acceptEdits로 바꾼 뒤 작업이 끝나면 git diff로 모아서 검토하는 방식을 권합니다.

어떤 모드에서도 쉽게 자동 승인되지 않는 보호 경로(protected paths)도 있습니다. 공식 문서에 따르면 .git, .vscode, .idea, .husky 같은 경로는 저장소 상태나 설정이 망가지는 것을 막기 위해 Manual·acceptEdits에서 항상 확인을 요청합니다. 클로드 코드가 이런 경로를 수정하려 하면 특히 주의 깊게 검토하세요.

⏪ 되돌리기: 체크포인트와 git

이 섹션에서는 잘못된 수정을 되돌리는 두 가지 방법과 각각의 한계를 살펴보겠습니다.

체크포인트(checkpoint)는 클로드 코드가 자동으로 만드는 복원 지점입니다. 공식 문서에 따르면 턴을 시작하는 프롬프트를 보낼 때마다 새 체크포인트가 생기고, 세션을 다시 열어도 사용할 수 있습니다. 입력창이 빈 상태에서 Esc를 두 번 누르거나 /rewind를 입력하면 되감기 메뉴가 열리고, 시점을 고른 뒤 다음 중 하나를 선택합니다.

• Restore code and conversation: 코드와 대화를 모두 그 시점으로
• Restore conversation: 코드는 그대로 두고 대화만 되감기
• Restore code: 대화는 유지하고 파일 변경만 되돌리기

그러나 체크포인트에는 반드시 알아야 할 한계가 있습니다. 공식 문서는 Bash 명령으로 바뀐 파일은 추적하지 않는다고 명시합니다. 클로드 코드가 rm, mv, cp로 파일을 지우거나 옮겼다면 되감기로 복구할 수 없습니다. 내가 에디터에서 직접 고친 내용이나 다른 세션이 바꾼 내용도 보통 추적되지 않고, 심볼릭 링크·하드 링크 파일은 복원에서 건너뜁니다. 스냅샷은 기본적으로 약 30일 뒤 정리됩니다.

그래서 공식 문서도 체크포인트는 세션 단위의 빠른 복구 수단이며 버전 관리를 대체하지 않는다고 강조합니다. 실무에서는 다음 순서를 습관으로 만드세요.

git status
git diff
git restore README.md

첫 줄은 어떤 파일이 바뀌었는지 목록을 보여 줍니다. 둘째 줄은 바뀐 줄을 자세히 보여 주므로, 클로드 코드의 수정을 최종 검토하는 데 가장 확실한 방법입니다. 셋째 줄은 커밋하지 않은 README.md의 변경을 버리고 마지막 커밋 상태로 되돌립니다. 이 명령은 되돌린 내용을 복구할 수 없으니 신중히 쓰세요. 큰 작업을 맡기기 전에는 먼저 커밋해 두면 언제든 그 지점으로 돌아올 수 있습니다.

📝 핵심 요약

체크	핵심
☐ 도구	Read(읽기, 권한 불필요) · Edit(부분 수정) · Write(생성·덮어쓰기), 수정 도구는 권한 대상
☐ Edit 원리	정확한 문자열 치환, 먼저 읽기·일치·유일성 검사
☐ 승인	변경 줄을 보고 승인·거절, 익숙해지면 acceptEdits + git diff 검토
☐ 보호 경로	.git, .vscode 등은 자동 승인되지 않음
☐ 되돌리기	Esc 두 번·/rewind, 단 Bash로 바뀐 파일은 제외 → 작업 전 커밋

다음 5강에서는 단순한 파일 수정을 넘어, 원하는 결과를 정확히 얻을 수 있도록 코드 수정 요청을 구체적으로 작성하는 방법을 실습해 보겠습니다.

📚 참고 자료

• Tools reference — Claude Code Docs (Anthropic)
• Choose a permission mode — Claude Code Docs (Anthropic)
• Checkpointing — Claude Code Docs (Anthropic)
• git-restore Documentation — Git