GitHub Copilot 코딩 에이전트에 이슈를 맡기는 비동기 워크플로우

이슈를 사람이 하나씩 붙잡고 처리하면 컨텍스트 전환 비용이 크고, 반대로 아무 이슈나 그대로 에이전트에 던지면 엉뚱한 PR이 돌아온다. GitHub Copilot 코딩 에이전트는 이슈를 할당받아 백그라운드에서 코드를 고치고 초안 PR을 만드는 비동기 워커인데, 결과 품질은 이슈를 얼마나 작업 지시서답게 다듬었는지에 거의 좌우된다. 이 글은 어떤 일을 맡기고 어떤 일은 맡기지 말아야 하는지부터, 이슈 템플릿, 저장소 권한, 그리고 결과 PR을 검증하는 순서까지 실무 흐름대로 정리한다.

비동기 에이전트에 어울리는 작업과 그렇지 않은 작업

비동기 에이전트의 강점은 사람이 지켜보지 않는 동안에도 작업이 진행된다는 점이다. 그래서 경계가 분명하고, 재현이 가능하며, 완료 여부를 자동화된 테스트로 확인할 수 있는 작업에 잘 맞는다. 반대로 요구사항이 계속 흔들리거나, 정답이 팀의 암묵지 안에 있거나, 한 번의 대화로 방향을 잡아야 하는 탐색적 작업은 사람이 붙잡는 편이 낫다.

실무에서는 "이 정도면 사람이 30분에 하는데" 싶은 잔무가 오히려 좋은 후보다. 문서 오탈자 수정, 의존성 업데이트에 따른 테스트 보정, 명확한 스펙의 단순 API 추가처럼 검증 비용이 낮은 일부터 맡기면 팀이 결과를 신뢰하는 데 걸리는 시간이 줄어든다.

또 하나 중요한 기준은 실패했을 때 되돌리기 쉬운가다. 비동기 작업은 사람이 지켜보지 않으므로 문제가 생기면 한참 뒤에 발견된다. 그래서 큰 작업을 한 번에 맡기기보다 작은 단위로 자주 결과를 받아 확인하는 편이 안전하다. 첫 시도에서는 아주 좁은 범위를 맡기고, 결과가 기대에 맞으면 다음 이슈에서 범위를 조금씩 넓히는 방식이 안정적이다.

이슈를 작업 지시서로 다듬는 방법

에이전트는 대화 맥락을 공유하지 않는다. 이슈 본문에 적힌 것만 읽고 움직인다. 그래서 이슈를 할당하기 전에 지시서 수준으로 다듬는 단계가 반드시 필요하다. 제목에 무엇을 어디서 바꾸는지 드러내고, 본문에는 재현 절차, 기대 동작, 완료 조건, 건드리지 말아야 할 범위를 명시한다.

재현 절차·완료 조건·범위를 명시하기

1. 재현 절차: 어떤 명령, 어떤 입력, 어떤 환경에서 문제가 나는지 순서대로 적는다.
2. 기대 동작: 지금 나오는 값과 나와야 하는 값을 분리해 적는다.
3. 완료 조건: 통과해야 하는 테스트 이름, 확인해야 하는 화면, 갱신해야 하는 문서를 나열한다.
4. 범위: 변경을 허용할 디렉터리와 손대지 말아야 할 모듈을 함께 적는다.

완료 조건이 "동작하게 만든다"처럼 추상적이면 에이전트는 가장 적은 변경으로 끝내려 하고, 그 결과가 리뷰에서 되돌아온다. 테스트 명령 한 줄, 기대 응답 한 줄처럼 확인 가능한 형태로 적는 것이 핵심이다.

에이전트에 부여할 권한과 저장소 설정

코딩 에이전트는 저장소 읽기와 브랜치 생성, PR 생성 권한이 필요하다. 반대로 메인 브랜치 직접 푸시, 시크릿 접근, 배포 권한은 주지 않는 것이 기본이다. 저장소 설정에서 에이전트가 만든 PR이 반드시 리뷰를 거치도록 하고, 보호 규칙으로 직접 머지를 막아 두면 사고 반경이 크게 줄어든다. CI가 필수 체크로 걸려 있으면 에이전트가 스스로 실패를 고치는 루프도 자연스럽게 돈다.

자동화된 파이프라인에서 정적 분석과 린트가 통과되도록 GitHub Actions AI 코드 리뷰 봇 워크플로우를 연계해 두면 사람이 리뷰하기 전에 기본 품질 검사를 자동으로 마칠 수 있다.

# 보호 규칙 예시 (개념)
main:
  require_pull_request: true
  required_checks: [lint, test, typecheck]
  allow_direct_push: false
  require_review: true

권한은 저장소 단위로 최소화하고, 여러 저장소에 한꺼번에 열지 않는다. 한 저장소에서 결과가 안정된 뒤에 다음 저장소로 넓히는 편이 안전하다.

결과 PR을 검증하는 순서

1. CI 결과와 실제 변경 범위를 먼저 확인한다. 요청한 파일 밖을 건드렸다면 그 이유를 확인한다.
2. 테스트가 실제로 문제를 잡는지 본다. 통과한 테스트가 요청과 무관한 것일 수 있다.
3. 재현 절차를 로컬에서 다시 실행해 기대 동작을 확인한다.
4. 롤백 시나리오와 마이그레이션 유무를 점검한다.
5. 필요하면 커밋을 쪼개거나 리베이스해 리뷰 단위를 정리한다.

AI가 만든 PR이 여러 개 쌓이면 서로 충돌하기 쉬우므로, AI 생성 PR 스태킹 리뷰 워크플로우처럼 처리 순서를 미리 정해 두는 편이 좋다.

실패 사례와 비용·보안 주의점

가장 흔한 실패는 이슈가 부실한 채로 맡겨 엉뚱한 파일을 고치는 경우다. 두 번째는 테스트 없이 리팩터링을 맡겨 동작이 미묘하게 바뀌는 경우다. 세 번째는 동시에 여러 에이전트를 돌려 같은 파일에서 충돌이 나는 경우다. 동시 실행 수를 제한하고, 파일 경계가 겹치는 이슈는 순차로 돌리는 규칙이 필요하다.

비용은 실행 시간과 모델 호출량에 비례한다. 큰 저장소에서 무관한 파일까지 읽게 만들면 비용이 빠르게 늘어나므로, 이슈에 관련 디렉터리를 명시해 탐색 범위를 줄인다. 보안 측면에서는 시크릿이 담긴 파일이나 운영 설정을 이슈 본문에 붙이지 말고, 에이전트가 만든 PR의 diff에 토큰이 섞이지 않았는지 머지 전에 확인한다.

운영에 익숙해지면 실패 유형을 기록해 두는 것이 좋다. 어떤 표현의 이슈에서 결과가 자주 어긋나는지, 어떤 저장소에서 실행 시간이 길어지는지를 모아 두면 템플릿과 동시 실행 수를 조정하는 근거가 된다. 결국 비동기 위임은 한 번의 대형 작업이 아니라, 작은 작업을 반복해서 안정적으로 흘려보내는 운영 체계에 가깝다.