Claude Code에게 파일 하나만 고치게 하는 지시문 작성법

“이 블로그 글 도입부, 좀 더 다듬어둬.”

제가 이렇게 입력한 건 금요일 밤 10시였습니다. 고쳐달라고 한 건 파일 하나의 첫 세 단락뿐이었어요. 그런데 다음 날 아침 차이(diff)를 열어보니 12개 파일이 바뀌어 있었습니다. 글 본문만이 아니라 공통 레이아웃, 태그 목록, 심지어 어째선지 공개 설정 파일까지요. 제대로 동작하는지 확인도 안 한 채, 저는 그대로 잠들어 버렸던 겁니다.

되돌리는 데 30분이 걸렸습니다. 뭐가 잘못됐을까요. Claude Code가 서툴렀던 게 아닙니다. 제 지시가 “어디까지 건드려도 되는지”를 한마디도 정해두지 않았기 때문에, 똑똑한 AI가 “도입부를 좋게 만든다 = 관련된 곳도 같이 정리한다”라고 알아서 챙겨준 것뿐이에요.

이 글에서는 그날 밤의 실패에서 만든 “파일 하나만 안전하게 고치게 하는 요청문”을, 그대로 복사해서 쓸 수 있는 형태로 드립니다. 범위를 좁게 정하고, 끝나면 스스로 검증하게 하고, 틀렸으면 되돌릴 수 있게 한다. 딱 이것만으로 한밤중의 사고는 거의 사라졌습니다.

핵심 요약

• AI에게 맡긴 작업이 폭주하는 건 모델이 나빠서가 아니라 건드려도 되는 범위를 적지 않았기 때문입니다.
• 요청문에는 “볼 파일”, “바꿀 파일”, “건드리지 말 것”, “확인 명령어”, “되돌리는 법” 다섯 가지를 반드시 넣습니다.
• 성공 보고를 받기 전에 검증 명령어를 꼭 실행시키면, 나중에 사람이 테스터가 되는 사고가 줄어듭니다.
• 블로그 수정, 버그 리포트 정리, 상품 문구 재작성처럼 멈출 지점이 분명한 작은 일부터 시작하세요.
• 범위를 좁혀도 글이나 결과물의 가치는 떨어지지 않습니다. 오히려 독자가 자기 환경에 옮겨 적용하기 쉬워집니다.

왜 “더 좋게 만들어줘”는 사고를 낼까

“더 좋게 만들어줘”라는 부탁에는 끝나는 선이 없습니다.

사람 편집자라면, 바쁜 금요일 밤에 이런 부탁을 받으면 “도입부 세 단락만이죠?”라고 되묻습니다. 하지만 AI는 확인 없이 곧장 달려나갈 수 있어요. 게다가 알아서 챙기는 데 능숙하다 보니 “도입을 좋게 만들 거면, 태그도 정리하고 관련 링크도 추가하는 게 친절하겠지”라며 멋대로 범위를 넓힙니다. 악의는 전혀 없습니다. 그게 가장 골치 아픈 점이죠.

여기서 효과를 발휘하는 게 지시 안에 “멈출 지점”을 적어두는 발상입니다. 프롬프트를 길고 정교한 문장으로 만들 필요는 없어요. 오히려 짧아도 됩니다. 대신, 건드려도 되는 파일과 건드리면 안 되는 파일을 처음에 분명히 나눠둔다. 이것만으로 폭주는 멈춥니다.

프롬프트 작성법 자체를 더 깊이 파고들고 싶은 분은 Claude Code 고급 프롬프트 설계도 함께 읽으면, 여기서 말하는 “범위를 좁힌다”가 다른 기법과 어떻게 이어지는지 보입니다.

요청문에 반드시 넣는 5가지

제가 지금 쓰는 요청문에는 반드시 이 다섯 가지가 들어갑니다. 순서에도 의미가 있어요.

항목	내용	이게 없으면 일어나는 일
볼 파일	상황 파악을 위해 읽어도 되는 범위	관계없는 곳까지 읽고 엉뚱한 수정을 한다
바꿀 파일	실제로 고쳐도 되는 1~2개 파일	12개 파일 사고가 난다
건드리지 말 것	설정·생성물·비밀 정보·공개 설정	지우면 안 되는 파일을 “정리”당한다
확인 명령어	변경 후에 실행할 검증 명령어 하나	망가진 채로 “완료했습니다”라고 보고된다
되돌리는 법	틀렸을 때 원래대로 돌리는 절차	복구에 30분이 걸린다

