코드 수정 요청하기

🎯 학습 목표

4강에서 클로드 코드가 파일을 고치는 원리를 배웠다면, 이번 강에서는 원하는 결과를 얻기 위해 무엇을 어떻게 요청할지를 배웁니다. 같은 클로드 코드라도 요청을 어떻게 쓰느냐에 따라 한 번에 끝나는 작업이 되기도 하고, 몇 번씩 되돌리는 작업이 되기도 합니다.

• 모호한 요청과 구체적인 요청의 차이를 알고, 모호한 요청을 구체적인 요청으로 바꿔 쓸 수 있습니다.
• 수정할 파일·범위·하지 말아야 할 것을 지정해 의도치 않은 변경을 막을 수 있습니다.
• 기존 코드의 패턴을 참조시켜 프로젝트 스타일에 맞는 코드를 얻을 수 있습니다.
• 테스트·빌드 같은 검증 기준을 요청에 포함하고, 결과를 증거로 확인할 수 있습니다.

이 강의 예시는 공식 문서 Best practices for Claude Code에 실린 원칙을 바탕으로, 한국어 실무 상황에 맞게 풀어 쓴 것입니다.

🔍 모호한 요청 vs 구체적인 요청

이 섹션에서는 요청의 구체성이 왜 결과를 좌우하는지 원리부터 살펴보겠습니다.

공식 문서는 "Claude는 의도를 추론할 수 있지만 마음을 읽을 수는 없다"고 말합니다. "로그인 버그 고쳐 줘"라는 요청을 받으면 클로드 코드는 어떤 버그인지부터 추측해야 합니다. 추측이 틀리면 엉뚱한 곳을 고치고, 맞더라도 원인을 찾느라 많은 파일을 읽으며 시간과 컨텍스트를 소모합니다. 컨텍스트는 대화·읽은 파일·명령 출력이 모두 담기는 작업 기억 공간인데, 공식 문서는 이 공간이 채워질수록 성능이 떨어지므로 가장 중요하게 관리해야 할 자원이라고 강조합니다.

공식 문서가 제시하는 구체화 전략 네 가지를 한국어 예시로 옮기면 다음과 같습니다.

전략	모호한 요청	구체적인 요청
범위 지정 파일·시나리오·테스트 방식	foo.py에 테스트 추가해 줘	foo.py에 사용자가 로그아웃된 경우의 엣지 케이스 테스트를 작성해 줘. 목(mock)은 쓰지 마.
출처 지목 답을 줄 수 있는 곳	ExecutionFactory API는 왜 이렇게 이상해?	ExecutionFactory의 git 기록을 살펴보고 API가 어떻게 지금 형태가 됐는지 요약해 줘.
기존 패턴 참조	캘린더 위젯 추가해 줘	홈 화면의 기존 위젯 구현 방식을 보고, HotDogWidget.php를 예시로 삼아 같은 패턴으로 월 선택 캘린더 위젯을 만들어 줘. 이미 쓰는 라이브러리 외에는 추가하지 마.
증상 설명 증상·위치·완료 기준	로그인 버그 고쳐 줘	세션 타임아웃 후 로그인이 실패한다는 제보가 있어. src/auth/의 인증 흐름, 특히 토큰 갱신을 확인해 줘. 문제를 재현하는 실패 테스트를 먼저 쓰고 고쳐 줘.

표의 오른쪽 요청에는 공통점이 있습니다. 어디를(파일·폴더), 무엇을(증상·목표), 어떻게 확인할지(테스트·완료 기준)가 들어 있습니다. 이 세 요소를 요청 작성의 기본 틀로 기억하세요.

그렇다고 모호한 요청이 항상 나쁜 것은 아닙니다. 공식 문서도 탐색 단계에서는 "이 파일에서 개선할 점이 뭐야?" 같은 열린 질문이 내가 생각하지 못한 문제를 드러내 줄 수 있다고 설명합니다. 핵심은 탐색할 때는 열린 질문, 수정할 때는 구체적인 요청으로 구분해 쓰는 것입니다.

📐 변경 범위와 스타일 지정하기

이 섹션에서는 클로드 코드가 필요 이상으로 많이 고치지 않도록 범위를 좁히고, 프로젝트 스타일을 따르게 하는 방법을 살펴보겠습니다.

