일부러 에이전트 속도를 늦추기

더 빠른 에이전트가 더 나은 소프트웨어를 만드는 것은 아니다. 규율 있는 에이전트가 만든다. RakuAI를 일관되게 유지하는 이 스로틀은, 진지하게 에이전트 주도 개발을 하는 모든 팀에게 필요하다고 생각하는 바로 그 규율이다.

이번 토요일 계획은 지난 몇 주말과는 달랐다. 지난 몇 주는 처리량 위주의 주말이었다. 여든 개 커밋, 일흔 개 커밋, 그 전에는 이백여든두 개. 추세는 계속 올라갔다. 나는 에이전트 큐를 완전히 열어놓고 코드 줄 수가 쌓이는 것을 지켜보고 있었다.

이번 주말에는 일부러 서른일곱 개 커밋으로 속도를 줄였다. 이 그래프의 추세는 이제 내려가고 있고, 그것은 의도적으로 내려가는 것이다. 왜 그랬는지 글로 남기고 싶은데, AI 에이전트로 개발하는 대부분의 사람들이 예상하는 추세와는 다르다고 생각하기 때문이다.

이 워크플로에서 사실인 것

에이전트는 지치지 않는다. 구현 레이어의 처리량은 토큰 비용과 큐에 열려 있는 이슈 수에 의해서만 제한된다. 아침 여섯 시에 이슈 백 개를 등록하면 큐는 하루 종일 비워졌다 다시 채워지고, 나는 PR을 백 개 돌려받게 된다. 완전히 개방해서 돌리면 워크플로가 하는 일이 바로 그것이다.

완전히 개방해서 돌릴 때 하지 않는 일은 일관성 있는 코드베이스를 만드는 것이다. 각 PR은 개별적으로는 깔끔하게 들어온다. 하루에 마흔 개의 PR이 들어오는 교집합 지점에서부터 어긋나기 시작한다. 네이밍 컨벤션이 갈라진다. 서브시스템 경계가 흐려진다. 어떤 이슈를 작업한 에이전트가 런타임 레이어에 대해 가정한 무언가를, 병렬로 다른 이슈를 작업한 에이전트는 가정하지 않았다. 토요일 저녁쯤 되면 그 두 가정이 세 번째 PR에서 충돌해서 조율해야 하고, 그 조율 결과는 엉성해진다.

이 워크플로의 병목은 에이전트가 아니다. 에이전트가 만들어낸 것을 읽고 아키텍처의 일관성을 지키는 사람이다.

무엇을 바꿨나

이번 주말 커밋 패턴에서 눈에 띄는 두 가지를 바꿨다.

큐 깊이를 줄였다. 항상 열려 있던 에이전트 큐 이슈 열다섯 개를 여섯 개로 낮췄다. 에이전트는 더 이상 완전히 개방된 상태로 돌지 않는다. 다음 배치가 들어오기 전에 내가 실제로 그 결과물을 읽을 수 있는 속도로 돌아간다.

리뷰 시점을 앞당겼다. 처리할 배치가 쌓일 때까지 에이전트 PR을 기다리게 두는 대신, PR이 열리는 즉시 리뷰하는 방식으로 바꿨다. 더 느리게 들릴 것이고, 실제로 느리다. 하지만 어긋남이 퍼지기 전에 잡아낸다. 토요일 이른 시간에 바로잡은 잘못된 가정은, 토요일 저녁까지 여섯 개의 PR에 걸쳐 되돌릴 필요가 없다.

이 두 가지 변화가 합쳐진 결과가 여든 개 커밋짜리 주말 대신 서른일곱 개 커밋짜리 주말이다. 그리고 그 결과는 지난 토요일보다 더 나은 상태의 코드베이스이기도 한데, 그게 핵심이다.

그래도 진행된 것

