변경 반경 캡: diff가 번지기 전에 묶을 세 줄

2026년 5월 17일 | 바이브코딩 Tips

---

코딩 에이전트의 diff는 파일 하나를 고치는 척하다가 옆 디렉터리로 번질 때가 있다. 처음에는 작은 버그 수정이었는데, 어느 순간 타입 이름을 바꾸고, 공통 유틸을 손대고, 테스트 fixture까지 새로 정리한다. 결과가 항상 나쁜 것은 아니다. 문제는 사람이 그 확장을 허락한 적이 없는데도, 작업이 스스로 넓어진다는 데 있다.

나는 예전에는 이 상황을 “프롬프트가 덜 구체적이었나” 정도로만 봤다. 그런데 여러 코딩 에이전트를 번갈아 쓰다 보니, 더 자주 필요한 것은 긴 지시문보다 변경 반경 캡이었다. 이번 작업의 중심 파일이 어디인지, 어디까지는 같이 고쳐도 되는지, 그 바깥으로 나가야 하면 어떤 말을 먼저 해야 하는지 세 줄로 묶어 두는 방식이다. 이 세 줄이 있으면 에이전트가 똑똑해지는 것은 아니지만, 똑똑한 척하며 판을 키우는 순간을 꽤 빨리 잡을 수 있다.

Figure 1. 변경 반경 캡은 중심 파일, 허용 반경, 확장 신호, 검증 증거를 한 줄 흐름으로 묶는 운영 장치다.

1. 파일 수 제한보다 확산 경로가 먼저다

“파일 세 개까지만 수정해” 같은 제한은 없는 것보다 낫다. 다만 파일 수만으로는 충분하지 않았다. 한 파일을 고쳐도 핵심 경로를 비틀 수 있고, 다섯 파일을 고쳐도 같은 컴포넌트 안의 안전한 정리일 수 있다. 그래서 나는 숫자보다 먼저 확산 경로를 본다.

• 중심 파일: 실제 문제가 관찰된 파일이나 화면을 하나 적는다.
• 인접 파일: 같이 열어도 되는 타입, 테스트, 작은 helper 범위를 적는다.
• 금지 경로: 설정, 인증, 데이터 마이그레이션, 공통 디자인 토큰처럼 건드리면 비용이 커지는 곳을 미리 닫는다.

이렇게 쓰면 “작게 고쳐라”보다 훨씬 덜 애매하다. 에이전트 입장에서도 어디까지가 자연스러운 추적이고 어디서부터가 새 작업인지 구분하기 쉬워진다. 사람 입장에서는 diff를 볼 때도 편하다. 변경된 파일 목록이 허용 반경 안에 있으면 내용 검토로 들어가고, 바깥으로 튀면 먼저 이유를 묻는다. 검토 순서가 짧아지는 셈이다.

2. 확장 요청은 실패가 아니라 정상 절차다

변경 반경을 묶는다고 해서 에이전트가 더 이상 넓게 보면 안 된다는 뜻은 아니다. 실제 코드베이스에서는 원인이 옆 레이어에 있는 경우가 많다. UI 버그처럼 보였는데 API 응답 shape가 달라졌거나, 테스트 실패처럼 보였는데 fixture 생성 규칙이 오래된 경우도 있다. 그래서 중요한 것은 확장을 막는 것이 아니라, 확장 요청을 절차로 만드는 것이다.

나는 보통 “허용 반경 밖 파일을 고쳐야 하면, 수정하지 말고 먼저 이유와 후보 파일만 보고하라”는 문장을 붙인다. 이 한 줄이 꽤 세다. 에이전트는 더 찾아볼 수 있지만, 바로 손대지는 못한다. 그러면 대화가 “이미 고쳤습니다”에서 “여기까지 보니 이 파일도 봐야 합니다”로 바뀐다. 작은 차이 같지만 실제로는 권한의 방향이 달라진다.

특히 컨텍스트가 길어졌거나, 앞선 시도에서 실패가 두 번 이상 난 세션에서는 이 규칙이 더 필요하다. 실패를 만회하려는 에이전트는 종종 수정 범위를 넓혀서라도 답을 만들려고 한다. 그때 반경 캡이 없으면 리팩터링이 해결책처럼 섞인다. 반대로 확장 요청 규칙이 있으면, 넓히는 순간이 작업의 새 경계로 표시된다.

3. 내가 실제로 쓰는 세 줄

반경 캡은 길게 쓰면 잘 안 쓴다. 나는 작업을 시작하기 전에 아래처럼 세 줄만 남기는 편이 제일 지속 가능했다.

