건드리지 않을 파일 먼저 적기

2026년 6월 15일 | 바이브코딩 Tips

---

작은 버그를 에이전트에게 맡길 때 diff가 커지는 순간은 대개 “여기는 그대로 두라”는 말이 빠진 때였다. 나는 한 파일의 파싱 오류만 고치고 싶었는데, 에이전트는 근처 설정 파일을 정리하고, 테스트 이름을 바꾸고, 잠깐 읽은 문서까지 손본다. 결과가 운 좋게 통과하면 그냥 넘어가기 쉽지만, 나중에 보면 문제는 수정 능력이 아니라 수정하지 않을 표면을 먼저 고정하지 않은 것에 가까웠다.

그래서 요즘은 작업을 맡기기 전에 “고쳐야 할 파일”만 쓰지 않고, “건드리지 않을 파일”도 같이 적는다. 이건 에이전트에게 겁을 주는 문장이 아니다. 오히려 반대에 가깝다. 바꿀 수 있는 곳과 읽기만 할 곳을 분리해 주면, 에이전트는 불필요하게 전체 구조를 개선하려고 애쓰지 않아도 된다. 사람 입장에서도 완료 보고를 볼 때 “왜 이 파일까지 바뀌었지”라는 질문을 늦게 하지 않게 된다.

허용 목록만으로는 부족한 순간

처음에는 허용 파일 목록만 있으면 충분하다고 생각했다. 예를 들면 “parser.py와 parser_test.py만 고쳐줘”라고 쓰는 식이다. 그런데 실제 작업에서는 에이전트가 다른 파일을 직접 수정하지 않더라도, 그 파일들을 읽고 나서 넓은 리팩터링 제안을 만들 때가 있다. 특히 타입 정의, 설정 파일, 생성 산출물, snapshot 파일이 근처에 있으면 “이것도 정리하면 좋다”는 방향으로 쉽게 번진다.

허용 목록은 작업의 중심을 잡아 주지만, 보존 목록은 작업의 경계를 잡아 준다. 둘은 역할이 다르다. 허용 목록만 있으면 에이전트는 “주로 여기를 고치면 된다”고 이해한다. 보존 목록까지 있으면 “여기는 현재 문제를 이해하기 위해 읽을 수는 있지만, 이번 diff에 들어오면 안 된다”고 이해한다. 이 차이가 긴 세션에서는 꽤 크다.

내가 쓰는 세 칸

형식은 복잡하게 만들 필요가 없었다. 나는 보통 작업 요청 맨 위에 세 칸만 둔다.

