AI에게 대규모 리네임(Rename)을 통째로 맡기지 마라 — 인간과 AI의 책임 분담으로 안전하게 치환하기

수백 파일 규모의 기계적 리네임(식별자·파일명·디렉토리명 일괄 치환)을 Claude Code와 함께 사고 제로·되돌리기 제로로 완료했다.

포인트는 하나. AI에게 무엇이든 시키지 않는 것이다.

sed를 통한 파괴적 치환 → 인간이 수동 실행

git mv와 git grep / find를 통한 검증 → AI가 실행

이것만으로도 AI 코딩 에이전트와의 대규모 리네임은 극적으로 안전해진다.

• 부분 일치로 인해 의도하지 않은 부분까지 치환됨 (OldName을 치환했더니 OldNameExtra까지 망가짐)
• 문자열 리터럴 'oldname'과 같이 의미를 가진 값까지 식별자와 함께 바꿔버림
• PascalCase는 수정했지만 camelCase / kebab-case는 놓침
• "완료했습니다"라고 말했지만 grep 해보니 수십 건이 남아 있음

파괴적 변경을 한꺼번에 실행하는 성질과 검증을 소홀히 하는 성질이 곱해져 사고가 발생한다.

설계서(무엇을 무엇으로 바꿀 것인가·PR 스코프의 경계)와 구현 계획서(AI가 실행할 수 있는 입도(granularity)의 단계)로 나눈다. 인간이 리뷰하고 합의한 후에 AI에게 넘긴다.

조작	담당
sed 일괄 치환	인간 (수동)
git mv	AI
git grep / find를 통한 검증	AI
타입 체크·테스트	인간 (수동)

이번 내 프로젝트에서는 Claude Code의 샌드박스(Sandbox) 모드를 채택했기 때문에, 파괴적인 커맨드는 애초에 AI가 실행할 수 없다.

다만, 이것은 어디까지나 보험으로서 기능하는 것이며, 중요한 것은 구체적으로 어떤 절차로 AI가 무엇을 하는지가 명시적으로 되어 있다는 점에 초점을 맞추어 사양서를 작성했다는 것이다.

1. AI: 「Phase X / Step Y: 〇〇의 치환」이라며 sed 커맨드를 제시
2. 인간: 수동 실행 후 완료 보고
3. AI: git grep으로 검증
...

포인트는 AI가 할 일뿐만 아니라, 하지 않을 일을 인간(개발자)이 실행한다고 명시함으로써 오작동을 방지하는 것이다.

# ✅ 긴 쪽을 먼저
sed -i '' 's/OldFooBar/NewFooBar/g' file.ts
sed -i '' 's/OldFoo/NewFoo/g' file.ts

역순이면 긴 패턴이 망가진다.

식별자(뒤에 영문자가 이어지는 경우)만 치환하고 싶다면 정규 표현식(Regular Expression)으로 범위를 좁힌다.

sed -i '' "s/oldname\([A-Za-z]\)/newname\1/g" file.ts

이렇게 하면 oldnameUser → newnameUser로는 바뀌지만, 'oldname' 리터럴은 남는다.

"실행했다"는 말로 AI가 만족하지 않도록, 무엇이 나오면 OK인지 코멘트로 작성한다.

git grep -c 'OldRelationName' -- 'packages/foo/**/*.ts'
# 기대값: 0

find packages/foo -type f -name "*.ts" \
! -name 'legacy-component.tsx' \
-exec sed -i '' 's/OldName/NewName/g' {} +

DB 계층·백엔드 계층·프론트엔드 계층을 별도의 커밋으로 나눈다고 미리 결정해 두면 리뷰의 인지 부하가 단번에 낮아진다.

인간에게도 일정 수준의 주도권을 부여한 AI 주도 개발(AI-driven development)을 수행할 때는,

• 사양서와 계획서를 먼저 작성한다
• 파괴적 조작은 인간, git 조작과 검증은 AI
• 스텝 루프(Step loop)로 진행한다

이것만으로도 유능하지만 파괴 행위는 하지 않는 역할로서 AI가 기능한다. 샌드박스 제한은 방해가 아니라, 안전장치로서 적극적으로 사용한다는 관점을 전제로 두어야 함을 배웠다.