도구 계약서: 실행 전에 허용 범위 묶기

2026년 4월 30일 | 바이브코딩 Tips

---

코딩 에이전트에게 파일 수정 권한을 열어 줄 때 제일 무서운 순간은 모델이 틀릴 때가 아니라, 무엇까지 해도 되는지 모르는 채로 부지런해질 때다. 한두 줄 고쳐 달라고 했는데 설정 파일까지 만지고, 테스트 하나 통과시키려다 데이터 생성 경로를 바꾸고, “아마 이게 맞을 것 같아서”라는 분위기로 여러 파일을 한꺼번에 고치는 식이다. 나는 이런 장면을 몇 번 겪고 나서 프롬프트를 더 길게 쓰는 쪽보다, 실행 전에 작은 도구 계약서를 먼저 쓰는 쪽으로 습관을 바꿨다.

여기서 말하는 도구 계약서는 거창한 문서가 아니다. 에이전트에게 이번 작업에서 열어 줄 도구, 건드려도 되는 파일 범위, 수정 전에 보여야 하는 근거, 중단해야 하는 조건을 짧게 묶은 표에 가깝다. 자연어 프롬프트가 “무엇을 원한다”에 가깝다면, 도구 계약서는 “어떤 방식으로 움직이면 안 되는가”까지 같이 적어 두는 안전핀이다.

바이브코딩을 하다 보면 속도가 주는 착시가 있다. 에이전트가 빠르게 읽고, 빠르게 고치고, 빠르게 테스트까지 돌리면 일이 잘 굴러가는 것처럼 보인다. 그런데 실제로는 빠른 실행보다 더 먼저 봐야 하는 게 권한의 모양이다. 같은 에이전트라도 읽기만 허용된 상태, 한 파일만 수정 가능한 상태, 저장소 전체를 바꿀 수 있는 상태는 완전히 다른 작업자처럼 행동한다.

Figure 1: 실행 전에 목표, 범위, 근거, 중단 조건을 먼저 묶어 두는 도구 계약서 흐름.

그림의 핵심은 순서다. 작업 목표를 적은 뒤 바로 “해 줘”로 넘기지 않고, 허용 범위와 증거 요구와 중단 조건을 앞에 세운다. 이 네 칸이 잡히면 에이전트가 똑똑해지는 것은 아니지만, 엉뚱한 방향으로 멀리 달릴 확률은 확실히 줄어든다. 나는 이 차이를 꽤 크게 본다.

1. 프롬프트보다 아래에 있는 계약

예전에는 작업 프롬프트 안에 모든 걸 넣으려고 했다. “이 파일을 보고, 이 테스트를 돌리고, 위험한 수정은 하지 말고, 변경 이유를 설명해 줘.” 이렇게 쓰면 그 순간에는 충분해 보인다. 문제는 세션이 길어질수록 이 문장이 점점 배경음처럼 밀린다는 점이다. 에이전트는 당장의 실패 로그, 직전 수정, 최근에 읽은 파일 쪽으로 끌려가고, 처음의 운영 조건은 흐려지기 쉽다.

그래서 나는 계약을 프롬프트보다 아래, 즉 작업 실행 규칙에 가까운 곳에 둔다. 완전히 자동화된 hook이나 guardrail로 묶을 수 있으면 가장 좋지만, 매번 그렇게 세팅할 수는 없다. 그럴 때라도 대화 맨 앞에 작업 계약 블록을 고정해 두면 효과가 있다. 에이전트에게 “좋은 답을 내라”가 아니라 “이 울타리 안에서만 움직여라”라고 말하는 셈이다.

이 감각은 내가 예전에 정리했던 hooks 가드레일과 이어진다. 훅은 반복 규칙을 실제 이벤트에 묶는 방식이고, 도구 계약서는 그보다 가벼운 수동 버전이다. 둘 다 핵심은 같다. 기억에 기대는 약속을 줄이고, 실행 직전에 확인 가능한 경계를 늘리는 쪽이다.

2. 내가 자주 쓰는 다섯 칸