핵심은 편집을 시작하기 전에 먼저 “계획”을 한 번 답하게 하는 것입니다. 곧장 고치게 하지 않아요. “어떤 파일을 보고, 어느 걸 바꾸고, 만약 틀리면 무엇이 망가지는가”를 먼저 말하게 합니다. 여기서 엉뚱한 계획이 돌아오면 그 시점에 멈출 수 있어요. 고친 뒤에 알아차리는 것보다 훨씬 저렴합니다.

AI에게 맡길 범위와, 사람이 정할 범위

전부 AI에게 넘길 필요는 없습니다. 선은 이렇게 긋습니다.

AI에게 맡겨도 되는 부분

• 상황 파악을 위해 파일을 읽는다
• 변경 계획을 세우고 말로 정리한다
• 실제 문장이나 코드를 쓴다
• 검증 명령어를 실행하고 결과를 보고한다

사람이 쥐고 있어야 할 부분

• 어떤 파일을 변경 대상으로 삼을지 (범위 결정)
• 공개·운영 반영 버튼을 누를지
• 설정 파일이나 비밀 정보를 건드리는 판단
• 검증이 실패했을 때 공개를 멈추는 판단

이 선 긋기는 AI에게 처음 작업을 맡기는 사람일수록 중요합니다. 맡길 범위와 사람이 판단할 범위를 어떻게 나눌지는 비엔지니어를 위한 Claude Code 활용법에서도 기본 사고방식으로 나옵니다. 익숙하지 않을 때는 “읽기·쓰기는 AI, 지우기·공개하기는 사람” 정도의 거친 구분으로 충분합니다.

복사해서 쓰는 요청문 템플릿

그대로 붙여 넣고, 파일 이름만 자기 환경에 맞게 바꾸세요. PowerShell이든 bash든 변수에 문장을 담아 확인만 하면 됩니다.

brief=$(cat <<'EOF'
목적: 안전한 편집을 한 곳만 수행한다.
바꿔도 되는 파일: site/src/content/blog-ko/example.mdx
건드리지 말 것: package 계열 파일, 생성물, 비밀 정보, 공개·배포 설정.

편집을 시작하기 전에 다음을 답할 것:
1. 상황 파악을 위해 볼 파일
2. 실제로 바꿀 파일 1개
3. 그 변경이 틀렸을 경우 망가지는 것
4. 변경 후에 실행할 확인 명령어

편집을 마치면 다음을 답할 것:
- 차이(diff) 요약
- 확인 명령어의 실행 결과
- 원래대로 되돌리는 절차
EOF
)

echo "$brief"

이 문장은 화려하지 않습니다. 가치는 작업을 시작하기 전에 경계를 글자로 적어둘 수 있다는 점이에요. 파일 이름, 건드리지 말 것, 확인 명령어를 자기 저장소에 맞게 바꿔서 Claude Code에 건네세요. 좋은 계획이 돌아오면, 같은 제약을 한 번 더 말하게 한 다음 작업에 들어가게 합니다.

CLAUDE.md에 같은 제약을 적어두면, 매번 붙여넣지 않아도 자동으로 적용됩니다. 방법은 CLAUDE.md 베스트 프랙티스에 정리해 두었습니다.

끝나면 검증하게 하는 작은 스크립트

“완료했습니다”를 믿지 않는다. 이게 두 번째 기둥입니다.

편집이 끝난 뒤, 변경된 파일이 정말 하나뿐인지를 기계적으로 확인합니다. 아래 스크립트는 커밋되지 않은 변경 파일 수를 세서, 예상보다 많으면 멈추기만 하는 것입니다. 한국어 주석이 달려 있고 그대로 동작합니다.

#!/usr/bin/env bash
# 변경 파일이 하나뿐인지 확인한다. 너무 많으면 멈춘다.
set -e

# 예상하는 변경 파일 수 (한 파일 편집이면 1)
expected=1

# 커밋되지 않은 변경 파일 수를 센다
changed=$(git status --porcelain | grep -c .)

echo "변경된 파일 수: $changed (예상: $expected)"

if [ "$changed" -gt "$expected" ]; then
  echo "예상보다 많은 파일이 바뀌었습니다. 차이(diff)를 확인하세요."
  git status --porcelain
  exit 1
fi

echo "범위대로입니다."

이 스크립트를 요청문의 “확인 명령어”로 지정해 두면, AI는 스스로 실행해 결과를 보고하게 됩니다. 12개 파일이 바뀌어 있으면, 보고하는 시점에 빨간 글자가 뜹니다. 제가 아침에 일어나서 알아차리는 게 아니라, 그 자리에서 멈춥니다. 이게 효과적이에요.

