끌어오기 요청에 AI 생성 코드 쌓기

대규모 풀 리퀘스트는 검토하기 어렵고 병목을 초래하며, 특히 AI가 짧은 시간에 대량의 코드를 생성하는 데 도움이 되는 경우 더욱 그렇습니다. 끌어오기 요청 크기가 증가함에 따라 검토 품질도 저하됩니다. 검토자는 결과를 대충 훑어보거나, 문제를 누락하거나, 미루고, 부실해지고 병합 충돌이 발생할 때까지 풀 리퀘스트를 방치해 오래되게 둘 수 있습니다.

스택형 pull request는 큰 코드 변경 내용을 검토할 수 있도록 유지합니다.

스택은 동일한 리포지토리에 있는 일련의 끌어오기 요청으로, 각 끌어오기 요청이 아래 끌어오기 요청의 분기를 대상으로 하여 단일 분기(일반적으로 주 분기)에 배치되는 순서가 지정된 체인을 형성합니다. 하나의 큰 끌어오기 요청 대신 더 작은 끌어오기 요청 집합을 가져옵니다. 각 끌어오기 요청에는 고유한 포커스가 있는 diff가 있으므로 팀원은 각 계층을 독립적으로 검토하고 승인할 수 있습니다.

이 자습서에서는 에이전트와 함께 스택형 pull request를 사용하여 개별적으로 검토 가능한 계층에서 기능을 빌드하는 방법을 안내합니다. 이 예제에서는 앱에 사용자 인증을 추가하는 방법을 살펴보겠습니다. 우리는 GitHub Copilot CLI와 gh-stack 에이전트 스킬을 사용합니다.

사전 요구 사항

에이전트와 함께 gh-stack 스킬을 사용하려면 먼저 GitHub CLI 및 gh-stack CLI 확장을 설치해야 합니다. 다음 항목이 필요합니다.

• GitHub CLI (gh) 2.90.0 이상 및 Git 2.20 이상
  • GitHub CLI를 gh auth login로 인증하십시오.
• GitHub 푸시할 수 있는 리포지토리입니다.
• GitHub Copilot CLI 설치되었고 로그인됨.

GitHub CLI에서 gh-stack 확장 및 스킬을 설치합니다.

gh extension install github/gh-stack
gh skill install github/gh-stack

1. 코드를 생성하기 전에 스택을 설계하세요

좋은 스택은 집을 짓는 것과 같습니다. 강한 기초로 시작하고, 벽 골조를 세우고, 배선을 설치한 다음, 건식 벽체를 마감합니다. 각 계층은 아래 계층 위에 구축됩니다. 결국 검토자는 아래에서 위로 풀 리퀘스트를 읽고 기능이 완성되어 가는 과정을 따라갈 수 있어야 합니다.

• 기능을 레이어로 분할합니다. 각 계층은 자체적으로 검토할 수 있는 일관된 단일 변경이어야 합니다.
  • 각 계층을 풀 리퀘스트를 빠르게 읽을 수 있을 만큼 작게 유지합니다. 레이어를 검토하려면 긴 설명이 필요하다고 느껴진다면 너무 클 수 있습니다.
  • 경계를 직접 결정하거나 Copilot와 함께 계획을 세우세요. 어느 쪽이든 스택의 형태를 결정합니다.
• 종속성별로 레이어를 정렬합니다. 기본 변경 내용은 맨 아래에 있습니다. 그들에 의존하는 모든 것은 함께 증가합니다. 인증의 경우 다음과 같습니다.
  • 계층 1: 데이터 모델 및 마이그레이션
  • 계층 2: CRUD 엔드포인트
  • 계층 3: JWT 미들웨어 및 가드
  • 계층 4: 통합 및 단위 테스트

예시 프롬프트

• Propose a layered approach to add user authentication to this app. Order the layers by dependency, keeping each layer independently reviewable.
• Review my planned layers and flag any that are too large or that depend on a branch above them.

2. 맨 아래 계층을 먼저 빌드합니다.

기초를 바탕으로 스택을 시작합니다. 위의 모든 항목은 이 계층을 올바르게 구현하는 데 따라 달라집니다.

• Copilot에 누적 풀 리퀘스트를 빌드할 것이라고 알리고 계획에 따라 첫 번째 계층을 빌드하도록 요청합니다. 에이전트는 이 gh-stack 스킬을 사용하여 스택의 첫 번째 분기를 만듭니다.
• 스택을 직접 만들고 싶다면 gh stack init로 직접 만드세요. 분기 이름을 깔끔하게 유지하려면 예를 들어 gh stack init BRANCH-NAME-1 같은 접두사를 사용하세요.
• 계속 진행하기 전에 생성된 변경 사항을 직접 검토하세요. 아래쪽 계층의 실수가 위의 모든 분기에 전파되므로 계속 진행하기 전에 검토하세요.

예시 프롬프트

• Start the pr-stack and build only the first layer: the user data model and migration.
• Conduct a review of the generated code and confirm this branch contains only the data model and migration, and nothing that belongs in a later layer.

3. 각 새 코드 계층을 위에 쌓습니다.

기반이 마련되면 기능의 나머지 부분을 한 번에 한 계층씩 빌드합니다.

