Claude Code는 코드만을 위한 것이 아닙니다

대부분의 사람들은 저장소 (repo) 작업을 위해 Claude Code를 설치합니다. 하지만 그 내부를 들여다보면, Claude Code는 파일을 읽고, 셸 명령 (shell commands)을 실행하며, 텍스트를 편집할 수 있는 권한을 가진 터미널 에이전트 (terminal agent)입니다. PDF, 스크린샷, 송장 또는 CSV 내보내기 파일로 가득 찬 폴더를 대상으로 지정하면, 이는 범용 파일 어시스턴트 (file assistant)가 됩니다. 사용자가 일상적인 언어로 결과를 설명하면, 에이전트가 mv, find, mkdir 호출을 스스로 결정합니다.

사용자가 요청하지 않는 한 스크립트를 직접 볼 필요는 없습니다. 하지만 에이전트는 실제로 해당 명령들을 실행하므로, 여기서 핵심 기술은 작업을 정확하게 설명하고 에이전트가 통제 범위를 벗어나지 않도록 관리하는 것입니다.

에이전트가 잘 처리하는 네 가지 작업과 이를 제한하는 방법에 대해 알아보겠습니다.

1. 이름 변경 (Rename)

다운로드 폴더는 IMG_4821.jpg, Scan (3).pdf, final_v2_FINAL.docx와 같이 엉망이 되기 일쑤입니다. 원하는 명명 규칙 (naming scheme)을 설명하면, 에이전트가 파일을 읽어 빈칸을 채워줍니다.

이 폴더의 모든 PDF를 YYYY-MM-DD_vendor_amount.pdf 형식으로 이름을 변경해줘. 각 파일을 읽어서 날짜와 업체명 (vendor)을 파악해. 아무것도 건드리기 전에 전체 이름 변경 목록을 먼저 보여줘.

Claude Code는 PDF를 열 수 있기 때문에, 단순히 파일명이 아니라 파일 내용에서 날짜와 업체명을 추출합니다. 사진의 경우 EXIF 날짜를 읽을 수도 있습니다. 200개의 파일이 이동하기 전에 잘못된 추측을 잡아낼 수 있도록, 먼저 매핑 정보(old -> new)를 보여달라고 요청하세요.

2. 분류 (Sort)

"물건들을 제자리에 두어라"라는 작업은 사람에게는 지루하지만 에이전트에게는 사소한 일입니다.

이 디렉토리를 파일 유형별로 하위 폴더(이미지, 문서, 스프레드시트, 아카이브, 기타)로 분류해줘. 폴더가 없으면 생성해줘. 기존의 하위 폴더는 건드리지 마.

파일 확장자, 생성 월, 파일명 내부의 프로젝트 이름, 또는 내용을 읽은 후의 주제 등 에이전트가 추론할 수 있는 무엇이든 기준으로 분류할 수 있습니다. 연구 자료 더미를 주제별로 분류하는 것은 일반적인 셸 스크립트 (shell script)로는 할 수 없는 일이며, 바로 이 지점에서 에이전트가 스크립트를 실제로 압도합니다.

3. 수집 (Gather)

흩어진 파일들을 모으는 것은 분류의 역과정입니다.

이 폴더와 하위 폴더 아래에 있는 모든 .csv 파일을 찾아 ./collected-csv/로 복사하세요. 만약 두 파일의 이름이 같다면, 덮어쓰는 대신 숫자 접미사를 추가하세요.

첫 번째 단계에서는 이동(move)이 아닌 복사(copy)를 수행하라고 말하세요. 회계 처리를 위해 12개의 프로젝트 폴더에서 모든 인보이스(invoices)를 한곳으로 모으거나, 모노레포(monorepo) 내의 모든 .env.example 파일을 하나의 체크리스트로 모으는 작업도 같은 원리입니다.

4. 보고 (Report)

에이전트가 디렉토리 트리(tree)를 읽을 수 있게 되면, 이를 요약할 수도 있습니다.

이 폴더를 탐색하여 INVENTORY.md를 작성하세요: 각 파일의 크기, 수정 날짜, 그리고 포함된 내용에 대한 한 줄 설명을 담은 표를 만드세요. 크기순으로 정렬하되, 가장 큰 파일이 먼저 오도록 하세요.

이것은 매우 가치 있는 작업입니다. 왜냐하면 출력물이 새로운 정보가 되기 때문입니다. 고객 인계(handoff)를 위한 매니페스트(manifest), 디스크 용량을 차지하는 가장 큰 파일 10개 목록, 또는 "2019년에 다운로드한 이 아카이브(archive)의 정체가 대체 뭐야?"라는 질문에 대한 빠른 답변이 될 수 있습니다. 에이전트는 읽고 쓰지만 원본은 전혀 변경하지 않으므로, 가장 안전하게 시작할 수 있는 작업이기도 합니다.

