← 모든 글

AI Engineering

AI 코딩 에이전트가 같은 실수를 반복할 때: 프롬프트 대신 린트·CI로 막는 법

에이전트에게 같은 지적을 반복하지 말고 린트 규칙과 정책으로 저장소에 남기라는 Sentry Greg의 발표를 정리했다.

이 글의 목차

Sentry에서 디버깅 에이전트 인프라를 만드는 Greg의 발표를 보고 정리했다. 제목부터 도발적이다. 프롬프트를 그만 쓰고, 에이전트가 따라야 할 규칙을 코드로 박아 두라는 이야기다.

정리 대상 영상. 길이는 15분 남짓이다.

같은 잔소리를 계속 하게 된다

발표자는 AI가 쓴 코드를 읽느냐는 질문으로 시작한다. 회사 프로덕션 코드는 꼭 읽지만, 개인 프로젝트는 한 줄씩 보지 않는다고 한다. 그러다 나중에 코드를 열어 보면 방어 코드가 지나치게 많고 테스트는 아무것도 검증하지 않는 경우가 생긴다.

그래서 에이전트에게 "너무 복잡하다, 이렇게 고쳐라"라고 말한다. 에이전트는 "맞습니다"라며 고치지만, 몇 분 뒤 컨텍스트 압축이 일어나면 처음 상태로 돌아간다. 같은 지적을 처음부터 다시 해야 한다.

발표자의 주장은 단순하다. 말로 고치지 말고, 지키길 바라는 규칙을 코드베이스에 결정적인 검사로 남기라는 것이다.

결정적인 검사 세 가지: 테스트, 타입, 린터

발표자가 꼽는 기본기는 테스트, 엄격한 타입, 린터다. 훅은 이 검사를 알맞은 때에 돌리는 수단이라고 설명한다. 다만 이 셋을 켜 두는 것만으로는 부족하다. 예를 들어 타입을 엄격하게 쓰더라도, 있어서는 안 되는 상태까지 표현할 수 있는 타입 방식을 막아 두지 않으면 에이전트가 그 상태를 만들어 낸다고 한다. 발표는 이 중에서 린터에 집중한다.

에이전트 시대에는 린터를 만드는 비용이 달라졌다

예전에는 린트 규칙을 직접 만드는 일이 부담이었다. 만들고 유지하는 비용이 들고, 그 문제가 얼마나 자주 나오는지도 따져야 했다. 사람 팀이라면 몇 주에 한 번 "디자인 시스템 컴포넌트를 쓰라"고 말하면 되고, 사람은 기억하기 때문에 한두 번 말하면 대부분 따른다.

지금은 상황이 두 가지로 바뀌었다. 코드를 쓰는 쪽(에이전트)은 기억이 없어서 같은 실수를 반복한다. 반대로 린트 규칙은 에이전트에게 시키면 싸고 빠르게 만들 수 있다.

발표자가 권하는 실습은 이렇다. 에이전트에게 지난 대화 기록과 GitHub 리뷰(봇과 동료의 피드백)를 읽게 하고, 반복해서 지적한 것 중 결정적인 린트 규칙으로 만들 수 있는 것을 뽑게 한다. 본인은 이 작업을 정기적으로 돌려서 아직 규칙이 되지 않은 패턴을 찾는다고 한다.

커스텀 린트 규칙 예시: API 스키마 맞추기

단순한 예는 오래 써 온 것들이다. 특정 프로젝트에서 console.log를 막거나, 디자인 시스템과 React 관례를 규칙으로 고정하는 식이다. 에이전트가 있으면 조금 더 복잡한 것도 가능하다.

Sentry는 Django와 DRF를 쓰는 오래된 코드베이스이고 타입이 곳곳에 엄격하게 적용되어 있지는 않다. 그 상태에서 OpenAPI 스키마가 실제 동작과 어긋나는 일이 많았고, 그래서 규칙 세 개를 만들었다고 한다.

  • 엔드포인트 함수는 응답 타입을 반환해야 하고, 그 안에 any가 없어야 한다.
  • 엔드포인트에는 스키마 확장 데코레이터를 붙여 문서화를 강제한다.
  • 함수가 만드는 타입이 OpenAPI 스키마의 선언과 일치하는지 검사한다.

스킬 문서까지 린트한 두더지 잡기

Sentry의 디버깅 에이전트(Seer)는 Sentry API를 많이 호출한다. 고치기 어려운 오래된 엔드포인트는 스킬 문서로 사용법을 안내한다. 그런데 스킬을 대량으로 생성했더니 예제 코드 중 환각이 많아서 에이전트 정확도가 크게 떨어졌다고 한다.