• Copilot에게 다음 계층을 추가하고 아래 계층의 컨텍스트에서 구현하도록 요청합니다. 에이전트는 스택의 맨 위에 브랜치를 추가하고 그곳에서 작업을 커밋합니다.
• 브랜치를 직접 추가하려면 gh stack add BRANCH-NAME-NEXT를 사용합니다.
• 레이어가 너무 커지게 되면 계획 외부로 드리프트되었는지 아니면 실제로 하나 대신 두 개의 레이어가 필요한지 고려합니다.
• 진행하면서 각 계층에 대해 새 브랜치를 만들면 모든 브랜치가 깨끗하고 독립적인 변경 사항(diff)으로 유지됩니다.
• 끌어오기 요청을 만들 준비가 되면 스택을 제출해 달라고 Copilot에 요청하거나 직접 수행하려면 gh stack submit을 사용합니다.
• 각 pull request가 독립적으로 완결되도록 합니다. 포커스가 있는 제목과 레이어에 대한 간결하고 의미 있는 설명만으로도 충분합니다.

예시 프롬프트

• Add the next layer in a new branch on top: the CRUD endpoints that use the user model from the branch below.
• This branch is getting large. Suggest how it could be split into two independently reviewable layers.

4. 검토를 요청하기 전에 풀 리퀘스트를 직접 검토합니다.

각 레이어는 작기 때문에 자체 검토도 더 쉬워집니다. 팀원을 참여시키기 전에 모든 브랜치를 한 번씩 확인하세요. 검토자는 사용자가 이미 신뢰하는 변경 사항을 받아야 합니다.

• 각 브랜치에서 테스트, linter 및 코드 검사를 실행합니다. 검토를 요청하기 전에 Copilot이 각 계층을 표준에 맞춰 확인하도록 하세요.
• AI 생성 변경 내용을 철저히 검토하는 방법에 대해서는 AI 생성 코드 검토을 참조하세요.

5. 맨 아래에서 시작하여 스택에 대한 검토 요청

레이어가 빌드되면 검토자는 큰 코드 벽 대신 작은 변경 사항을 확인할 수 있습니다.

• 종속성이 강력하게 통합된 경우 스택의 맨 아래에서 시작하여 검토를 요청하면 후속 검토 전에 변경 내용을 스택의 상위 단계에 반영할 수 있습니다.
• 서로 다른 계층에 대해 별도의 사람들로부터 검토가 필요한 경우 검토자는 병렬로 작업할 수 있습니다. 한 사람은 데이터 모델을 검토할 수 있고 다른 사용자는 엔드포인트를 검토하며, 어느 쪽도 전체 기능을 전부 훑어볼 필요는 없습니다.

6. 피드백을 바탕으로 반복 개선

피드백은 전체 기능이 아닌 개별 레이어에 달립니다. 스택을 사용하면 올바른 계층을 제자리에 고정하고 변경 사항을 상위 계층으로 전파할 수 있습니다.

• 검토자가 플래그를 지정한 계층을 수정하도록 Copilot에 요청합니다. 에이전트가 오른쪽 분기로 이동하여 변경을 수행하고 그곳에 커밋합니다. 그런 다음 위의 레이어를 리베이스하여 수정 사항이 반영되도록 합니다.
• 각 수정 사항은 속한 레이어에 두세요. 잘못된 분기에서 변경한 내용은 혼동을 일으키고 상위 스택에서 오류를 일으킬 수 있습니다.
• 수정할 때 Copilot에게 위의 분기를 다시 기반으로 설정하고 변경 내용을 전파하도록 요청합니다.
• 스택을 직접 따라 이동하려면 gh stack down, gh stack up 또는 gh stack checkout BRANCH-NAME를 사용하여 분기를 탐색합니다. 그런 다음 변경 내용을 커밋하고 gh stack rebase --upstack를 실행하여 변경 내용을 스택 상위에 반영합니다.

예시 프롬프트

• A reviewer flagged that the auth service doesn't handle expired tokens. Fix that on BRANCH-NAME and test the changes.
• I've rebased the layers above onto this fix. Check that the branch with endpoints still works with the change and flag anything that needs updating.

7. 아래쪽 계층에서 병합

스택은 기본 분기를 가리키는 계층에서 시작하여 순서대로 병합됩니다. 레이어를 한꺼번에 병합하거나 하나씩 병합하면 GitHub가 자동으로 다음 레이어가 main을 가리키도록 다시 지정합니다.

• 스택을 맨 아래에서 위로 한 번에 하나씩 병합하거나, 스택의 어느 위치에서든 병합할 수 있으며, 이 경우 병합한 풀 리퀘스트 아래의 모든 브랜치는 맨 아래에서 위로 병합됩니다.
• 각 레이어의 diff는 부모에 대해 정확히 동일하게 유지되며 베이스만 변경되므로 진행 중인 작업이나 검토에 영향을 주지 않고 한 번에 레이어를 쉽게 병합할 수 있습니다.
• 자동 병합 또는 병합 큐를 사용하면 각 레이어가 승인되고 검사가 통과되는 즉시 병합됩니다. 전체 스택이 한꺼번에 완료되기를 기다릴 필요는 없습니다.

최상위 계층이 병합되면 전체 기능이 반영된 것입니다. 모든 조각은 하나의 큰 풀 리퀘스트보다는 작고 의도적인 변화로 더 효과적으로 검토되었습니다.

추가 읽기

• AI 생성 코드 검토
• 스택형 풀 리퀘스트 관리