AI 코딩 에이전트의 실수를 엔지니어 리뷰 방식으로 잡는 워크플로

보안 중심 패키지 레지스트리 Greenflagged를 개발하는 작성자가 Claude Code로 코드를 작성하면서 관찰한 에이전트의 실패 패턴과, 이를 통제하기 위해 워크플로에 추가한 서브에이전트들을 정리했다. 핵심 주장은 단순하다. 코딩 에이전트는 사람 엔지니어와 매우 비슷한 방식으로 틀리기 때문에, 사람에게 적용하던 변경 리뷰 절차를 그대로 적용하는 것이 효과적이라는 것이다.

그가 구성한 흐름은 다음과 같다. 만들 기능을 정의하면 에이전트가 구현 계획을 세우고, 여러 에이전트가 그 계획을 서로 다른 관점에서 검토하며 반복한다. 계획이 확정되면 구현 후 머지 리퀘스트가 올라오고, 별도의 변경 리뷰 스킬이 이를 검증한다. 리뷰어들이 관점을 달리해 피드백을 주고, 수정과 재리뷰가 돌고, 마지막으로 CI가 빌드와 테스트를 확인한다. 사람이 손으로 코드를 쓰던 시절의 파이프라인과 구조가 같다.

여기에 세 개의 서브에이전트가 붙는다. 첫째는 Skeptic으로, 모든 주장에 의심을 거는 역할이다. 어떤 에이전트가 "이 코드는 다른 경로에서 이미 처리되니 삭제해도 된다"고 제안했을 때, 이 에이전트가 그 변경이 Greenflagged 알림 시스템에 사각지대를 만든다는 점을 리뷰 단계에서 잡아냈다. 둘째는 Logician으로, 전제에서 결론이 실제로 따라오는지를 본다. 승인한 패키지를 나중에 다시 승인할 수 있게 되는 논리 결함이 계획 단계에서 지적됐는데, 코드가 만들어지기도 전에 걸러진 사례다. 셋째는 Steward로, 장기 운영 비용에 초점을 좁힌다. 로그인 관련 작은 변경 하나가 검색엔진에 수백만 개의 URL을 남길 수 있었는데, HTML 속성 하나를 추가하는 것으로 막았다.

실패 사례는 더 직접적이다. 한 에이전트는 Redis가 디스크에 데이터를 쓰는 것이 헬스체크 타임아웃의 원인이라고 진단하고 영속화를 끄는 변경을 머지했다. ConfigMap이 갱신된 것까지는 확인했지만 Redis를 재시작하지 않아 계속 디스크에 기록이 남았다. 결과를 검증하는 절차를 건너뛴 것이다. 작성자는 이후 에이전트가 자신의 작업 결과를 검증하는 방법까지 명시적으로 알도록 워크플로를 바꿨다.

배경에는 에이전트의 특성에 대한 관찰이 있다. 에이전트는 사람처럼 시행착오를 반복하지만, 사용 가능한 도구에 대한 지식이 사실상 무한하고 포기하지 않는다는 점이 다르다. 작성자가 들어본 적 없는 CLI 도구로 아이디어를 검증하고 그것을 해법에 통합하기도 한다. 반면 주어지지 않은 맥락은 스스로 발견하지 못하고 가정으로 채운다. 잘못된 가정이야말로 Skeptic을 만든 이유다.

실무적 함의는 프로세스에 있다. 에이전트의 생산 속도가 빨라질수록 병목은 코드 작성이 아니라 검증과 리뷰로 옮겨가며, 어떤 관점의 리뷰를 자동화할지 설계하는 일이 유지보수성을 좌우한다. 데이터 종류와 접근 패턴을 미리 분류해 적절한 저장소를 고르는 것 같은 판단도 에이전트에게 맡기기 전에 사람이 기준을 정해둬야 한다는 것이 이 사례의 교훈이다.

다만 이 내용은 한 개발자가 자신의 프로젝트에서 운영한 워크플로에 대한 경험적 기록이다. 작성자 역시 독자가 자신의 에이전트에게 맞는 버전을 직접 만들 것을 권하고 있으며, 제시된 서브에이전트 구성이 일반적인 성능 향상을 보장하지는 않는다.