검증이나 매일의 작업 흐름을 더 자동화하고 싶은 분은 Claude Code 생산성 향상 팁에 다른 패턴도 정리해 두었습니다.

이런 상황에서 효과적이다 (3가지)

모두 “멈출 지점”이 분명한 일입니다. 거꾸로 말하면, 멈출 지점이 보이지 않는 일은 아직 AI에게 통째로 맡기지 않는 게 좋다는 신호예요.

1. 블로그 도입부 리라이트 바꾸는 건 파일 하나의 도입부뿐, 이라고 처음에 적습니다. 대상 독자와 검증 명령어도 곁들여요. 이러면 본문 전체나 레이아웃으로 손이 뻗지 않습니다. 제 12개 파일 사고는, 딱 이 한 줄만 있었어도 일어나지 않았습니다.

2. 버그 리포트 정리 로그 파일과 템플릿 하나만 보여주고, “관계없는 코드의 정리는 금지”라고 적습니다. 리포트를 다듬는 작업에 딸려서 리팩터링까지 되면, 리뷰가 단숨에 무거워집니다. 보여주는 범위를 좁히면 출력도 좁힐 수 있어요.

3. 상품 페이지 문구 테스트 페이지 전체 재작성이 아니라 “카피 한 안”과 “변경 후의 모양 확인”만 요구합니다. 범위가 한 안으로 고정되어 있으니, A/B로 시험할 때도 비교가 편합니다.

자주 묻는 질문

Q. 매번 이 긴 요청문을 붙여넣는 건 번거롭지 않나요? 자주 쓰는 제약은 CLAUDE.md에 적어두면 매번 붙여넣지 않아도 적용됩니다. 붙여넣는 건 “이번에 건드려도 되는 파일 이름”만으로 끝나게 돼요.

Q. 범위를 좁히면 AI의 장점을 죽이는 거 아닌가요? 반대였습니다. 범위가 좁을수록 AI는 헤매지 않고 깊게 고쳐줍니다. 넓은 지시는 “어디부터 손댈지”에서 헤매게 만들 뿐이에요.

Q. 검증 명령어는 뭘 넣으면 되나요? 처음에는 “변경 파일 수 체크”만으로 충분합니다. 익숙해지면 빌드가 통과하는지, 테스트가 깨지지 않는지, 끊긴 링크가 없는지를 한 명령어씩 더해갑니다.

Q. 그래도 예상 밖의 파일이 바뀌면요? 되돌리는 법을 요청문에 적어뒀다면, 그 절차로 되돌리기만 하면 됩니다. git restore . 같은 되돌리기 명령어를 처음부터 지시문에 넣어두는 게 요령이에요.

Q. 어디서부터 시작하면 좋을까요? 실패해도 되돌릴 수 있는 작은 일을 하나 고르세요. 초안 글 수정이나 문구 교체가 적당합니다. 기본 조작이 불안하면 Claude Code 입문 가이드부터 시작하면 바탕이 다져집니다.

실제로 해본 결과

그 12개 파일 사고 이후, 저는 요청문을 반드시 “바꿀 파일”, “건드리지 말 것”, “확인 명령어”를 붙여서 쓰게 됐습니다.

검증 스크립트를 “확인 명령어”로 지정한 뒤로, 예상 밖의 파일이 섞이는 경우는 그 자리에서 멈추게 됐어요. 실제로 지난주에도 상품 페이지 문구를 고치게 했을 때, AI가 공통 컴포넌트까지 손을 뻗으려 했지만, 변경 파일 수가 2가 된 시점에 스크립트가 빨간 글자를 띄우며 멈췄습니다. 아침에 일어나 차이를 보고 새파랗게 질리는 일이 없어졌어요.

또 하나 확인한 건, 범위를 좁혀도 출력 품질이 떨어지지 않는다는 점입니다. “도입부 세 단락만”이라고 묶은 날이 오히려 더 정확한 수정이 돌아왔어요. 똑똑한 AI에게 넓게 맡기기보다, 좁게 부탁하고 스스로 검증하게 한다. 돌아가는 것처럼 보여도 이게 저에게는 가장 빠르다, 라는 게 지금의 결론입니다.

회사 업무에서 AI에게 편집이나 운영을 맡기는 구조를 갖추고 싶다면, 연수·도입 상담에서 구체적인 절차부터 함께 짤 수 있습니다. 우선 여러분 손으로, 파일 하나만의 요청문을 한 번 시험해 보세요.

참고로, 여기서 쓴 도구의 공식 정보는 Claude Code 공식 문서에 있습니다.