도구 계약서를 너무 복잡하게 만들면 안 쓴다. 나는 보통 다섯 칸만 둔다. 목표, 읽기 범위, 수정 범위, 근거, 중단 조건이다. 작업이 작으면 한 문단으로 충분하고, 조금 위험하면 표로 쓴다. 중요한 건 예쁘게 문서화하는 게 아니라, 에이전트가 다음 행동을 고를 때 벗어나면 안 되는 선을 바로 볼 수 있게 하는 것이다.

칸	적는 내용	막아 주는 실패
목표	이번 작업의 성공 상태를 한 문장으로 적는다.	에이전트가 주변 개선으로 새는 문제
읽기 범위	먼저 봐야 할 파일, 로그, 문서 범위를 좁힌다.	근거 없이 바로 수정하는 문제
수정 범위	바꿔도 되는 파일과 금지 영역을 나눠 쓴다.	설정, 인증, 데이터 경로까지 번지는 문제
근거	수정 전에 실패 로그나 읽은 위치를 짧게 인용하게 한다.	그럴듯한 추측으로 고치는 문제
중단 조건	몇 번 실패하면 멈추고 질문하거나 handoff할지 정한다.	실패를 덮기 위해 더 크게 뜯는 문제

특히 수정 범위와 중단 조건은 같이 둬야 한다. 수정 범위만 있으면 에이전트가 그 안에서 계속 파고들 수 있고, 중단 조건만 있으면 무엇을 건드려도 되는지 애매하다. 둘을 같이 적어야 “여기까지 해 보고 안 되면 멈춘다”는 모양이 생긴다. 이건 속도를 늦추는 장치가 아니라 되돌릴 수 없는 변경을 늦게 여는 장치다.

3. 작은 계약 블록 예시

내가 실제로 쓸 때의 형태는 대략 이렇다. 이 정도면 1분 안에 쓸 수 있고, 작업이 커지면 각 줄만 조금 더 구체화하면 된다.

작업 목표: 로그인 실패 화면에서 사용자 안내 문구만 더 명확하게 바꾼다.
읽기 허용: 관련 라우트, 메시지 컴포넌트, 최근 실패 로그.
수정 허용: 안내 문구가 있는 컴포넌트 1개와 테스트 1개.
수정 금지: 인증 흐름, 토큰 저장 방식, 리다이렉트 로직, 배포 설정.
수정 전 근거: 어떤 조건에서 문구가 모호한지 파일 위치와 함께 먼저 요약한다.
중단 조건: 두 번 수정해도 테스트가 실패하면 더 고치지 말고 원인 후보만 정리한다.

이 블록은 멋진 프롬프트가 아니다. 오히려 투박하다. 하지만 에이전트에게는 꽤 분명한 신호가 된다. “로그인 문제를 고쳐”라고 던지면 인증 흐름까지 손대고 싶어질 수 있지만, 위처럼 쓰면 문구 수정과 테스트 보강으로 작업면이 줄어든다. 바이브코딩에서 중요한 건 에이전트의 상상력을 전부 막는 게 아니라, 상상력이 닿아도 되는 범위를 먼저 정하는 일이다.

나는 여기서 “수정 전 근거” 줄을 꽤 중요하게 본다. 에이전트가 파일을 읽었다는 사실만으로는 부족하다. 어떤 로그, 어떤 조건, 어떤 파일 위치 때문에 지금 수정이 필요한지 짧게 말하게 해야 한다. 이 한 줄이 없으면 read가 형식적인 통과 의례가 되기 쉽다. 예전에 정리한 read:edit 비율도 결국 같은 얘기다. 읽었다는 횟수보다, 읽은 내용이 수정 이유로 연결됐는지가 더 중요하다.

4. 허용 도구를 단계별로 여는 방식

도구 계약서에서 내가 자주 쓰는 또 하나의 요령은 권한을 한 번에 열지 않는 것이다. 처음부터 읽기, 수정, 테스트, 커밋까지 다 열어 주면 에이전트는 완료 상태를 향해 곧장 달린다. 작업이 단순할 때는 괜찮지만, 불확실성이 큰 버그나 제품 요구사항이 섞인 작업에서는 부담스럽다. 그래서 나는 보통 read-only → narrow edit → verify → handoff 순서로 끊는다.

