AI 코딩 에이전트가 기능 하나를 통째로 구현하면 결과물은 빠르게 나오지만, 검토 속도까지 빨라지는 것은 아닙니다. 데이터 모델, API, 화면 연결, 오류 상태, 테스트가 하나의 대형 풀 리퀘스트에 섞이면 변경 목적과 의존 관계를 파악하기 어려워집니다. GitHub가 제안한 방식은 이 결과물을 논리적인 계층으로 분해해, 순서와 의존성이 드러나는 여러 개의 스택형 풀 리퀘스트로 전달하는 것입니다.
핵심은 풀 리퀘스트 수를 늘리는 데 있지 않습니다. 한 번에 판단할 범위를 줄이고, 기반 작업부터 사용자 경험까지 검토 순서를 명확하게 만드는 것이 목적입니다. 개인 프로젝트에서는 AI가 생성한 코드를 실제로 읽고 검증하기 쉬워지고, 팀에서는 데이터·백엔드·프런트엔드 담당자에게 적절한 검토 단위를 배정할 수 있습니다.
대형 AI 풀 리퀘스트가 문제가 되는 이유
GitHub가 제시한 예시는 기존 웹 애플리케이션에 상품 검색 기능을 추가하는 상황입니다. 출발점에는 임의의 문장을 응답하는 모의 AI 도우미가 있고, 상품 데이터는 여러 컴포넌트에 일관성 없이 들어가 있습니다. 별도의 카탈로그 모듈이나 API, 데이터 계층도 없습니다.
이 상태에서 코딩 에이전트에게 상품 검색 구현을 한 번에 맡기면 다음 변경이 하나의 풀 리퀘스트에 모일 수 있습니다.
- 상품 데이터 모델과 초기 데이터
- 데이터 검증 및 접근 모듈
- 검색 API 경로와 입력 검증
- 클라이언트와 API 연결
- 검색 결과를 활용하는 대화 응답
- 상품 인용 카드와 빈 상태·오류 상태 등 사용자 인터페이스
- 관련 테스트와 설정 변경
원문 사례에서는 이런 결과가 1,000줄을 넘는 변경으로 커질 수 있고, 실제 검토 화면에는 1,721줄의 변경이 나타납니다. 줄 수만으로 품질을 판단할 수는 없지만, 서로 다른 관심사가 한 변경 묶음에 들어가면 검토자는 데이터 구조와 API 계약, 화면 동작을 동시에 기억해야 합니다. 설명까지 얕거나 추상적이면 검토가 미뤄지고, 시간이 흐를수록 작성자와 검토자 모두 변경 맥락을 잃기 쉽습니다.
AI가 코드를 빨리 작성한다는 사실은 이 문제를 자동으로 해결하지 않습니다. 오히려 사람이 읽고 검증할 수 있는 속도보다 코드 생성 속도가 빨라지면 검토 대기열이 병목이 됩니다. 따라서 에이전트의 생산성을 평가할 때는 생성 시간뿐 아니라 검토 시간, 수정 횟수, 병합까지 걸린 시간과 결함 발견 시점도 함께 봐야 합니다.
스택형 풀 리퀘스트는 무엇이 다른가
스택형 풀 리퀘스트는 하나의 목표를 작은 논리 계층으로 나누고, 각 계층의 의존 관계를 순서대로 연결합니다. 아래쪽에는 다른 작업이 의존할 기반을 놓고, 그 위에 API와 기능 연결, 사용자 경험을 차례로 쌓습니다. 각 풀 리퀘스트는 하나의 관심사에 집중하되, 전체 스택을 합치면 원래 목표가 완성되는 구조입니다.
상품 검색 사례는 다음과 같이 나눌 수 있습니다.
| 계층과 브랜치 | 담당 변경 | 의존 대상 | 주요 검토 관점 |
|---|---|---|---|
| L1: feat/catalog-data | 타입이 정의된 상품 카탈로그, 초기 데이터, 검증, 데이터 접근 모듈 | main | 타입, 데이터 일관성, 검증 규칙 |
| L2: feat/search-api | 검증을 포함한 /api/products/search 엔드포인트 | feat/catalog-data | API 계약, 입력 검증, 실패 처리 |
| L3: feat/chat-grounding | 대화 기능이 검색 API를 호출하고 실제 상품 데이터를 사용하도록 연결 | feat/search-api | 데이터 흐름, 응답 정확성, 예외 처리 |
| L4: feat/grounded-ui | 상품 인용 카드와 관련 화면 상태 | feat/chat-grounding | 사용자 경험, 빈 결과, 로딩·오류 상태 |
이 구조에서는 데이터 담당자가 첫 계층을, 백엔드 담당자가 API 계층을, UI 담당자가 마지막 계층을 집중적으로 볼 수 있습니다. 검토자는 전체 기능을 매번 처음부터 이해할 필요 없이 이미 확인된 기반 위에서 새로 추가된 관심사에 집중할 수 있습니다.
다만 스택을 만들었다고 각 풀 리퀘스트가 완전히 독립되는 것은 아닙니다. 위쪽 계층은 아래쪽 계층에 의존하므로 기반 API나 데이터 구조가 바뀌면 후속 계층도 영향을 받을 수 있습니다. 좋은 스택은 단순히 변경 줄 수를 비슷하게 나눈 것이 아니라, 변경 이유와 검토 책임이 분명한 경계를 가진 구조여야 합니다.
가장 먼저 정해야 할 것은 스택 기준점이다
GitHub의 설명에서 중요한 설정은 스택의 기준점입니다. CI 검사와 병합 규칙이 스택 관리 과정에서 이 기준점을 바탕으로 평가되기 때문입니다. 예시에서는 main을 기준으로 두고, 가장 기초적인 카탈로그 데이터 작업을 첫 번째 계층에 배치합니다.
적용 전에는 다음 질문에 답할 수 있어야 합니다.
- 스택이 최종적으로 병합될 대상 브랜치는 어디인가?
- 해당 브랜치에 적용된 필수 검사와 병합 보호 규칙은 무엇인가?
- 각 계층에서 같은 CI 검사를 실행할 수 있는가?
- 아래 계층의 변경 요청이 위 계층에 미치는 영향을 누가 관리하는가?
- 일부 계층만 승인됐을 때 작업 상태를 어떻게 공유할 것인가?
원문은 각 풀 리퀘스트가 스택 기준점을 상대로 평가되고 모든 계층에 검사가 실행된다고 설명합니다. 따라서 CI가 없거나 중요한 동작을 검사하지 못하는 저장소라면 스택 도구부터 도입하기보다 기본 테스트와 필수 검사를 먼저 정비하는 편이 안전합니다. 풀 리퀘스트를 잘게 나눠도 자동 검증의 빈틈까지 사라지는 것은 아닙니다.
코딩 에이전트에는 분해 규칙도 함께 가르쳐야 한다
사람이 스택 구조를 이해해도 에이전트가 기능 전체를 한 브랜치에 작성하면 같은 문제가 반복됩니다. GitHub의 사례에서는 작업 흐름별로 사용자 지정 에이전트를 두고, 각 에이전트가 작고 단일 범위인 풀 리퀘스트를 만들도록 엄격한 범위 규칙을 적용합니다. 데이터 모델링, 백엔드 API, 프런트엔드 연결과 UI를 서로 다른 작업 흐름으로 배정한 것도 이 때문입니다.
에이전트에게는 “상품 검색을 구현하라”는 최종 목표만 주기보다 다음 제약을 함께 전달하는 편이 실용적입니다.
- 먼저 기반 데이터, API, 기능 연결, UI로 의존 관계를 분해합니다.
- 각 계층이 담당하는 파일과 동작을 명시합니다.
- 한 계층에서 다음 계층의 UI나 API 구현을 미리 섞지 않도록 제한합니다.
- 계층별 검증 명령과 완료 조건을 정합니다.
- 변경 목적, 의존 대상, 검증 결과를 각 풀 리퀘스트 설명에 남깁니다.
- 검사 실패 시 커밋과 다음 계층 생성을 진행하지 않고 해당 계층을 수정합니다.
원문은 첫 계층의 일반적인 흐름으로 에이전트 호출, 스택 초기화와 브랜치 설정, 작업 및 검증, 검사가 통과한 경우 커밋하고 그렇지 않으면 반복 수정하는 과정을 제시합니다. 여기서 중요한 운영 기준은 “코드 생성 완료”가 아니라 “해당 계층의 검증 완료”입니다.
도구 설치보다 먼저 확인할 조건
GitHub는 풀 리퀘스트 화면에서 스택형 풀 리퀘스트를 시작할 수 있고, 터미널에서는 gh stack CLI를 사용할 수 있다고 안내합니다. 원문에 제시된 CLI 확장 설치 명령은 gh extension install github/gh-stack입니다. 에이전트가 스택 생성과 관리를 학습하도록 하는 스킬 설치 명령으로는 gh skill install github/gh-stack이 소개되며, 대안으로 npx skills add github/gh-stack도 제시됩니다.
다만 제공된 정보만으로는 계정별 제공 범위, 조직 정책, 권한 요구 사항, 요금 조건을 확정할 수 없습니다. 실제 저장소에 적용하기 전에는 현재 GitHub 계정과 조직에서 기능을 사용할 수 있는지, CLI 확장과 스킬을 설치할 권한이 있는지, 조직의 승인된 도구 정책에 부합하는지를 공식 문서에서 확인해야 합니다.
| 항목 | 확인할 질문 | 적용 기준 |
|---|---|---|
| 제공 범위 | 개인·조직 저장소와 현재 계정 유형에서 사용할 수 있는가? | 실제 대상 저장소에서 지원 여부를 확인한 뒤 시험 적용 |
| 권한 | 확장, 스킬, 브랜치와 풀 리퀘스트를 만들 권한이 있는가? | 최소 권한으로 실행할 수 있고 조직 정책을 충족해야 함 |
| CI | 모든 계층에 필요한 검사가 실행되는가? | 각 계층의 독립 검증과 전체 기능 검증 경로가 있어야 함 |
| 병합 규칙 | 보호 브랜치와 필수 승인 규칙이 스택 구조와 맞는가? | 기존 규칙을 우회하지 않고도 순서대로 검토할 수 있어야 함 |
| 복구 | 아래 계층이 변경되거나 폐기될 때 후속 계층을 정리할 수 있는가? | 브랜치와 의존 관계를 추적하고 되돌리는 절차가 있어야 함 |
| 비용 | 별도 플랜이나 사용량 조건이 적용되는가? | 공식 가격표와 계정 화면에서 확인하기 전에는 비용을 가정하지 않음 |
작게 시험할 때 측정할 것
첫 적용부터 장기간 진행되는 핵심 기능 전체를 스택으로 옮길 필요는 없습니다. 데이터 계층, 간단한 API, 작은 화면 변경처럼 의존 관계가 눈에 보이는 기능 하나를 골라 기존 방식과 비교하는 편이 좋습니다.
- 풀 리퀘스트 하나당 검토에 걸린 시간
- 첫 검토가 시작되기까지의 대기 시간
- 계층별 수정 요청 횟수와 수정 범위
- 아래 계층 변경으로 다시 작업한 후속 계층 수
- CI 실패를 발견한 계층과 원인
- 최종 기능을 수동으로 검증하는 데 걸린 시간
- 브랜치 동기화와 충돌 해결에 든 시간
- 병합 후 발견된 누락이나 회귀 여부
스택이 성공적인지는 풀 리퀘스트가 작아졌다는 사실만으로 판단하기 어렵습니다. 검토 품질이 좋아지고, 피드백이 더 이른 계층에서 발생하며, 전체 병합 시간이 예측 가능해져야 실제 이점이 있습니다. 반대로 계층을 지나치게 잘게 나눠 설명과 동기화 비용만 커졌다면 경계를 다시 합치는 것이 낫습니다.
개발자 유형별 판단 기준
개인 개발자와 학생
혼자 작업하더라도 스택은 AI 생성 코드를 단계별로 학습하고 검증하는 장치가 될 수 있습니다. 데이터 구조를 확인한 뒤 API로 넘어가고, 마지막에 화면을 연결하면 오류가 생긴 위치를 좁히기 쉽습니다. 다만 작은 과제나 파일 몇 개의 수정까지 모두 스택으로 만들면 관리 부담이 더 클 수 있으므로, 서로 다른 관심사가 세 개 이상 섞이거나 변경을 한 번에 이해하기 어려울 때 우선 검토할 만합니다.
연구자
연구용 코드에서는 데이터 준비, 전처리, 모델 호출, 결과 표시를 계층으로 나누면 재현성과 검토 책임을 분리하기 좋습니다. 민감한 연구 자료나 외부 공개 전 데이터를 에이전트가 다루는 경우에는 스택 구조와 별개로 데이터 보존, 접근 권한, 외부 전송 조건을 먼저 확인해야 합니다.
팀과 CI/CD 관리자
팀에서는 브랜치 보호, 필수 승인, 코드 소유자, 자동 배포 조건과의 충돌을 먼저 점검해야 합니다. 각 계층에 적합한 검토자를 배정할 수 있다는 장점이 있지만, 모든 검토자가 전체 스택의 목표와 현재 상태를 볼 수 있어야 합니다. 일부 계층의 승인이 전체 기능 승인으로 오해되지 않도록 최종 통합 동작의 확인 책임도 명시해야 합니다.
결론
스택형 풀 리퀘스트는 AI가 생성한 많은 코드를 사람이 검토 가능한 순서로 바꾸는 전달 구조입니다. 데이터, API, 기능 연결, UI처럼 의존 관계가 있는 작업을 논리적으로 나누면 검토 범위와 담당자가 선명해집니다. 그러나 도구 설치만으로 좋은 분해가 만들어지지는 않습니다. 스택 기준점, 계층 경계, CI, 병합 규칙, 에이전트의 범위 제한과 복구 절차가 함께 정의돼야 합니다.
도입 여부는 생성 속도보다 검토 가능성을 기준으로 판단하는 것이 좋습니다. 현재 대형 풀 리퀘스트가 자주 대기하고, 서로 다른 담당 영역이 한 변경에 섞이며, AI 생성 코드의 설명과 검증이 부족하다면 작은 기능 하나로 시험할 가치가 있습니다. 기존의 작은 풀 리퀘스트 방식만으로도 충분히 검토되고 있다면, 전환 비용과 의존 관계 관리 부담을 먼저 비교해야 합니다.
출처와 검증
주요 개념, 상품 검색 사례, 계층 구성, 설치 명령과 CI 관련 설명은 GitHub Blog의 Turn one giant AI-generated pull request to a reviewable stack을 기준으로 재구성했습니다. 실제 적용 전에는 해당 글과 연결된 최신 공식 문서에서 계정별 제공 범위, 권한, CLI 사용법, 조직 정책 및 요금 조건을 다시 확인해야 합니다.