AI 에이전트와 세 단계 사이클

  • AI
  • Claude Code
  • Code Review
  • TDD
  • GitHub Actions

TL;DR

  • 팀 프로젝트 합방을 진행하며 백엔드(레포)에서 내가 올린 PR 186개를 Claude Code로 만들었다. 구현을 맡기고 계획, 테스트, 리뷰 사이클로 진행했다.
  • 리뷰단계에서 사이클의 효과가 가장 컸다. CI의 Claude 리뷰가 diff에서 확인되지 않는 팀 문서나 설정과 대조하게 바꾸자, 내 PR에 달린 인라인 리뷰가 11%에서 77%로 늘었다. 그렇게 달린 인라인 리뷰 69건 중 64건은 전부 또는 일부를 고쳤다.
하나의 이슈 티켓이 병합되기까지의 과정
  • 개발자
  • AI
이슈플랜·질문답·되묻기승인계획실패 → 통과다음 테스트PR테스트CI 리뷰수정·답글병합리뷰배포 뒤 운영에서 확인 → 이슈 닫기 → 다음 이슈

1. 계획: 승인 전에는 읽기만 한다

에이전트에게 티켓 번호만 주면 바로 코드를 고치기 시작한다. 요구사항을 잘못 이해한 채 코드를 작성하기 시작하면 AI는 잘못된 방향으로 아우토반처럼 달려간다. 리뷰 단계가 돼서야 발견되지 않도록 최대한 나와의 fit을 맞춰야 한다. 반복되는 티켓 작업에 매번 프롬프트를 길게 입력하지 않도록 command(/plan-ticket)를 만들어 이슈 번호를 넘기는 것으로 시작했다.

플랜을 내가 승인할 때까지는 읽기·조회만 한다.

AI 에이전트는 이슈의 완료 조건과 관련 문서, 기존 코드를 읽고 플랜을 낸다. 단계마다 자기가 증명하는 완료 조건 번호를 달고, 플랜을 세울 때는 mattpocock/skills의 skill을 티켓 종류에 맞춰 쓴다.

  • grilling: AI가 멋대로 추론하지 않도록 질문하게 한다. 한번에 10개 가량의 질문이 들어온다.
  • domain-modeling, codebase-design: 용어가 맞는지 확인하고, 다른 모듈간 연결할 지점과 끊을 지점을 정한다.

지갑 앱 HTTP 클라이언트에서는 질문이 네개 왔고 셋은 추천대로 답했다. 하나는 내가 AI의 질문을 이해하지 못해서 질문했다.

이해 안돼 다시 설명해

강의 AI 추천 동기화에서는 장바구니와 리뷰에 @Version만 달면 동시에 두 번 요청할 때 두 번째가 500이 된다는 게 걸렸다. version만 달면 되지 않느냐고 되물었다가, 선택지를 다시 나눠 받고 행 잠금을 같이 쓰는 쪽을 골랐다. 그리고 그 결정이 지켜지는지 볼 테스트를 플랜에 넣게 했다.

장바구니 빼기, 리뷰 수정을 동시에 두 번 해도 둘 다 성공하는지 확인하는 테스트 추가.


2. 테스트: 플랜의 테스트부터 쓴다

승인한 플랜에는 단계마다 테스트 이름이 붙어 있다.

text
4. [C2·C3·C4] LectureSyncEvents.lectureChanged와 Lecture.toSyncDto()를 만들고, 강의 use case 7곳에서 부른다.
   - 강의를_등록하면_version_0과_콘텐츠로_이벤트가_나간다
   - 콘텐츠만_바꿔도_강의_version이_오르고_새_콘텐츠로_나간다
   - 삭제하면_deleted_true_onSale_false로_나간다

에이전트는 tdd skill로 Red-Green-Refactor 사이클로 구현한다. 82개 PR 중 69개가 테스트도 함께 추가했다.

테스트가 있다고 내 의도를 충분히 검증한다는 걸 보장할 수 없다. 그래서 구현을 일부러 되돌려 테스트가 정말 실패하는지도 확인했다. 인프라 작업은 테스트 대신 단계마다 제대로 됐는지 확인할 수 있는 명령어와 기대 결과를 확인하도록 했다.


3. 리뷰: diff 외에도 확인한다

