techlist.io
KR EN
github

거대한 AI 생성 풀 리퀘스트 하나를 검토 가능한 스택으로 바꾸기 (새 탭에서 열림)

githubcontinuous-integrationapi-designcoding-agentsgithub-clistacked-pull-requests

AI 코딩 에이전트는 짧은 시간에 대규모 기능을 구현하지만, 모든 변경을 하나의 거대한 PR에 담는 방식은 리뷰 품질과 병합 속도를 떨어뜨린다. 이 글은 기능을 데이터·API·애플리케이션 연결·UI처럼 논리적 계층으로 나누고, 각 계층을 작은 PR로 쌓는 “스택드 풀 리퀘스트(stacked pull requests)”를 대안으로 제시한다. 이를 통해 에이전트의 생산성은 유지하면서도 각 변경을 독립적으로 검토하고 관리할 수 있다.

AI가 만든 대규모 PR의 문제

  • 쇼핑 어시스턴트에 상품 검색 기능을 추가하면 다음 변경이 한 PR에 함께 들어가기 쉽다.
    • 새 데이터 모델과 시드 데이터
    • API 라우트와 입력 검증
    • 클라이언트 연결
    • UI 및 빈 상태·오류 상태·대체 상태
  • 결과적으로 1,000~1,700줄 이상의 큰 diff가 만들어질 수 있다.
  • 리뷰어는 변경 내용을 한 번에 이해하기 어렵고, PR 설명이 길지만 구체적이지 않으면 검토를 뒤로 미루게 된다.
  • 리뷰가 늦어지면서 문맥이 사라지고 피드백 품질이 낮아지며, 충돌과 수동 동기화가 늘어난다.
  • 결국 기능이 충분히 검토되지 않은 채 병합될 위험이 커진다.

스택드 풀 리퀘스트의 기본 원리

  • 하나의 대형 PR 대신 기능을 논리적으로 분해해 여러 개의 작은 PR로 만든다.
  • 각 PR은 하나의 관심사만 다루며, 리뷰어가 한 번에 이해할 수 있는 크기로 제한한다.
  • PR은 의존성 순서에 따라 연결된다.
    • 하위 계층이 먼저 구현되고, 상위 계층은 그 변경을 기반으로 작업한다.
  • 이전 계층에서 얻은 문맥은 다음 계층으로 자연스럽게 이어지므로, 전체 기능을 매번 처음부터 읽을 필요가 없다.
  • 데이터 담당자, 백엔드 담당자, UI 담당자처럼 변경 영역에 맞는 리뷰어를 배정할 수 있다.

상품 검색 기능의 스택 구조

계층 브랜치 작업 내용 의존 대상
L1 feat/catalog-data 타입이 지정된 카탈로그, 시드 데이터, 검증, 데이터 접근 모듈 main
L2 feat/search-api 검증을 포함한 /api/products/search 엔드포인트 L1
L3 feat/chat-grounding 채팅이 API를 호출하고 실제 상품 데이터에 기반해 응답 L2
L4 feat/grounded-ui 상품 인용 카드와 UI 상태 처리 L3
  • 데이터, API, 애플리케이션 연결, UX가 각각 독립된 작업 단위가 된다.
  • 각 계층은 자체적으로 리뷰할 수 있지만, 전체 기능은 계층 간 의존성을 통해 완성된다.
  • 가장 기반이 되는 작업을 스택의 아래쪽에 배치하고, 그 위에 이를 사용하는 작업을 쌓는다.

GitHub 도구와 초기 설정

  • GitHub는 PR 화면뿐 아니라 터미널에서도 스택드 PR을 관리할 수 있다.
  • gh-stack CLI 확장 설치:
gh extension install github/gh-stack
  • 코딩 에이전트가 스택 구조를 이해하고 생성·관리하도록 관련 스킬을 설치할 수 있다.
gh skill install github/gh-stack

또는:

npx skills add github/gh-stack
  • 스택을 시작하기 전에 스택의 기준 브랜치(stack base)를 정해야 한다.
    • 일반적으로 main이 기준이 된다.
    • CI 검사와 병합 규칙이 전체 스택에서 이 기준을 바탕으로 평가된다.
  • 모든 계층에 CI가 존재하는지 확인해야 한다.
    • 각 PR 계층마다 CI 검사가 실행된다.
    • 따라서 작은 PR이라도 테스트와 규칙 검증을 통과해야 한다.

에이전트별 작업 분담

  • 에이전트에게 전체 기능을 한 번에 맡기기보다, 계층별로 역할과 범위를 지정한다.
  • 예시 구성:
    • L1: 데이터 모델러 에이전트
    • L2: 백엔드 에이전트
    • L3: 프론트엔드 에이전트
    • L4: 프론트엔드 에이전트
  • 각 에이전트는 하나의 작업 스트림과 엄격한 범위를 따르도록 구성한다.
  • 이런 방식은 에이전트가 자동화 루프에서 작업하더라도 결과물이 지나치게 커지는 것을 방지한다.
  • 작업 순서는 데이터 기반을 먼저 만들고, API, 채팅 연결, UI 순으로 진행한다.

실용적인 적용 방법

  • 기능을 시작할 때 먼저 데이터·도메인 모델·API·애플리케이션 연결·UI로 나눈다.
  • 각 PR이 단일 관심사만 포함하는지 확인한다.
  • 기반 브랜치를 먼저 만들고, 각 후속 브랜치를 바로 이전 계층에서 파생한다.
  • 계층별로 적절한 리뷰어를 배정하고, 각 PR에 해당 계층의 목적과 검증 방법을 명확히 작성한다.
  • AI 에이전트에는 “전체 기능 구현”이 아니라 특정 스택 계층과 변경 범위를 명시하는 것이 좋다.
  • 스택드 PR은 리뷰 부담을 줄이는 대신 브랜치 의존성을 관리해야 하므로, CLI와 자동화 도구를 함께 사용하는 것이 효과적이다.