“AI한테 코드 수정 시켰다가 파일이 날아가면 어떡하죠?” — 클로드 코드(Claude Code)를 처음 써보려는 분들이 가장 많이 하는 걱정입니다. 결론부터 말씀드리면, 클로드 코드는 파일을 무턱대고 건드리지 않습니다. Read(읽기) → Edit(수정) → Write(쓰기)라는 세 단계를 순서에 맞게 거치고, 각 단계마다 사용자에게 확인을 구합니다. 이번 편에서는 이 세 도구가 실제로 어떻게 작동하는지, 코드를 통째로 맡기는 프롬프트는 어떻게 쓰는지 실전으로 배워보겠습니다.
파일 도구 세 가지, 이것만 알면 됩니다
클로드 코드에는 파일을 다루는 핵심 도구(tool)가 세 가지 있습니다. 도구(tool)란 클로드가 특정 작업을 수행하기 위해 내부적으로 사용하는 기능 모듈이라고 생각하시면 됩니다.
| 도구 | 역할 | 특징 |
|---|---|---|
| Read | 파일 내용 읽기 | 줄 번호 포함 출력, 수정 전 필수 단계 |
| Edit | 파일 일부 교체 | 지정 문자열을 찾아 새 내용으로 정밀 교체 |
| Write | 파일 전체 쓰기 | 기존 내용을 모두 덮고 새로 작성 |
세 도구 모두 클로드가 자동으로 선택해서 사용하지만, 원리를 알면 더 정확한 지시를 내릴 수 있습니다.
Read → Edit 순서, 왜 지켜야 할까요?
클로드 코드는 Edit 도구를 쓰기 전에 반드시 Read를 먼저 실행합니다. 이건 규칙이 아니라 설계입니다. 이유는 Edit 도구의 작동 방식에 있습니다.
Edit 도구는 “찾아서 바꾸기” 방식으로 동작합니다. old_string(바꿀 내용)과 new_string(새 내용)을 지정하면, 파일에서 정확히 일치하는 문자열을 찾아 교체합니다. 공백 하나, 들여쓰기(인덴트) 하나까지 정확히 맞아야 합니다.
만약 Read 없이 Edit을 시도하면 클로드가 기억 속 내용을 기준으로 교체 대상을 지정하게 됩니다. 그런데 실제 파일이 조금이라도 다르면 교체가 실패하거나, 엉뚱한 부분이 바뀌게 됩니다. Read를 먼저 실행해야 현재 파일 상태를 정확히 파악하고 안전하게 수정할 수 있습니다.
핵심 원칙: Read 없이 Edit하면 클로드 코드가 스스로 막습니다. 이 순서는 실수를 막기 위한 안전장치입니다.
실전! 파일을 통째로 맡기는 프롬프트
클로드 코드 파일 수정 작업은 프롬프트 한 줄로 시작됩니다. 실제 예시를 보겠습니다.
상황 1 — 함수 이름에 오타가 있는 경우
app.py 파일에서 get_user_naem 함수를 get_user_name으로 수정해줘
클로드가 실행하는 단계:
1. Read — app.py를 읽어 줄 번호와 현재 내용 파악
2. Edit 제안 — get_user_naem → get_user_name 교체 내용 표시
3. 사용자 확인 — “이 변경을 적용할까요?” 물음 (기본 모드)
4. 승인 시 파일에 실제 반영
상황 2 — 새 스크립트를 처음부터 만드는 경우
엑셀 파일을 읽어서 이름·나이·이메일 컬럼만 뽑아 CSV로 저장하는
파이썬 스크립트를 extract_data.py로 만들어줘
이때는 Write 도구가 사용됩니다. 기존 파일이 없으니 새로 생성하는 방식입니다.
여러 파일을 동시에 맡기는 법
파일이 여러 개라면 이렇게 요청하면 됩니다:
components/ 폴더 안의 모든 버튼 컴포넌트를 찾아서
클래스명 btn-primary를 btn-main으로 일괄 변경해줘
클로드는 내부적으로 Glob(파일 패턴 검색)과 Grep(내용 검색) 도구를 함께 활용해 대상 파일을 먼저 찾은 뒤, 각각 Edit을 수행합니다. Glob은 *.tsx처럼 파일 이름 패턴으로 찾기, Grep은 특정 단어가 들어간 파일을 내용으로 찾기라고 기억하세요.
Edit와 Write, 어떻게 구분해서 쓸까요?
처음에는 두 도구가 비슷해 보이지만 용도가 확실히 다릅니다.
- Edit → 기존 파일의 일부만 바꿀 때. 나머지 코드를 건드리지 않아서 안전합니다.
- Write → 파일 전체를 새로 작성할 때. 기존 내용이 통째로 교체됩니다.
실무에서는 Edit이 훨씬 자주 쓰입니다. Write는 주로 새 파일 생성이나 파일을 처음부터 완전히 다시 쓸 때만 사용됩니다. 클로드도 기존 파일에는 Edit을 우선 선택합니다.
팁: “이 부분만 바꿔줘”라고 명시하면 Edit, “전체를 다시 작성해줘”라고 하면 Write가 사용됩니다.
권한 모드로 실수 방지하기
클로드 코드는 파일을 수정하기 전에 기본적으로 사용자 확인을 요청합니다. 터미널 하단에서 Shift + Tab 을 누르면 세 가지 모드를 순환할 수 있습니다.
| 모드 | 동작 방식 | 추천 상황 |
|---|---|---|
| Normal (기본) | 파일 수정 전 매번 확인 요청 | 초보자, 중요한 파일 작업 시 |
| Accept edits | 편집 자동 승인, 셸 명령만 확인 | 수정이 많고 내용 검토가 끝났을 때 |
| Plan | 읽기만, 수정 없음 | 큰 변경 전 계획 먼저 검토할 때 |
처음 시작할 때는 Normal 모드에서 변경 내용을 직접 눈으로 확인하는 습관을 들이는 것을 권장합니다.
자주 묻는 질문 (FAQ)
Q. 클로드가 파일을 수정했는데 되돌리고 싶어요. 방법이 있나요?
A. 클로드 코드는 Git(버전 관리 도구)과 통합되어 있습니다. 프로젝트가 Git으로 관리된다면 git diff로 변경 내용을 확인하고, git checkout 명령으로 이전 상태로 되돌릴 수 있습니다. Git을 쓰지 않는 경우라면, 중요한 파일은 작업 전 복사본을 만들어두는 것을 권장합니다.
Q. Edit 도구가 “일치하는 문자열을 찾을 수 없다”고 실패해요. 왜 그런가요?
A. Edit 도구는 공백, 탭, 줄바꿈까지 완전 일치를 요구합니다. 파일이 중간에 수정됐거나 클로드가 최신 상태를 읽지 않았을 때 발생합니다. “파일을 다시 읽고 수정해줘”라고 요청하면 대부분 해결됩니다.
Q. 파일 한 개가 아니라 프로젝트 전체를 맡길 수도 있나요?
A. 가능합니다. 다만 변경 범위가 넓을수록 Plan 모드로 계획을 먼저 확인한 뒤, 단계별로 진행하는 것이 안전합니다. “먼저 어떻게 바꿀 건지 계획만 보여줘”라고 요청하면 수정 없이 계획만 출력해줍니다.
한 줄 요약: 클로드 코드는 Read → Edit → Write 순서로 파일을 안전하게 다루며, Normal 모드에서 한 단계씩 확인하면 초보자도 걱정 없이 코드를 통째로 맡길 수 있습니다.
참고 자료
– Claude Code 공식 문서 — 개요
– 클로드 코드 내장 도구 총정리 (DaleSeo Engineering Blog)
– Text editor tool — Claude Platform Docs