수정 가능: src/parser.py, tests/test_parser.py
읽기만 가능: docs/format.md, examples/sample-input.json
수정 금지: generated/schema.json, package-lock.json, snapshots/*.snap

이 세 줄을 넣으면 요청문의 성격이 조금 바뀐다. “버그를 고쳐줘”가 아니라, 어떤 표면에서만 버그를 고칠 수 있는지가 같이 전달된다. generated 파일이나 lockfile처럼 한 번 바뀌면 검토 비용이 큰 파일은 특히 수정 금지 칸에 넣어 두는 편이 낫다. snapshot도 마찬가지다. snapshot을 바꾸면 테스트는 초록색이 될 수 있지만, 실제로는 기대 동작을 바꾼 것인지 구현을 고친 것인지 헷갈릴 때가 많다.

읽기만 가능 칸도 생각보다 중요하다. 에이전트가 문서를 보지 못하면 맥락이 부족해지고, 문서를 수정할 수 있으면 작업이 넓어진다. 그래서 나는 “문서는 읽어도 되지만 이번 diff에는 넣지 말아 달라”는 식으로 분리한다. 이러면 에이전트가 근거를 찾을 길은 남기면서도, 결과물의 변경 범위는 작게 묶을 수 있다.

수정 금지 칸에 자주 들어가는 파일은 대체로 비슷하다. 자동 생성 schema, lockfile, migration 파일, snapshot, 큰 JSON fixture, 이미 승인된 문구가 들어간 문서다. 이 파일들은 한 줄만 바뀌어도 리뷰 맥락이 달라진다. 특히 lockfile은 의존성 업데이트 의도가 없는데도 바뀌면 “버그 수정”이 “환경 변경”처럼 보인다. migration은 더 조심스럽다. 한 번 섞이면 실제 데이터 구조를 바꾸려는 의도였는지, 테스트를 맞추려던 임시 수정이었는지 나중에 분리하기 어렵다.

반대로 수정 가능 칸은 일부러 좁게 쓴다. 처음부터 관련 파일을 다 열어 두면 에이전트가 전체 구조를 다시 설계하려고 한다. 나는 보통 실패가 직접 보이는 파일 하나, 그 파일을 검증하는 테스트 하나, 필요하면 아주 가까운 helper 하나 정도만 연다. 더 필요하면 중간 보고를 받는다. 이렇게 해도 느려지기보다 오히려 빠른 경우가 많았다. 리뷰해야 할 diff가 줄고, 되돌릴 때도 어느 선부터 잘라야 하는지 분명해지기 때문이다.

완료 보고에서 바로 걸러지는 것

이 방식의 장점은 작업 중보다 작업 끝에서 더 잘 보인다. 완료 보고를 받을 때 바뀐 파일 목록을 세 칸과 대조하면 된다. 수정 가능 칸 안에서만 바뀌었으면 다음은 테스트 결과를 보면 된다. 읽기만 가능 칸이 바뀌었다면 이유를 물어야 한다. 수정 금지 칸이 바뀌었다면, 그 순간 결과가 좋아 보여도 일단 멈추는 편이 안전하다.

나는 이걸 작은 체크리스트처럼 쓴다. 에이전트가 “테스트 통과”라고 말해도, 먼저 바뀐 파일 목록을 본다. 통과 여부보다 앞에 놓는 이유는 간단하다. 테스트가 통과해도 변경 반경이 약속 밖으로 나갔다면 그건 다른 작업이 섞인 것이다. 이때는 성급하게 merge하지 않고, 금지 파일 변경을 되돌리거나 별도 작업으로 분리한다. 초록 로그가 변경 범위까지 보증해 주지는 않는다.

처음부터 완벽한 목록일 필요는 없음

물론 처음부터 수정 금지 목록을 완벽하게 알 수는 없다. 작업을 하다 보면 정말로 다른 파일을 고쳐야 하는 경우도 있다. 그래서 나는 금지 목록을 절대 규칙이라기보다 확장 요청 기준으로 둔다. 에이전트가 금지 파일을 손대야 한다고 판단하면, 바로 수정하지 말고 “왜 필요한지, 어떤 줄이 바뀔지, 대안은 무엇인지”를 먼저 보고하게 하는 식이다.

이렇게 하면 작업이 막히기보다 의사결정 지점이 선명해진다. 파일을 하나 더 여는 것이 새 버그 수정인지, 리팩터링인지, 테스트 기대값 변경인지 구분할 수 있다. 특히 자동 생성물이나 lockfile이 끼어 있는 작업에서는 이 구분이 중요하다. 한 번 잘못 들어간 변경은 나중에 리뷰에서 잡기도 귀찮고, 되돌릴 때도 다른 diff와 엉켜서 비용이 커진다.

작은 요청을 정말 작게 유지하기

바이브코딩에서 “작게 맡기기”는 단순히 프롬프트를 짧게 쓰는 일이 아니었다. 짧은 요청이라도 경계가 없으면 에이전트는 주변을 넓게 만진다. 반대로 요청문이 조금 길어져도 수정 가능, 읽기만 가능, 수정 금지가 나뉘어 있으면 diff는 작아진다. 나는 이쪽이 훨씬 편했다.

작은 버그 하나를 맡길 때도 건드리지 않을 파일을 먼저 적어 두면, 완료 보고를 읽는 기준이 생긴다. 어떤 파일을 고쳤는지, 어떤 파일은 참고만 했는지, 어떤 파일은 그대로 남아야 하는지가 작업 전부터 보인다. 결국 에이전트에게 필요한 건 더 많은 자유가 아니라, 이번 작업에서 자유롭게 움직여도 되는 바닥의 크기다. 그 바닥을 먼저 그어 두면 작은 작업은 정말 작게 끝날 가능성이 높아진다.