【Claude Code 활용】 파일 읽기 및 쓰기 맡기기

Claude Code의 파일 조작 능력

Claude Code는 **Read(읽기)・Write(쓰기)・Edit(편집)**의 3가지 종류의 파일 조작 도구를 가지고 있습니다.

Read: 파일 내용을 읽어옴 -
Write: 신규 파일을 생성하거나 덮어씀 -
Edit: 기존 파일의 특정 부분을 차분(diff)으로 변경함

「읽고 이해하고 쓰는」 흐름을 자동으로 수행하기 때문에, 구현 지시서만 전달하면 필요한 파일을 생성해 줍니다.

실제로 맡겨보기: 구현 지시서 전달

agent01의 Step 05에서는 read_file / list_files를 구현할 필요가 있었습니다. Claude.ai에서 작성한 구현 지시서를 Claude Code에 전달했더니, 다음과 같은 흐름으로 구현이 진행되었습니다.

• 지시서를 읽음
• src/tools/ 디렉토리 구성을 확인함
• src/tools/file_tools.py를 신규 생성함
• src/step05_file_tools.py (동작 확인 스크립트)를 생성함

지시서에는 구현해야 할 함수의 시그니처(signature)와 동작 사양만 적어두고, 구체적인 코드는 Claude Code에 맡겼습니다.

Claude Code가 생성한 코드

생성된 file_tools.py의 주요 부분을 인용합니다.

def read_file(path: str) -> str:
"""파일 내용을 읽어온다.
Args:
...

주목할 점은, 지시서에 「에러 핸들링(error handling)을 구현해 주세요」라고 적지 않았음에도 불구하고, PermissionError나 UnicodeDecodeError까지 고려한 코드가 생성되었다는 점입니다.

list_files도 마찬가지로, 제외 디렉토리(.git, __pycache__ 등)를 자동으로 스킵하도록 설계되어 있습니다.

def list_files(directory: str) -> str:
"""디렉토리 하위의 파일 목록을 재귀적으로 가져온다."""
# ...
...

인간이 확인해야 할 포인트

생성된 코드는 반드시 동작 확인을 거친 후 커밋합니다. 특히 Windows 환경에서는 다음 사항을 확인했습니다.

인코딩(encoding) 설정: Windows의 기본 인코딩은 cp932 (Shift_JIS)입니다. Claude Code가 생성하는 코드는 encoding="utf-8"을 지정하고 있지만, 표준 입출력은 sys.stdout.reconfigure(encoding="utf-8")로 명시적으로 설정해야 합니다.

경로 구분자: Windows에서는 \를 사용하지만, Python의 pathlib.Path를 사용함으로써 OS 차이를 흡수할 수 있습니다. Claude Code는 pathlib을 자연스럽게 사용하는 경향이 있습니다.

깨달은 점

PROGRESS.md를 통한 인계가 유효했다: Step 05 완료 후에 PROGRESS.md에 「tool_use 사용 시에는 llama3.1:8b를 지정할 것」이라고 기록해 둔 덕분에, 다음 세션에서 다시 확인하는 수고를 덜 수 있었습니다.

지시서의 입도(granularity)가 중요하다: 「read_file 함수를 구현한다」라는 한 줄 지시보다, 「인자·반환값·에러 발생 시의 동작」까지 적은 지시서가 기대한 대로의 출력을 얻을 수 있었습니다. 입도가 세밀할수록 Claude Code의 망설임이 줄어듭니다.

요약

Claude Code의 파일 조작 능력은 구현 지시서만 잘 정비되어 있다면 고품질의 코드를 생성할 수 있습니다. 에러 핸들링이나 타입 어노테이션(type annotation)까지 자동으로 작성해 주기 때문에, 코드 리뷰의 부담을 대폭 줄일 수 있었습니다.

다음 회차

B3에서는 Claude Code의 코드베이스 탐색 능력에 대해 소개합니다. 기존 코드를 참조하면서 일관된 스타일로 새로운 도구를 생성한 경험을 전달해 드리겠습니다.

시리즈 링크 (Series B)

기사	제목
B1	Claude Code란・도입 및 초기 설정
...

Discussion