실제로 작동하는 작업을 작성하는 법

몇 가지 습관이 깔끔한 실행과 엉망진창인 결과를 가릅니다.

• 입력(input)과 출력(output)을 명시하세요. "내 파일들을 정리해줘"보다는 "이 폴더에 있는 PDF 파일들의 이름을 변경해줘"가 훨씬 낫습니다. 범위를 명확하게 지정하세요.
• 실행 전 계획을 요청하세요. "먼저 무엇을 할 것인지 보여줘" 또는 "드라이 런(dry run, 테스트 실행)만 수행해"라는 문구를 추가하세요. 목록을 검토한 다음 실행을 명령하세요.
• 예외 상황(edge cases)을 알려주세요. 중복된 이름, 누락된 날짜, 패턴과 일치하지 않는 파일 등을 언급하세요. 어떻게 처리할지 알려주지 않으면 에이전트는 추측하게 됩니다.
• 해당 폴더의 결과가 신뢰할 만해질 때까지는 이동(move)보다 복사(copy)를 선호하세요.

안전: 사람들이 건너뛰는 부분

이 에이전트는 실제 파일에 대해 실제 명령어를 실행합니다. 누군가에게 당신의 터미널(terminal) 권한을 넘겨주는 것처럼 취급하세요.

• 디렉터리 범위 지정 (Scope the directory). Claude Code를 실행할 때 홈 디렉터리가 아닌, 변경하고자 하는 폴더
  _내부_에서 시작하세요. 만약 에이전트가 ~/Downloads/sorting-test만 볼 수 있다면, 다른 곳으로 돌아다닐 수 없습니다.
• 되돌릴 수 있게 만들기 (Make it undoable). 파괴적인 작업을 실행하기 전에 해당 폴더에서 git init을 실행하거나, 폴더를 미리 복사해 두세요. 이름 변경이 잘못되더라도 슬퍼하는 대신 초기화할 수 있습니다.
• 승인하기 전에 읽기 (Read before you approve). 에이전트가 find ... -delete나 대량의 mv 명령어를 제안할 때, 실제로 내용을 읽으세요. 명령어 하나를 거절하는 데는 1초가 걸리지만, 삭제된 파일을 복구하는 데는 오후 전체를 허비할 수 있습니다.
• 한 번에 한 폴더씩 (One folder at a time). 작은 복사본으로 먼저 검증한 다음, 실제 대상에 적용하세요.

이것은 Claude에 국한된 편집증이 아닙니다. 당신이 한 줄 한 줄 직접 작성하지 않은 그 어떤 스크립트를 실행하기 전에도 가져야 할 동일한 주의사항입니다.

취약한 부분

고정된 패턴으로 매일 수행하는 작업의 경우, 다섯 줄짜리 셸 스크립트(shell script)나 Hazel/Automator 규칙을 만드는 것이 한 번 작성해 두면 더 빠르고 비용도 들지 않습니다. 에이전트는 매번 전체 과정을 다시 추론하며 그 과정에서 토큰(tokens)을 소비하기 때문입니다. 또한 에이전트는 확률적(probabilistic)입니다. 수천 개의 파일을 처리할 때 몇 개를 잘못 분류할 수 있으므로, 대규모 작업 시 보고(report) 단계나 드라이 런(dry run)은 선택이 아닌 필수입니다. 그리고 이름이나 카테고리를 결정하기 위해 파일
_내용(contents)_을 읽는 것은 강력하지만, 확장자 매칭보다 느리고 비용이 많이 듭니다. 판단이 모호하고 양이 사람이 처리할 만한 수준인 경우에 사용하세요. 규칙이 명확하고 지속적으로 실행되어야 하는 경우에는 실제 스크립트를 사용하세요.

가장 적합한 상황은 일회성으로 발생하는 지저분한 작업입니다. 스크립트를 짤 정도는 아니지만, 그렇다고 일일이 수동으로 클릭하며 정리하고 싶지는 않은 폴더 같은 경우 말이죠.

저는 AI를 채팅 장난감에서 실무 도구로 전환하는 것에 대해 글을 씁니다. 저는 실제 실습을 통해 Claude를 배우는 게임 기반 아카데미인 AGINE Academy를 구축하는 것을 돕고 있습니다. 이는 독립적인 제품이며 Anthropic과 관련이 없습니다.