출력 형태부터 정하고 도구를 맡기기

시리즈: 바이브코딩 Tips #24

이전: 23편 | 목록 | 다음 없음

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

---

코딩 에이전트에게 도구를 맡길 때 가장 자주 깨지는 지점은 “무엇을 할지”보다 어떤 모양으로 돌려받을지가 비어 있을 때다. 파일을 읽어 달라고만 하면 긴 요약이 오고, 테스트를 돌려 달라고만 하면 성공·실패보다 로그 해석이 먼저 온다. 사람은 대충 알아서 맞춰 줄 거라고 생각하지만, 에이전트는 출력 계약이 없으면 매번 다른 폭으로 움직인다.

도구를 부르기 전 계약을 좁히면, 결과 해석과 되돌림 비용이 같이 줄어든다.

도구 이름보다 결과 모양이 먼저다

처음에는 나도 “이 파일 읽고 문제 찾아줘”, “테스트 돌려줘”, “최근 로그 봐줘”처럼 일을 던졌다. 짧게 말하니 편한 것 같지만, 막상 돌아온 결과는 매번 달랐다. 어떤 세션은 원인 후보를 길게 쓰고, 어떤 세션은 명령 결과만 붙이고, 어떤 세션은 수정까지 해버렸다. 문제는 에이전트가 똑똑하지 않아서가 아니라, 내가 출력의 형태와 멈출 지점을 먼저 정하지 않았다는 데 있었다.

도구 계약은 거창한 문서가 아니다. “읽기만 하고 수정하지 말 것”, “결과는 원인 후보 3개와 증거 줄 3개로 줄 것”, “실패하면 다음 명령을 실행하지 말 것”, “최종 출력은 JSON 배열로 줄 것” 같은 작은 약속이다. 이 약속이 있으면 에이전트는 도구를 더 적게 부르고, 사람은 결과를 더 빨리 판단한다.

특히 코딩 작업에서는 도구 호출 자체가 비용을 만든다. 검색 범위를 넓히면 관련 없는 파일까지 읽고, 테스트를 크게 돌리면 실패 원인이 흐려지고, 자동 수정까지 허용하면 diff가 중심 밖으로 번진다. 그래서 좋은 요청은 “이 도구를 써라”가 아니라 “이 도구를 써도 되지만, 결과는 이 모양으로만 가져오라”에 가깝다.

입력 계약: 어디까지 봐도 되는지 먼저 자르기

첫 번째는 입력 범위다. 에이전트에게 “repo 전체를 봐도 된다”고 열어 두면, 실제로는 문제와 상관없는 설정 파일, 예전 실험, 문서까지 한꺼번에 들어온다. 컨텍스트가 넓어질수록 답이 풍부해지는 게 아니라, 판단 근거가 흐려질 때가 많다.

나는 요즘 작은 작업을 맡길 때 “우선 이 파일 두 개만 읽고, 부족하면 추가 파일명을 요청하라”는 식으로 시작한다. 이 말 한 줄이 생각보다 강하다. 에이전트는 바로 검색을 넓히지 않고, 사람이 허락한 경계 안에서 먼저 가설을 세운다. 추가 조사가 필요하면 그때 이유와 함께 범위를 늘린다. 이렇게 하면 중간에 “왜 이 파일까지 고쳤지?” 하는 순간이 줄어든다.

출력 계약: 자연어 요약보다 판정 가능한 모양

두 번째는 출력 형태다. 로그 분석을 맡길 때 “요약해줘”라고 하면 읽기 좋은 글은 오지만, 다음 행동으로 바로 이어지지 않을 때가 많다. 대신 “증상, 직접 증거, 가능한 원인, 다음 한 가지 확인”처럼 칸을 정해 두면 결과가 훨씬 다루기 쉬워진다.

코드 생성도 마찬가지다. “함수 만들어줘”보다 “입력 타입, 출력 타입, 실패 시 예외, 테스트 케이스 이름까지 같이 제안해줘”가 낫다. 결과물이 파일이든 표든 JSON이든 상관없다. 중요한 건 사람이 다시 판단할 수 있는 단위로 접혀 있어야 한다는 점이다. 에이전트가 만든 결과를 내가 다시 해석하는 데 오래 걸리면, 자동화로 줄인 시간이 검토 비용으로 다시 나간다.

검증 계약: 성공 기준을 도구 호출 뒤에 만들지 않기

세 번째는 검증 기준이다. 에이전트가 뭔가를 고친 뒤에야 “그런데 성공은 어떻게 보지?”를 묻기 시작하면 늦다. 이미 diff가 생겼고, 로그도 길어졌고, 사람은 처음 의도와 결과를 다시 맞춰야 한다. 작은 작업일수록 검증 기준은 앞에 두는 편이 좋다.