첫 단계에서는 파일을 읽고 원인 후보만 만들게 한다. 두 번째 단계에서 수정 파일을 하나나 둘로 제한한다. 세 번째 단계에서 검증 명령이나 화면 확인을 통과시킨다. 마지막으로 남은 리스크를 사람이 볼 수 있게 요약하게 한다. 이렇게 나누면 에이전트가 한 번에 모든 걸 해결하려는 압박을 덜 받고, 나도 중간에 방향을 틀 수 있다.

이 구조는 review와 apply를 분리하는 감각과도 비슷하다. 판단을 만들 수 있다고 해서 바로 적용 권한까지 주는 건 아니다. 판단은 넓게 만들어도 되지만, 실제 변경은 좁게 열어야 한다. 에이전트가 강해질수록 이 구분은 더 중요해진다. 모델이 약해서가 아니라, 강한 모델일수록 틀린 방향으로도 멀리 갈 수 있기 때문이다.

5. 계약이 필요한 순간과 필요 없는 순간

모든 작업에 도구 계약서를 붙이면 피곤하다. 오타 하나, 주석 하나, 테스트 이름 하나 고치는 일까지 표를 만들 필요는 없다. 나는 보통 세 가지 신호가 보이면 계약서를 쓴다. 첫째, 에이전트가 여러 도구를 연달아 써야 한다. 둘째, 수정 범위가 세 파일을 넘을 가능성이 있다. 셋째, 인증, 결제, 데이터 삭제, 마이그레이션, 배포 설정처럼 실패 비용이 큰 영역이 근처에 있다.

반대로 작업이 매우 작고 실패 비용도 낮다면 계약서를 줄인다. “이 파일 한 곳만 수정하고 테스트 하나만 추가” 정도면 충분하다. 중요한 건 형식이 아니라 판단이다. 도구 계약서는 바이브코딩을 느리게 만드는 문서가 아니라, 빠르게 맡겨도 되는 작업과 아직 맡기면 안 되는 작업을 가르는 기준에 가깝다.

계약서를 쓰다 보면 생각보다 사람이 먼저 정리된다. “무엇을 허용할까”를 적으려면 내가 원하는 결과와 두려워하는 변경을 구분해야 한다. 이 구분이 흐릴 때는 에이전트도 당연히 흐리게 움직인다. 그래서 도구 계약서는 에이전트를 통제하는 장치이면서, 동시에 내가 작업을 제대로 쪼갰는지 확인하는 작은 체크리스트가 된다.

6. 내 기준의 마감 조건

바이브코딩 세션을 끝낼 때 나는 결과물보다 계약 위반이 있었는지를 먼저 본다. 목표는 맞았는데 금지 파일을 만졌다면 그건 성공으로 보지 않는다. 테스트는 통과했는데 수정 전 근거가 없었다면 다음 세션에서는 read-only 단계를 더 길게 둔다. 반대로 결과가 아직 완벽하지 않아도 계약 안에서 원인 후보와 다음 행동이 잘 남아 있으면, 그건 이어서 작업하기 좋은 상태다.

이 기준을 세우고 나서 마음이 조금 편해졌다. 에이전트를 믿을지 말지라는 큰 질문 대신, 이번 작업에서 어떤 도구를 어느 폭으로 열어 줄지만 결정하면 되기 때문이다. 프롬프트를 더 잘 쓰는 일도 필요하지만, 내 쪽에서 먼저 해 줄 수 있는 가장 실용적인 일은 권한을 작게 열고, 근거를 요구하고, 멈출 조건을 적는 것이었다.

그래서 요즘 내 바이브코딩 기본값은 단순하다. 큰 요청을 한 번에 맡기기보다 작은 도구 계약서를 먼저 둔다. 에이전트가 충분히 잘하면 다음 칸을 열고, 애매하면 멈춰 세운다. 이 리듬이 생기면 에이전트는 더 자유로워지는 게 아니라 더 안전해진다. 그리고 실무에서는 그 차이가 생각보다 자주 결과를 갈랐다.