첫 린터는 스킬 안의 코드 블록을 꺼내서 타입 검사를 하고, 샌드박스에서 실행되는지와 OpenAPI 스키마에 맞는지 확인했다. 그러자 에이전트가 이상한 방향으로 피해 갔다. 이 과정이 발표에서 가장 재미있는 대목이다.

  1. 린트 오류가 나자 코드 블록을 지워 버렸다. 그래서 예제는 반드시 코드 블록에 넣으라는 규칙을 더했다.
  2. 이번에는 코드 블록에서 백틱을 빼 버렸다. 린터가 백틱 안의 코드만 보기 때문이다. 그래서 코드처럼 생긴 것(밑줄, 괄호가 있는 것)은 코드 블록에 넣으라고 했다.
  3. 그러자 API를 산문으로 설명하기 시작했고, 그 안에 URL을 적었다. 그래서 URL도 린트로 막았다.

이렇게 한동안 두더지 잡기를 했지만, 결국 스킬이 OpenAPI 스키마와 동기화된 상태가 됐고 비용도 크지 않았다고 한다. 발표자는 깨지지 않는다고 장담하지는 않지만, API가 바뀌어도 스킬을 매번 따라가며 고치지 않아도 되는 구조가 되었다고 말한다.

도구는 이미 쓰는 것을 그대로 쓰면 된다. 발표자는 oxlint, flake8, clippy를 예로 들고, 언어에 관계없이 쓸 수 있는 ast-grep을 좋아한다고 한다. 린터 코드 대신 의도를 영어로 적으면 린터를 만들어 주는 Taskless 같은 새 도구도 언급한다. 마지막은 역시 에이전트에게 린터를 만들어 달라고 해 보라는 것이다.

린터로 못 잡는 것: 취향은 정책과 서브에이전트로

결정적인 규칙으로 표현하기 어려운 것도 많다. 상태가 세 개인 상태 머신에 작은 기능을 넣는 PR이 상태를 열 개로 부풀리는 경우가 그렇다. "상태는 네 개까지"처럼 임의의 숫자를 정할 수는 있지만 근거가 없다. 이런 건 경험이나 취향의 영역이라 거절하거나, LLM에게 한 번 검토를 맡기는 수밖에 없다고 한다.

발표자는 저장소에 정책을 써 두었다. 예를 들면 테스트를 무조건 늘리지 말고 더 강하게 쓸 것, 지나치게 방어적인 코드를 쓰지 말 것, 원치 않는 상태는 타입으로 표현하지 못하게 할 것 같은 내용이다. 그리고 이 정책을 읽고 도는 스킬을 만들었는데, 이름은 grumpy engineer(사내에서는 Garfield)다.

동작 방식은 이렇다. 정책마다 서브에이전트를 하나씩 띄우고, 각 서브에이전트는 피드백을 주거나 "이 정도면 됐다"며 물러난다. 모두 물러날 때까지 이 과정을 반복하고, 그다음에야 사람이 코드를 읽는다. 발표자는 이 발표에서 루프라는 말을 쓰는 건 이 대목이 거의 유일하다고 농담한다.

정책 서브에이전트 반복 검토 흐름 저장소 정책 정책별 서브에이전트 피드백 or 물러남 사람이 리뷰 피드백이 있으면 고치고 다시 검토 모두 물러나면
영상 설명을 바탕으로 직접 그린 흐름도. 화살표 모양과 배치는 이해를 돕기 위해 단순화한 것이다.

이 방식의 성공 기준도 흥미롭다. 코드 리뷰를 없애는 게 아니라, 리뷰할 때 초보적인 지적을 하는 일이 줄었는지를 본다. "이건 아쉽지만 방향을 잡아 줄 수 있다"는 수준의 피드백만 남기는 것이 목표다. 발표자는 모델이 좋아지면 이 부분도 바뀔 거라고 말하면서, 지금은 품질의 바닥을 끌어올리는 용도라고 설명한다.

숫자로 취향을 대신하지 말 것

마지막 경고는 가짜 지표에 대한 것이다. 발표자는 질적인 기준을 숫자로 바꾸는 실험을 해 봤다. 대표적인 것이 순환 복잡도와 테스트 커버리지다.

에이전트에게 숫자를 주면 그 숫자를 최대한 올리는 쪽으로 움직인다. 실제로 커버리지가 100%에 가까운 프로젝트가 나왔지만, 테스트는 특정 출력 문자열을 그대로 확인하는 식이어서 가치 있는 것을 검증하지 못했다. 오히려 거짓 안심만 줬다고 한다.

정리하며

영상에서 가져갈 것은 순서다. 먼저 에이전트와 반복해서 부딪히는 지점을 모아서 린트 규칙으로 만든다. 린터로 안 되는 취향은 정책으로 쓰고 서브에이전트에게 검토시킨다. 숫자 지표로 취향을 흉내 내는 것은 조심한다. 같은 말을 세 번째 하게 되면, 프롬프트에 쓰는 대신 저장소가 기억하게 만들 때라는 이야기다.