10월 15일, PR마다 도는 Claude 리뷰를 GitHub Actions에 추가했다(#212). 처음 기준은 AGENTS.md의 모듈 경계와 돈 규칙, 두 장뿐이었다.

3주쯤 돌려 보니 "문제 없음"으로 끝나는 리뷰가 많았다. 고치기 전에 확인부터 하도록 했다.

  • 첫 리뷰 59건 중 약 31건이 "지적 없음"이었다.
  • 리뷰 한 번에 평균 22초였고, diff 외에 다른 파일을 확인한 건 리뷰당 0~2번이었다.
  • Claude가 문제 없다고 한 PR 4개에서 CodeRabbit 지적 7건이 반영됐다. #686에서 Claude는 diff 안의 메모리 합계만 맞춰 봤고, CodeRabbit은 apps/*/k8s를 검색해 최대 surge 메모리가 640Mi가 아니라 704Mi라는 걸 찾았다.

AI가 만든 코드를 diff에서만 확인하면 그럴듯하지만 diff 밖에서 불일치가 발생한다. 팀 문서의 규칙, 다른 앱의 설정값, 예전에 내린 결정 등이 같이 수정되지 않기 때문이다. 그래서 #701에서 리뷰 프롬프트를 이렇게 바꿨다.

  • 바뀐 파일에 맞는 팀 문서를 골라 읽는다. 로그 문이면 logging.md, k8s manifest면 k8s.md다.
  • diff에 나온 숫자, 이름, 설정 키는 Grep으로 다른 코드, 설정, 문서와 맞는지 본다.
  • 바뀐 테스트는 의도한 경로를 실제로 타는지 본다.
  • 기준 문서는 PR이 아니라 dev 브랜치에서 꺼낸다. AGENTS.md를 고친 PR이 자기 리뷰 기준을 바꾸지 못하게 하려는 것이다.
인라인 리뷰가 달린 PR 비율의 증가
전체
이전11% PR 91개 중 10개
이후77% PR 39개 중 30개
Infra
이전12% PR 52개 중 6개
이후81% PR 26개 중 21개
Lecture
이전0% PR 19개 중 0개
이후83% PR 6개 중 5개
Others
이전20% PR 20개 중 4개
이후57% PR 7개 중 4개

이전: 10. 15 ~ 11. 05 / 이후: 11. 05 ~ 11. 18

인라인 리뷰 수는 11건에서 69건이 됐다. 리뷰가 늘었다고 맞는 지적을 했다는 뜻은 아니다. 그래서 이 지적에 관해 답글을 어떻게 했는지로 나눠 봤다. 69건 중 42건은 고쳤고, 22건은 일부만 고치고 나머지는 이유를 남겼다. 이유만 적고 고치지 않은 건 2건이다.

기억에 남는 지적은 #721의 "REPEATABLE_READ 효과를 검증하는 테스트가 없다"다. 누군가 isolation을 지워도 모든 테스트가 통과한다는 얘기였다. 테스트를 추가하고 isolation을 지우면 실패하는 것까지 확인했다. 이게 프롬프트에 넣은 테스트 규칙이 그대로 작동한 경우다.


한계

  • 계획 검토의 깊이가 고르지 않다. 코드 수정까지 간 /plan-ticket 약 20번 중 약 9번은 선택지 고르기, "추천대로", 승인 한마디로 끝났다.
  • 테스트를 결국 확인해야 했다. AI 에이전트가 작성한 테스트 케이스가 내 의도를 제대로 반영하는지 확인하는 과정은 결국 필요했다.
  • 리뷰가 버그나 불일치를 완전히 찾지 못한다. 문서의 계획과 기능 구현의 불일치를 100% 잡기 어려웠다. 문서의 수가 많았고 완전히 내용을 분리하지 않아 logging의 구현 내용이 monitoring에도 들어가 있었다.

구현을 맡기고 나니 내 일은 코드를 쓰는 것에서 어디서 멈출지 정하는 쪽으로 옮겨 갔다. 세 곳 모두 에이전트가 만든 결과를 diff 밖의 기준, 즉 티켓의 완료 조건과 팀 문서와 운영 환경에 대 보는 자리였다.

댓글

다른 글

EC2 두 대짜리 k3s에서 메모리가 모자라 Spring Boot 앱 하나를 GraalVM Native Image로 바꾼 이야기@Controller와 @RestController의 차이점