AI에게 코드를 맡길 때 현장에서 가장 자주 나오는 불만은 "하나만 고쳐 달라고 했는데 여기저기 다 바꿨다"입니다. 클로드 코드는 요청을 잘 수행하려고 관련 있어 보이는 부분까지 정리하려는 경향이 있을 수 있습니다. 이를 막는 가장 확실한 방법은 허용 범위와 금지 사항을 명시하는 것입니다.

src/utils/price.js의 calculateDiscount 함수만 수정해 줘.
할인율이 0~100 범위를 벗어나면 에러를 던지도록 바꿔 줘.
함수 이름과 매개변수는 바꾸지 말고, 다른 파일은 건드리지 마.
기존 에러 처리는 src/utils/validate.js의 방식을 따라 줘.

첫 줄은 파일과 함수 단위로 범위를 고정합니다. 둘째 줄은 원하는 동작을 명확한 조건으로 적습니다. 셋째 줄은 하지 말아야 할 것을 적어 호출하는 쪽 코드가 깨지는 일을 막습니다. 넷째 줄은 기존 패턴을 지목해, 새로 만든 에러 처리 방식이 프로젝트의 다른 코드와 어긋나지 않게 합니다.

스타일 지시에서 기억할 점은 "깔끔하게 짜 줘"처럼 추상적인 표현보다 본보기 파일을 지목하는 편이 훨씬 효과적이라는 것입니다. 사람도 "좋게 써 줘"보다 "이 문서처럼 써 줘"라는 말을 더 정확히 이해하는 것과 같습니다. @로 파일을 지정하면 클로드 코드가 답하기 전에 그 파일을 읽습니다.

매번 반복하는 스타일 규칙(예: "import는 ES 모듈 문법 사용")은 요청마다 적지 말고 프로젝트 지시서인 CLAUDE.md에 적어 두는 것이 좋습니다. 공식 문서는 CLAUDE.md를 매 대화 시작 시 읽는 파일이라고 설명하며, 작성법은 14강에서 자세히 다룹니다.

변경이 크거나 방법이 확실하지 않을 때는 플랜 모드를 씁니다. Shift+Tab을 눌러 상태 표시줄에 ⏸ plan mode on이 보이면, 클로드 코드는 파일을 바꾸지 않고 읽고 계획만 세웁니다. 계획을 검토하고 승인한 뒤 구현에 들어가면 엉뚱한 문제를 푸는 일을 줄일 수 있습니다. 반대로 공식 문서는 오타 수정이나 변수 이름 변경처럼 변경 내용을 한 문장으로 설명할 수 있다면 계획은 건너뛰라고 권합니다.

✅ 수정 결과 검증하기: 확인할 수단을 함께 준다

이 섹션에서는 수정 결과를 믿을 수 있게 만드는 가장 강력한 방법인 검증 기준 제공을 살펴보겠습니다.

공식 문서는 이렇게 설명합니다. Claude는 작업이 끝난 것처럼 보이면 멈춥니다. 실행해 볼 확인 수단이 없으면 "끝난 것처럼 보인다"는 것이 유일한 신호이고, 결국 사람이 검증 루프가 되어 모든 실수를 직접 찾아내야 합니다. 반대로 통과·실패를 알려 주는 수단을 주면 Claude가 작업하고, 확인하고, 결과를 읽고, 통과할 때까지 반복하는 루프가 스스로 닫힙니다.

상황	검증 없는 요청	검증을 포함한 요청
함수 구현	이메일 검증 함수 만들어 줘	validateEmail 함수를 만들어 줘. user@example.com은 true, invalid는 false, user@.com은 false여야 해. 구현 후 테스트를 실행해 줘.
빌드 오류	빌드가 실패해	빌드가 이 에러로 실패해: [에러 붙여넣기]. 고친 뒤 빌드가 성공하는지 확인해 줘. 에러를 숨기지 말고 근본 원인을 해결해 줘.
화면 수정	대시보드 더 예쁘게 해 줘	[스크린샷 붙여넣기] 이 디자인대로 구현하고, 결과 스크린샷을 원본과 비교해 차이점을 나열한 뒤 고쳐 줘.

