Claude 가이드 #18: Text Editor 도구 — Claude가 파일을 직접 열어 고쳐주는 손

이 글은 Claude API 공식 문서의 Text Editor tool 페이지를 정리한 글입니다. 원문: https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool 마지막 확인: 2026-05-28

1. 한 줄 요약

#

Claude에게 “이 파일 좀 봐줘"라고 부탁하면, 파일을 직접 열어보고 어느 줄이 문제인지 찾아 고친 부분만 정확히 바꿔주는 도구입니다.

2. 무엇이고 왜 좋을까

#

지금까지 Claude에게 글이나 코드를 봐달라고 하면 보통은 이렇게 했어요. “이 내용을 복사해서 붙여넣고, 답변을 받아서, 다시 내 파일에 옮긴다.” 가운데 단계가 너무 많죠.

Text Editor(텍스트 에디터, 파일 편집) 도구는 그 가운데 단계를 없애줍니다. 마치 옆자리 동료가 “잠깐 파일 줘봐"라고 말하고 직접 펼쳐서 빨간 펜으로 한 줄만 살짝 고쳐주는 것과 같아요.

핵심은 네 가지 동작입니다 — view(열어보기), str_replace(부분만 바꾸기), create(새로 만들기), insert(특정 줄에 끼워넣기). 전체 파일을 다시 쓰는 게 아니라 고칠 부분만 콕 집어 바꿉니다. 그래서 긴 글이라도 토큰(AI가 글자를 세는 단위) 낭비가 적고, 변경 이력이 깔끔합니다. 도구를 부르는 데 약 700 토큰 정도가 추가로 들지만, 파일 전체를 다시 보내는 비용에 비하면 훨씬 가볍습니다.

3. 이런 상황에서 써요

#

상황 1: 학생 — 발표 자료 오탈자 점검

#

대학 발표를 앞두고 스크립트 파일을 정리하고 있어요. 30분짜리 발표용 텍스트라 분량이 꽤 됩니다. “처음부터 끝까지 읽고 어색한 문장 다섯 군데만 자연스럽게 다듬어줘"라고 부탁하면, Claude가 파일을 열어보고 딱 그 다섯 군데만 바꿔서 돌려줍니다. 나머지 멀쩡한 문장은 그대로 두니까, 발표 전날 밤에 안심하고 맡길 수 있어요.

상황 2: 직장인 — 회사 매뉴얼 업데이트

#

회사 안내 문서에 “휴가 신청은 3일 전까지"라고 쓰여 있는데, 정책이 바뀌어서 “5일 전까지"로 수정해야 합니다. 매뉴얼이 50페이지인데 비슷한 표현이 여기저기 흩어져 있어요. Claude에게 “휴가 관련 일정 안내를 모두 찾아서 새 정책에 맞게 고쳐줘"라고 부탁하면, 파일을 훑어보고 관련된 문장만 콕 집어 바꿔줍니다. 그것도 어느 줄을 어떻게 바꿨는지 다 보고하면서요.

상황 3: 일반인 — 개인 일기·메모 정돈

#

스마트폰에 휘갈겨 쓴 여행 메모가 있어요. 시간 순서가 뒤죽박죽이고, 같은 식당 이야기가 세 군데에 흩어져 있습니다. “이 메모를 날짜순으로 정렬하고, 같은 장소 이야기는 한 곳에 모아줘"라고 부탁하면 Claude가 직접 파일을 열어 정돈해줍니다. 한 줄 한 줄 복사·붙여넣기 하지 않아도 되고, 무엇이 어떻게 옮겨졌는지도 친절하게 알려줍니다.

4. 가볍게 시작하기

#

💻 개발 경험이 있으신가요? 아래 코드는 Python 기준 가장 짧은 예시입니다. 비개발자라면 “아, 이렇게 부탁하면 되는구나” 정도로 보고 넘어가셔도 충분합니다.

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    # ↓ 이 한 덩어리가 "파일 편집기를 손에 쥐여주는" 설정입니다
    tools=[{
        "type": "text_editor_20250728",
        "name": "str_replace_based_edit_tool",
        "max_characters": 10000,  # 큰 파일은 만 글자까지만 보여주기
    }],
    messages=[{
        "role": "user",
        "content": "primes.py 파일에 문법 오류가 있어. 좀 봐줄래?",
    }],
)
print(response)

코드의 핵심은 tools=[...] 부분 한 덩어리예요. 이걸 넣어주는 순간 Claude는 “아, 이번엔 파일을 직접 볼 수 있구나"라고 알아챕니다. max_characters는 파일이 너무 길 때 잘라서 보는 분량을 정하는 안전장치고요. 메시지에는 평소처럼 한국어로 자연스럽게 부탁만 하면 됩니다 — Claude가 알아서 view 명령으로 파일을 열어보고, 필요하면 str_replace로 고쳐줘요.

5. 흔한 오해와 함정

#

