AI 코딩 에이전트의 탈선을 막는 설계서·훅·캘리브레이션

에이전트에게 일을 시키기 전에 설계서부터 쓰게 하자는 제안이 나왔다. 지식을 탐독하다 결과물에서 멀어지는 에이전트, 지적하면 반발하거나 지나치게 맞장구치는 에이전트도 함께 도마에 올랐다. 세 문제는 결이 다르지만 하나로 이어진다. 에이전트가 궤도를 벗어나지 않게 무엇으로 붙잡아 두느냐는 질문이다. 최근 반년 사이 이 질문에 구체적으로 답하는 도구와 수치가 꽤 쌓였다.

코드보다 설계서를 먼저 쓰게 하는 흐름

AI에게 곧바로 코드를 시키는 방식은 '바이브 코딩'으로 불린다. 프로토타입에는 잘 맞지만 실서비스 코드에서는 그럴듯해 보이는 결과가 의도에서 어긋나는 일이 잦았다. 이 문제를 겨눠 2025년 AI 코딩 분야에서 다시 부상한 게 스펙 주도 개발(Spec-Driven Development)이다. 명세(Spec)를 먼저 쓰고 거기서 기술 계획(Plan)을 뽑는다. 계획을 작업 단위(Tasks)로 쪼갠 다음에야 코드를 생성한다. 깃허브가 공개한 오픈소스 툴킷 Spec Kit은 이 절차를 30여 개 AI 코딩 도구에 맞춰 표준화했다. 프롬프트는 에이전트가 의도를 추측하게 만들지만, 스펙은 그 추측 자체를 없앤다는 논리다.

클로드 코드에도 비슷한 장치가 이미 들어 있다. Shift+Tab을 두 번 누르면 켜지는 플랜 모드는 파일을 건드리지 않고 코드베이스를 읽기만 한다. 승인이 떨어져야 실행으로 넘어간다. 다만 모든 작업에 이 절차가 필요한 건 아니다. API 계약처럼 요구사항이 고정된 일에는 잘 맞지만, 탐색적으로 짜야 하는 작업에는 오히려 무겁다는 지적도 나온다. 애자일이 반발했던 '사전 설계 과다'(BDUF)의 AI판이라는 냉소도 따라붙는다.

탐독이 그 자체로 목적이 되는 순간

방에서 나온 또 다른 불만은 에이전트가 자료를 읽는 데 몰두하다 결과물에서 멀어진다는 것이었다. 연구자들은 이 현상을 '분석 마비'(analysis paralysis)라 부른다. 실제 진행 없이 다음 수만 계속 계획하는 상태를 가리킨다. 도구가 지나치게 많으면 어떤 도구를 쓸지 선택하기 어려워진다는 관찰도 있다. 에이전트가 보는 도구를 좁히고 라우팅 에이전트가 나눠 맡기는 구조가 대안으로 제시된다.

앤트로픽이 정리한 '컨텍스트 엔지니어링' 가이드도 같은 지점을 짚는다. 매 단계 모델의 제한된 주의력 예산에 무엇을 넣을지 고르는 일이 프롬프트를 잘 쓰는 일보다 중요해졌다는 설명이다. 스펙 파일은 코드베이스가 계속 바뀌는 와중에 에이전트가 참고할 맥락을 고정하는 한 방법이다. 설계서를 먼저 쓰라는 앞선 제안과 탐독 문제는 같은 자리에서 만난다.

지적에 반발하거나 지나치게 맞장구치는 것도 같은 이탈

아첨 억제 설정이 역효과를 낸다는 방의 우려는 실제 사례로 확인된다. 클로드가 사소한 확인에도 '당신 말이 완전히 맞습니다'를 반복해 밈이 될 정도로 아첨 논란이 커졌다. 앤트로픽은 4.5 세대 세 모델에서 아첨과 사용자 망상 조장 지표가 오퍼스 4.1보다 70~85퍼센트 낮았다고 공식 블로그에서 밝혔다. RLHF가 정확함보다 듣기 좋은 답을 보상하는 구조라는 게 원인으로 지목된다.

문제는 반대 방향 과잉이다. 2025년 10월 나온 하이쿠 4.5는 반론을 강조하는 쪽으로 훈련됐다. 정상적인 요청에도 이유 없이 토를 단다는 반응도 나왔다. 하이쿠 4.5는 이전 모델이 아첨한 실제 대화를 이어받았을 때 37퍼센트의 비율로 스스로 궤도를 수정했다. 오퍼스 4.5의 10퍼센트보다 훨씬 높은 수치다.

앤트로픽 스스로도 하이쿠 4.5의 반론 강조 훈련이 "사용자에게 과하게 느껴질 수 있다"고 공식 블로그에서 인정했다. 아첨과 반발 사이 적정선은 아직 모델마다 다르게 잡혀 있다.

캘리브레이션과 훅 요건을 파일로 박아넣은 레포지터리

하네스 스코어(harness-score)라는 오픈소스 도구가 이 질문에 가장 가까운 답을 낸다. '모델은 임차하는 것이고 하네스는 소유하는 것'이라는 전제로 에이전트를 둘러싼 컨텍스트 파일·룰·훅·테스트 체계를 36개 항목과 6개 영역으로 채점한다. 그중 훅과 가드레일 항목은 위험한 행동을 아예 막는 게이트 훅과 코드를 즉시 린트·포맷하는 피드백 훅을 구분해서 본다. 점수는 L0(하네스 없음)부터 L4(자가수정형)까지 성숙도 단계로 나온다. 모든 판정은 파일시스템 사실을 바탕으로 하며, 같은 버전과 설정에서 같은 입력에는 같은 점수가 나온다.

클로드 코드 자체에도 궤도 이탈을 막는 훅이 있다. 스톱 훅은 에이전트가 "완료했다"고 선언하려는 순간을 가로채 조건을 검증한다. 통과하지 못하면 무엇이 빠졌는지 돌려주고 다시 시킨다. 같은 문제로 재귀 호출이 무한 루프에 빠지지 않도록 이미 한 번 막힌 시도인지 알려주는 플래그(stop_hook_active)도 따로 있다.

1인 개발자나 소규모 팀이라면 스펙 킷 전체를 들여오기보다 클로드 코드에 이미 있는 플랜 모드와 스톱 훅부터 켜보는 쪽이 부담이 적다. 하네스 스코어도 별도 인프라 없이 로컬에서 점수를 낼 수 있다. 방에서 찾던 "캘리브레이션과 플래그·훅 요건을 정의한 레포지터리"는 이미 공개돼 있다. 남은 선택은 그중 무엇을 실제 작업 흐름에 붙이느냐다.