예를 들어 테스트를 돌릴 때도 “전체 테스트 통과”만 성공 기준으로 두면 너무 무겁다. “이번 변경은 특정 케이스 2개가 통과하고, 기존 실패 1개가 그대로 실패하면 충분하다”처럼 좁힐 수 있다. 반대로 보안이나 마이그레이션처럼 위험한 작업은 “경고가 하나라도 나오면 수정 중단”이 기준이 될 수 있다. 검증 계약은 에이전트를 믿지 않기 위한 장치가 아니라, 믿을 수 있는 범위를 작게 만드는 장치다.

권한 계약: 잘하면 더 하라는 말이 항상 좋은 건 아니다

마지막은 권한이다. 에이전트가 초반에 문제를 잘 찾으면, 사람은 자연스럽게 “그럼 고쳐줘”라고 말하고 싶어진다. 그런데 읽기 작업과 수정 작업은 성격이 다르다. 읽기에서는 넓게 봐도 괜찮지만, 수정에서는 한 줄이 배포 경로를 바꿀 수 있다. 그래서 권한은 단계적으로 여는 편이 안전하다.

내가 쓰는 간단한 문장은 이렇다. “이번 턴에서는 수정하지 말고, 수정 후보 파일과 이유만 내라.” 또는 “수정은 이 파일 하나로 제한하고, 다른 파일이 필요하면 멈춰서 요청하라.” 이렇게 말하면 에이전트가 스스로 큰 리팩터링으로 번지는 일을 막을 수 있다. 잘하는 에이전트일수록 일을 더 넓히려는 경향이 있기 때문에, 권한 계약은 속도를 늦추는 장치가 아니라 사고 반경을 줄이는 장치에 가깝다.

내가 자주 쓰는 짧은 요청 틀

• 입력: “우선 이 파일과 이 로그만 봐라. 부족하면 추가 파일명을 먼저 요청해라.”
• 출력: “결과는 증거 3개, 원인 후보 3개, 다음 확인 1개로만 줘라.”
• 검증: “성공 기준은 이 테스트 2개 통과와 이 경고 0개다.”
• 권한: “이번 턴은 읽기 전용이다. 수정이 필요하면 diff 계획만 내라.”

조금 더 실제 문장으로 쓰면 “로그를 보고 원인 후보만 좁혀줘. 수정하지 말고, 각 후보마다 근거 줄을 하나씩 붙여줘. 근거가 없으면 추측이라고 표시해줘.” 정도가 된다. 이 문장은 길지 않지만 입력 범위, 출력 형태, 수정 권한을 동시에 잡는다. 에이전트가 바로 코드를 고치는 대신 사람이 판단할 수 있는 작은 패킷을 먼저 돌려준다.

반대로 “알아서 고쳐줘”는 편해 보이지만, 결과가 마음에 안 들 때 되돌릴 기준이 약하다. 어떤 파일을 왜 봤는지, 어떤 실패를 성공 기준으로 삼았는지, 어디서 멈췄어야 했는지가 뒤늦게 논쟁거리가 된다. 특히 여러 에이전트를 병렬로 붙일 때는 이 기준 차이가 더 크게 터진다. 한 세션은 테스트를 성공 기준으로 보고, 다른 세션은 타입 검사만 보고, 또 다른 세션은 빌드 로그의 마지막 줄만 보고 끝낼 수 있다. 도구 계약은 에이전트를 통제하려는 말투가 아니다. 같이 일할 때 서로의 손이 닿는 범위를 보이게 만드는 최소한의 작업 표지판이다.

이 네 줄을 매번 다 쓸 필요는 없다. 그래도 작업이 애매해질수록 입력, 출력, 검증, 권한 중 무엇이 비어 있는지 먼저 보면 좋다. 에이전트가 예상보다 잘해 보이는 순간에도 이 기준은 남겨 두는 편이 낫다. 성공한 실행도 다시 맡기면 다른 경로로 갈 수 있기 때문이다. 이 작은 선을 미리 그어 두면 리뷰도 훨씬 짧고 선명해진다. 효과가 크다. 에이전트에게 일을 잘 맡기는 감각은 멋진 프롬프트 문장을 외우는 쪽보다, 도구가 돌아오기 전에 결과의 모양을 좁혀 두는 쪽에 더 가까웠다.

시리즈: 바이브코딩 Tips #24

이전: 23편 | 목록 | 다음 없음