중심: 실패가 보이는 파일 또는 화면 1개
허용: 같은 디렉터리의 관련 파일 2~3개와 해당 테스트까지만
확장: 그 밖의 파일 수정이 필요하면 먼저 이유와 예상 diff를 보고

여기서 핵심은 “예상 diff”다. 에이전트가 바깥 파일을 건드리기 전에 어떤 종류의 변경이 생길지 말하게 하면, 생각보다 많은 확장이 취소된다. 막상 말로 풀어 보면 “이건 지금 작업이 아니라 별도 정리”라는 게 드러나기 때문이다. 나도 이 과정에서 무릎을 친 적이 있다. 에이전트가 과감해서 문제가 아니라, 내가 확장의 이름을 안 붙여 줘서 문제였던 경우가 꽤 있었다.

세 줄에는 테스트도 붙인다. 허용 반경 안에서 고친 뒤 어떤 검증 증거를 남길지까지 정해야 한다. 단위 테스트 하나, 화면 캡처 하나, 변경 파일 목록 하나 정도면 충분하다. 증거가 없으면 작은 diff도 믿기 어렵고, 증거가 있으면 약간 넓은 diff도 판단할 수 있다. 반경 캡은 결국 수정 금지선이 아니라 판단 가능선을 만드는 장치에 가깝다.

반대로 이 세 줄이 없으면 리뷰가 이상하게 감정적으로 변한다. “왜 여기까지 고쳤지”라는 질문이 뒤늦게 나오고, 에이전트의 답은 대체로 그럴듯하다. 관련돼 보여서 고쳤고, 중복이 보여서 정리했고, 테스트가 깨져서 fixture를 손봤다는 식이다. 설명은 맞을 수 있지만, 허락된 작업인지는 별개다. 반경 캡은 바로 그 별개라는 사실을 세션 초반에 표시한다. 설명 가능한 변경과 허락된 변경을 구분해 두면, 리뷰어도 괜히 방어적으로 굴지 않고 diff를 볼 수 있다.

4. 모바일·웹 빌더에서는 더 작게 잡는다

모바일이나 웹 AI 빌더에서는 변경 반경이 더 잘 흐려진다. 화면을 보면서 자연어로 바로 고치다 보면, 버튼 간격을 고치려다 컴포넌트 구조가 바뀌고, 카드 하나를 정리하다가 라우팅이나 상태 저장 방식까지 건드리는 일이 생긴다. 프리뷰가 빠르게 뜨기 때문에 diff가 넓어진 사실을 늦게 알아차린다.

그래서 이런 도구에서는 반경을 더 작게 잡는 편이 낫다. 예를 들어 “이 카드 컴포넌트의 빈 상태 문구만 수정하고, 새 상태 관리나 라우팅 변경은 하지 않기”처럼 쓴다. 그리고 프리뷰 링크를 받을 때는 변경 파일 수와 미확인 영역을 같이 묻는다. 화면이 좋아졌다는 말만으로는 부족하다. 어떤 경로를 건드렸고, 어떤 경로를 일부러 안 건드렸는지가 같이 남아야 다음 사람이 이어받을 수 있다.

5. rollback 기준표와 다른 점

변경 반경 캡은 롤백 기준표와 닮았지만 위치가 조금 다르다. 롤백 기준표는 실패가 커질 때 되돌릴 조건을 잡는다. 변경 반경 캡은 그보다 앞에서, 실패가 커지기 전에 diff가 퍼지는 길을 먼저 좁힌다. 둘을 같이 쓰면 흐름이 꽤 단단해진다. 시작 전에는 반경을 묶고, 중간에는 확장 요청을 받으며, 종료 전에는 실제 변경·검증·남은 위험을 나눠서 본다.

이 구조를 쓰면 바이브코딩이 덜 답답해진다. 흔히 guardrail을 붙이면 속도가 느려질 것 같지만, 내 체감은 반대였다. 반경이 작으면 에이전트에게 맡길 수 있는 일이 오히려 늘어난다. 마음대로 넓어지지 않는다는 믿음이 생기기 때문이다. 사람도 매번 전체 diff를 의심하지 않고, 허용 반경 안쪽부터 차분히 보면 된다.

나는 코딩 에이전트에게 일을 맡길 때 “잘 고쳐 줘”보다 “여기 안에서 고쳐 줘”가 더 좋은 요청이라고 생각한다. 실력 있는 에이전트일수록 넓게 볼 수 있고, 넓게 볼 수 있다는 사실은 때로 위험이 된다. 변경 반경 캡은 그 능력을 줄이는 장치가 아니라, 이번 작업에서 그 능력이 쓰일 자리를 표시하는 장치다. diff가 번지기 전에 중심, 허용, 확장 세 줄만 남겨도 작업의 소음은 꽤 줄어든다.