Claude Code로 파일 직접 수정하기 — AI 페어 프로그래머를 터미널에 고용하는 법

처음 Claude Code를 설치하고 나서 가장 많이 드는 의문이 있다. "이게 그냥 채팅창이랑 뭐가 다르지?" 이 글은 그 의문을 완전히 날려버리는 내용이다. AI에게 코드 조각을 받는 게 아니라, 내 프로젝트 파일에 직접 들어와서 수정하게 만드는 방법 — 이걸 처음 써본 순간부터 개발 방식이 달라진다.

---

배경 — 기존 AI 도구와 뭐가 다른가

ChatGPT나 Claude.ai 웹에서 "이 함수 고쳐줘"라고 하면 수정된 코드가 채팅창에 출력된다. 그걸 복사해서 에디터에 붙여넣고, 저장하고, 실행해보고 — 이 반복이 생각보다 피로하다. 프로젝트가 커지면 어느 파일에 뭘 붙여넣어야 하는지 헷갈리기도 한다.

Claude Code는 이 흐름 자체를 뒤집는다. AI가 직접 파일 시스템에 접근해서 수정한다. 복붙이 없다.

내가 처음 시도한 방식은 그냥 웹처럼 쓰는 거였다. 터미널에 claude를 치고 코드를 통째로 붙여넣은 다음 "이거 고쳐줘"라고 입력했다. 응답은 잘 왔는데, 그걸 다시 파일에 옮기는 건 여전히 내 몫이었다. 이건 Claude Code를 제대로 쓰는 방식이 아니었다.

---

첫 번째 임무 — 자연어로 파일 지정하기

핵심은 파일명을 명시적으로 언급하는 것이다. AI가 내 프로젝트 폴더를 스캔하긴 하지만, 어떤 파일을 건드릴지는 내가 지정해야 한다.

claude 'main.py에 "hello_world" 함수를 추가해줘.'

이 명령 하나로 Claude Code가 하는 일의 순서는 이렇다.

1. 현재 디렉토리에서 main.py를 찾는다
2. 파일 전체를 읽어 기존 코드 구조를 파악한다
3. 중복 없이, 스타일에 맞게 함수를 작성한다
4. 수정안을 화면에 출력한다

이때 AI는 파일 전체를 무작정 바꾸지 않는다. 딱 필요한 부분만 손댄다. 기존 함수나 임포트 구조를 그대로 유지하면서 새 함수만 끼워넣는다.

---

두 번째 단계 — diff 검토와 승인

Claude Code가 수정안을 만들면 바로 파일에 쓰지 않는다. 먼저 diff 형식으로 변경 내용을 보여준다.

--- main.py (before)
+++ main.py (after)
@@ -12,0 +13,4 @@
+def hello_world():
+    """간단한 인사 함수"""
+    print("Hello, World!")
+    return "Hello, World!"

초록색(+)은 추가, 빨간색(-)은 삭제다. 이 화면에서 y를 누르면 적용, n을 누르면 취소다.

처음엔 이게 번거롭게 느껴질 수 있다. 근데 실제로 써보면 이 단계가 있어서 안심이 된다. AI가 의도치 않게 다른 부분을 건드린 경우 여기서 바로 잡을 수 있다. 특히 큰 파일에서 리팩터링을 시킬 때 차이가 크다.

---

세 번째 단계 — 대화의 연속성 활용하기

Claude Code의 진짜 강점은 여기서 나온다. 터미널 세션이 살아있는 동안 AI는 이전 대화와 파일 수정 내역을 전부 기억한다.

예를 들어, 방금 hello_world 함수를 추가했다면 이렇게 이어갈 수 있다.

# 1번 명령
claude 'main.py에 "hello_world" 함수를 추가해줘.'

# (diff 확인 후 y)

# 2번 명령 — AI는 방금 추가한 함수를 이미 알고 있다
claude '방금 추가한 함수에 인자로 이름을 받을 수 있게 수정해줘.'

두 번째 명령에서 "방금 추가한 함수"라는 표현만으로 AI가 어떤 함수인지 정확히 파악한다. 맥락이 유지되기 때문이다. 이게 단순한 코드 생성기와 페어 프로그래머의 차이다.

---

운영 팁 — 이것만 주의하면 된다

작업 범위를 좁게 지정할수록 결과가 좋다. "프로젝트 전체 리팩터링"보다 "이 파일의 이 함수만 수정"이 훨씬 정확하다.

파일이 여러 개 관련될 때는 순서대로 시키는 게 낫다. models.py를 먼저 수정하고 나서 그걸 참조하는 views.py를 수정하는 식이다. 한 번에 여러 파일을 동시에 바꾸라고 하면 충돌이 생길 수 있다.

Mac/Linux 환경 차이는 없다. 파일 경로 구분자 정도만 다른데, 자연어로 파일명만 지정하면 Claude Code가 알아서 처리한다. Docker 컨테이너 안에서도 동일하게 동작한다.

세션을 닫으면 맥락이 리셋된다. 터미널 창을 닫고 다시 열면 AI는 이전 대화를 기억하지 못한다. 장기 프로젝트라면 CLAUDE.md 파일에 프로젝트 구조와 컨벤션을 정리해두면 매번 설명하는 수고를 줄일 수 있다.

---

마무리

Claude Code를 쓰는 핵심은 AI에게 파일 접근 권한을 주고, diff로 검토한 뒤 승인하는 이 흐름에 익숙해지는 것이다. 익숙해지는 데 하루도 안 걸린다. 다음 글에서는 여러 파일에 걸친 작업을 시킬 때의 전략과, CLAUDE.md를 어떻게 세팅하면 효과적인지 다룬다.

---

🐦 X에서 더 빠르게: @baegseungh7061
📚 이 시리즈 더 보기: Code 입문
💌 새 글 알림: X 팔로우 또는 블로그 RSS 구독