이번 주말에는 멀티 레포 규율이 더 탄탄해졌다. 런타임, SDK, 문서 레포가 모두 함께 움직였다. 런타임은 README에 문서 디렉터리 개요를 얻었다. SDK는 그에 상응하는 상호 참조를 얻었다. 문서는 늘어났다. 셋 중 어느 하나도 다른 것들보다 앞서가지 않았다.

이것이 중요한 이유는 에이전트 주도 워크플로에서 문서는 단순한 문서가 아니기 때문이다. 문서는 에이전트가 다음 이슈를 집어들 때 읽는 입력값이다. 문서가 런타임이 지원하는 내용에 대해 거짓말을 하면, 에이전트는 그 거짓말하는 버전의 런타임에 맞춰 충실하게 코드를 작성할 것이고, 그 코드는 실제 현실과 컴파일되지 않을 것이다. 해결책은 세 레포 모두를 항상 정직하게 유지하는 것이다. 자연스럽게 손이 가는 레포일 때조차도.

이번 주말 조용히 중요했던 또 다른 일은 API 표면 정리였다. 9월의 정신없는 시기에 추가되었던 몇몇 API가 알고 보니 공개 표면에 있어서는 안 되는 것들이었다. 그것들은 내부용으로 강등되었다. 에이전트들은 SDK 전반에 걸친 이 강등 작업을 PR 하나로 처리했다. 사람 혼자서 하면 하루 종일 걸리는 종류의 리팩터링이다. 이 워크플로에서는 이슈 하나, PR 하나, 그리고 꼼꼼한 리뷰로 끝난다.

이 워크플로에서 “모범 사례”가 의미하는 것

이번 주말 속도를 줄인 경험을 통해 다듬어진 짧은 목록이다.

문서는 개발 산출물이 아니라 개발 입력값이다. 문서가 나쁘면 작업도 나쁘다. 코드를 관리하듯 문서를 관리하라. 코드를 리뷰하듯 문서를 리뷰하라. 문서가 빠진 기능은 머지를 거부하라.

서브시스템 간의 경계는 신성하다. 에이전트는 코드베이스에 이미 존재하지 않던 경계를 새로 만들어내지 않는다. 경계를 원한다면 직접 그리고, 이름을 붙이고, 그것을 위반하는 PR은 거부해야 한다.

레포 간 동기화는 1급 과제다. 런타임과 SDK가 함께 움직여야 할 때는 PR 설명에 그렇게 명시해야 하고, 한쪽의 머지는 다른 쪽의 머지에 게이트되어야 한다. 두 레포 간 상태 발산은 피하기는 비교적 쉽지만 회복하기는 훨씬 고통스러운 실패 모드 중 하나다.

일부러 속도를 늦춰라. 에이전트는 그러지 않는다. 사람이 해야 한다. 에이전트가 PR 백 개를 출시한 주말이 코드베이스가 백 개 PR만큼의 가치로 개선된 주말과 같은 것은 아니다. 에이전트가 잘 리뷰된 PR 서른일곱 개를 출시한 주말이 그럴 가능성이 더 높다.

파트너들에게 도움이 될 만한 것

자율 코딩 에이전트로 무언가를 만들고 있고 “에이전트는 빠르게 일하는데 코드베이스는 엉망”이라는 이 워크플로 버전에 부딪히고 있다면, 답은 더 나은 에이전트가 아니다. 답은 더 작은 큐, 더 이른 리뷰 패스, 그리고 에이전트가 입력값으로 읽는 문서다.

이런 자율 PR 워크플로용 코딩 에이전트를 튜닝하는 AI 랩이라면, 실무에서 가장 유용하다고 느끼는 지표는 하루에 출시된 코드 줄 수가 아니다. 그 주 초반에 들어온 PR이 코드베이스가 그 아래에서 움직여버려서 같은 주말 안에 다시 작성되어야 하는 빈도다. 그 숫자가 낮을수록 에이전트가 실제 작업을 더 잘하고 있는 것이다.

서른일곱 개의 커밋. 지난 토요일보다 더 나은 코드베이스. 토요일 오후, 이제 산책하러 갈 참이다.