⚠️ 함정 1: “도구만 켜면 알아서 파일을 열고 저장하지 않나요?”

#

사실 Claude는 직접 여러분 컴퓨터의 파일을 만지지 못합니다. Claude가 “이 파일 열어줘"라고 요청을 보내면, 그 요청을 받아서 실제로 파일을 읽고 결과를 다시 알려주는 건 여러분의 프로그램입니다.

❌ “도구만 붙이면 파일이 저절로 바뀐다” ✅ “Claude가 변경안을 만들고, 실제 적용은 내 프로그램이 한다”

이걸 알면 좋은 점은, 변경 전에 한 번 더 검토하는 절차를 끼워넣을 수 있다는 거예요. 중요한 파일이라면 백업부터 만들어두면 안심입니다.

⚠️ 함정 2: “부분 바꾸기(str_replace)인데 왜 자꾸 실패하지?”

#

str_replace는 글자 그대로 일치해야 동작합니다. 띄어쓰기 한 칸, 줄 끝 공백 하나만 달라도 “찾지 못했어요"라는 답이 옵니다. 또 같은 문장이 두 곳에 있으면 “정확히 한 곳만 바꿀 수 있는데 여러 곳이 있다"며 멈춥니다.

해결법은 간단해요. 바꾸려는 문장의 앞뒤 한 줄까지 함께 지정해주세요. 예: “휴가는 3일 전” 대신 “신청 안내: 휴가는 3일 전까지"처럼 주변 맥락을 포함하면 유일하게 일치합니다.

⚠️ 함정 3: “왜 자꾸 같은 파일을 두 번 세 번 열어보지?”

#

Claude는 파일을 한 번에 다 외우지 않습니다. 긴 파일이라면 일부만 본 뒤 “이쯤 더 봐야겠다” 하고 다시 부탁할 수 있어요. 이건 비효율이 아니라 꼼꼼함의 신호입니다.

다만 매번 전체를 다 보여주면 토큰이 아까우니, 위의 코드처럼 max_characters(최대 글자 수)를 적당히 정해두는 게 좋아요. 만 글자 정도면 보통의 글이나 코드 하나는 충분히 담깁니다.

6. 한 단계 더 (관심 있는 분만)

#

🎯 여기까지 오신 분 환영합니다. 이 섹션은 더 깊이 알고 싶은 분을 위한 보너스입니다. 본문만 읽으셔도 충분합니다.

Claude의 요청을 실제 파일 작업으로 옮기는 부분을 조금 더 살펴볼게요. 도구가 보내오는 명령은 네 가지뿐이라, 각각에 맞춰 분기만 해주면 됩니다.

def handle_editor_tool(tool_call):
    cmd = tool_call.input.get("command", "")
    path = tool_call.input.get("path", "")

    if cmd == "view":          # 파일 열어보기
        return open(path).read()
    elif cmd == "str_replace": # 일부 글자만 바꾸기
        old = tool_call.input["old_str"]
        new = tool_call.input["new_str"]
        text = open(path).read()
        return open(path, "w").write(text.replace(old, new, 1))
    elif cmd == "create":      # 새 파일 만들기
        return open(path, "w").write(tool_call.input["file_text"])
    elif cmd == "insert":      # 특정 줄에 끼워넣기
        # insert_line, insert_text 받아서 처리
        pass

명령별로 처리만 다르고 구조는 똑같다는 게 보이실 거예요. 실제로 쓰실 때는 백업 만들기, 경로가 정상인지 확인하기, 에러가 나면 차분히 알려주기 정도만 더해주면 든든해집니다.

도구 종류별 차이도 잠깐 비교해볼까요.

특별한 이유가 없다면 가장 최신인 text_editor_20250728을 쓰시면 됩니다.

7. 한 마디

#

처음 들으면 “Claude가 내 파일을 만진다고?” 싶어서 살짝 긴장될 수 있어요. 하지만 실제로는 Claude가 변경안을 제안하고, 실행은 여러분의 프로그램이 결정하는 구조라 안전장치를 충분히 끼워넣을 수 있습니다. 처음엔 중요한 파일의 복사본으로 시험해보시고, 익숙해지면 점점 더 큰 작업을 맡겨보세요.

혹시 잘 안 된다면 함정 1~3 중 하나일 가능성이 큽니다. 특히 str_replace가 자꾸 빗나간다면 앞뒤 맥락을 함께 지정해보세요 — 그 한 가지로 대부분 해결됩니다.

다음 글에서는 Claude 가이드 #19 — Bash 도구를 살펴봅니다. 텍스트 에디터가 “파일을 만지는 손"이라면, Bash는 “명령어를 직접 실행하는 손"이에요. 두 도구를 함께 쓰면 Claude가 훨씬 더 든든한 작업 짝꿍이 됩니다.

Claude API 공식 문서를 한국어로 풀어쓴 시리즈입니다. 원문 정확성이 가장 우선, 의역과 친근함은 그 위에서.