빌드 오류 예시의 "에러를 숨기지 말고"라는 문장은 특히 중요합니다. 검증 기준만 주면 테스트를 통과시키기 위해 검사를 꺼 버리거나 예외를 삼키는 식으로 증상만 없애는 수정이 나올 수 있기 때문입니다.

또 하나의 습관은 성공했다는 말 대신 증거를 요구하는 것입니다. 공식 문서는 테스트 출력, 실행한 명령과 그 결과, 결과 화면 스크린샷을 보여 달라고 하라고 권합니다. 증거를 검토하는 것이 직접 다시 실행하는 것보다 빠르기 때문입니다. 마지막으로 4강에서 배운 대로 git diff로 실제 바뀐 줄을 확인하는 것까지가 검증입니다.

⚠️ 자주 하는 실수와 바로잡는 법

이 섹션에서는 코드 수정을 요청할 때 현장에서 반복되는 실수와, 공식 문서가 제시하는 해결책을 살펴보겠습니다.

첫째, 같은 문제를 계속 고쳐 달라고 하는 경우입니다. 결과가 틀려서 지적하고, 또 틀려서 다시 지적하는 일이 반복되면 컨텍스트가 실패한 시도들로 오염됩니다. 공식 문서는 같은 문제로 두 번 넘게 바로잡았다면 /clear로 대화를 비우고, 그동안 알게 된 내용을 반영한 더 구체적인 요청으로 새로 시작하라고 권합니다. 깨끗한 세션에 좋은 요청 하나가 수정이 누적된 긴 세션보다 거의 항상 낫다는 것입니다.

둘째, 그럴듯해 보여서 믿는 경우입니다. 구현은 멀쩡해 보이지만 엣지 케이스를 처리하지 못하는 일이 흔합니다. 공식 문서의 결론은 단호합니다. 테스트·스크립트·스크린샷으로 검증할 수 없다면 배포하지 말라는 것입니다.

셋째, 범위 없는 조사를 맡기는 경우입니다. "이거 조사해 봐"라고만 하면 수백 개 파일을 읽으며 컨텍스트를 채울 수 있습니다. 조사 대상 폴더나 질문을 좁혀서 요청하세요.

넷째, 한 번에 너무 큰 작업을 맡기는 경우입니다. 여러 단계가 필요한 기능은 번호를 붙여 단계별로 요청하거나, 플랜 모드로 계획을 먼저 세운 뒤 단계마다 확인하며 진행하는 편이 안전합니다. 실무에서 바로 쓸 수 있는 요청 틀을 정리하면 다음과 같습니다.

[목표] 무엇을 바꾸고 싶은지, 왜 필요한지
[위치] 수정할 파일·함수, 참고할 기존 코드(@파일)
[제약] 바꾸면 안 되는 것, 쓰면 안 되는 라이브러리
[검증] 실행할 테스트·빌드 명령과 통과 기준, 결과 증거 제시

📝 핵심 요약

• ☐ 요청에는 어디를·무엇을·어떻게 확인할지를 담습니다. 탐색은 열린 질문, 수정은 구체적 요청으로 구분합니다.
• ☐ 범위와 금지 사항을 명시하고, 스타일은 추상적 표현 대신 본보기 파일을 지목합니다.
• ☐ 방법이 불확실하거나 여러 파일이 바뀌면 플랜 모드, 한 문장으로 설명되는 변경은 바로 요청합니다.
• ☐ 테스트·빌드·스크린샷 같은 검증 수단을 주고, 성공 선언이 아닌 증거를 요구합니다.
• ☐ 같은 문제로 두 번 넘게 바로잡았다면 /clear 후 더 나은 요청으로 다시 시작합니다.

다음 6강에서는 클로드 코드가 테스트·빌드·패키지 설치 같은 터미널 명령을 어떻게 실행하는지, 그리고 명령 실행 권한을 안전하게 다루는 방법을 살펴보겠습니다.

📚 참고 자료

• Best practices for Claude Code — Claude Code Docs (Anthropic)
• Choose a permission mode — Claude Code Docs (Anthropic)
• Common workflows — Claude Code Docs (Anthropic)