GitHub Copilot Agent Mode 실전 가이드 — VS Code에서 자율 코딩 에이전트 쓰는 법

GitHub Copilot을 인라인 자동완성 도구로만 쓰고 있다면 절반도 못 쓰고 있는 거예요.

2026년 기준 Copilot에는 4가지 에이전트가 있어요.

1. Local Agent    — 실시간, VS Code 안에서 동작
2. Plan Agent     — 실행 전 계획 먼저 세우기
3. Background     — 백그라운드에서 병렬 작업
4. Cloud Agent    — GitHub 서버에서 비동기 실행 → PR 자동 생성

오늘은 이 4가지를 실전에서 어떻게 쓰는지 다 다뤄요.

---

사전 준비

필요한 것:
✅ VS Code 1.99 이상
✅ GitHub Copilot Pro ($19/월) 이상
✅ GitHub Copilot + GitHub Copilot Chat 확장 설치

무료 플랜은 Agent Mode 미포함
→ 인라인 자동완성 + 기본 Chat만 사용 가능

VS Code 설정

// settings.json
{
  "github.copilot.chat.agent.enabled": true,
  "chat.agent.maxRequests": 30,

  // 선택: 웹 브라우징 허용
  "github.copilot.chat.agent.integratedBrowserEnabled": true
}

모델 선택

Agent Mode에서 쓸 모델 고를 수 있어요:

Chat 패널 상단 드롭다운:
- Claude Sonnet 4.6  ← 코딩 기본값 (권장)
- Claude Opus 4.7   ← 복잡한 리팩토링
- GPT-5.4           ← OpenAI 선호 시
- Gemini 3.1 Pro    ← Google 스택

※ 프리미엄 모델은 월 할당량 소진

---

Agent Mode 1 — Local Agent (실시간)

가장 기본. 즉각적인 피드백이 필요할 때.

활성화

VS Code Chat 패널 열기 (Ctrl+Shift+I)
→ 드롭다운에서 "Agent" 선택
→ 프롬프트 입력

실전 예시 1 — 버그 수정

프롬프트:
"src/api/users.py에서 테스트 실행하고 실패하는 거 전부 고쳐줘"

Copilot이 하는 일:

1. 파일 구조 파악
2. pytest 실행 → 실패 케이스 확인
3. 실패 원인 분석
4. 코드 수정
5. 다시 pytest 실행 → 통과 확인
6. 완료 보고

터미널 명령 실행 전에 항상 확인 요청해요:

Copilot: 다음 명령을 실행할까요?
> pytest src/tests/test_users.py -v

[실행] [건너뛰기]

실전 예시 2 — 기능 추가

프롬프트:
"users 테이블에 last_login 컬럼 추가해줘.
마이그레이션 파일, 모델 업데이트, API 응답에 포함까지 다 해줘"

Copilot 실행 흐름:
→ 기존 코드 파악 (SQLAlchemy 모델, Alembic 설정)
→ migrations/versions/xxx_add_last_login.py 생성
→ src/models/user.py 수정
→ src/api/users.py 응답 스키마 업데이트
→ alembic upgrade head 실행
→ 테스트 실행

실전 예시 3 — 코드 리뷰

프롬프트:
"이 PR의 변경사항 리뷰해줘.
보안 취약점, 성능 문제, 코드 스타일 위반 중심으로"

---

Agent Mode 2 — Plan Agent (계획 먼저)

큰 작업 전에 계획을 먼저 세우고 승인 후 실행.

드롭다운 → "Plan" 선택

프롬프트:
"JWT 인증 시스템을 세션 기반으로 전면 교체하는 계획 세워줘"

Copilot [Plan Mode]:
계획:
1. 현재 JWT 구현 위치 파악 (src/auth/)
2. Redis 세션 스토어 의존성 추가
3. 미들웨어 교체 (jwt_required → session_required)
4. 테스트 업데이트 (7개 파일)
5. 환경변수 문서화

예상 변경 파일: 12개
예상 소요 스텝: 8단계

승인하시겠습니까? [예] [수정] [취소]

계획 승인 후 Background Agent에 넘기거나 직접 실행.

---

Agent Mode 3 — Background Agent (병렬 작업)

내가 다른 작업하는 동안 백그라운드에서 돌아가요.

Plan Agent로 계획 수립
→ "Background에서 실행" 선택
→ 다른 브랜치에서 작업 (Git worktree로 격리)
→ 완료되면 알림

실전 시나리오:

[내가 하는 일]          [Background Agent]
feature/new-ui 브랜치   feature/add-tests 브랜치
UI 컴포넌트 작성        기존 코드 테스트 커버리지 80%로 올리기

→ 충돌 없이 병렬 진행

---

Agent Mode 4 — Cloud Agent (이슈 → PR 자동화)

가장 강력한 기능이에요. GitHub 이슈를 Copilot에게 할당하면 PR을 자동으로 만들어줘요.

설정

GitHub 레포 → Settings → Copilot
→ "Allow Copilot to create pull requests" 활성화

사용법 1 — 이슈에서 직접

GitHub 이슈 페이지
→ Assignees 에서 "Copilot" 선택
→ Copilot이 이슈 분석 후 자동으로:
   1. 새 브랜치 생성
   2. 코드 작성
   3. 테스트 실행
   4. PR 생성
   5. 리뷰 요청

사용법 2 — Chat에서

VS Code Chat:
"GitHub 이슈 #127 해결하는 PR 만들어줘"

→ Cloud Agent가 백그라운드에서 처리
→ 완료되면 PR 링크 전달
→ 코드 리뷰 후 머지

사용법 3 — CLI에서

# GitHub CLI로 이슈 할당
gh issue assign 127 --assignee @copilot

# 진행 상황 확인
gh pr list --head "copilot/*"

---

.github/copilot-instructions.md 설정

프로젝트 전체에 적용되는 Copilot 지침이에요. Claude Code의 CLAUDE.md와 동일한 개념.

# .github/copilot-instructions.md

## 프로젝트 스택
- Backend: FastAPI + SQLAlchemy 2.0 (async)
- DB: PostgreSQL + Alembic
- 테스트: pytest + pytest-asyncio
- 스타일: Black + isort + mypy

## 코딩 규칙
- 모든 함수에 타입 힌트 필수
- DB 쿼리는 async/await 사용
- 에러는 AppException 클래스 사용
- 새 기능엔 반드시 테스트 작성 (커버리지 80% 이상)

## 금지 사항
- print() 사용 금지 (logger 사용)
- 하드코딩된 시크릿 금지
- main 브랜치 직접 커밋 금지

---

커스텀 에이전트 만들기

특정 역할에 특화된 에이전트를 직접 만들 수 있어요.

<!-- .github/agents/security-scout.agent.md -->
---
name: Security Scout
description: "SQL 인젝션, XSS, 인증 취약점 전문 보안 분석가"
tools: [read, search]
model: claude-opus-4-7
---

# 지침
당신은 시니어 보안 엔지니어입니다.

1. 분석 순서: /src/auth/ → /src/api/ → /src/models/
2. 모든 사용자 입력 처리 코드 집중 검토
3. 발견한 취약점마다 심각도(Critical/High/Medium/Low) 표시
4. 각 취약점에 수정 코드 제안
5. OWASP Top 10 기준으로 분류

<!-- .github/agents/test-writer.agent.md -->
---
name: Test Writer
description: "pytest 테스트 코드 전문 작성"
tools: [read, edit, terminal]
model: claude-sonnet-4-6
---

# 지침
- pytest 사용
- 커버리지 80% 이상 목표
- 엣지 케이스 반드시 포함
- fixture 재사용 극대화
- 비동기 코드는 pytest-asyncio 사용

커스텀 에이전트 사용:

Chat 패널 → @ 입력
→ @Security Scout 이 PR에서 취약점 찾아줘
→ @Test Writer src/api/payments.py 테스트 작성해줘

---

/fleet 으로 병렬 처리 (CLI 전용)

# Copilot CLI 설치 후
gh extension install github/gh-copilot

# 여러 파일 동시 처리
/fleet "auth.py, billing.py, notifications.py에 각각 테스트 추가해줘"

→ 3개의 서브에이전트가 동시 실행
→ 순차 처리보다 3배 빠름

---

Claude Code vs GitHub Copilot Agent Mode

Copilot Agent Mode가 앞서는 것:
✅ GitHub 이슈 → PR 완전 자동화
✅ VS Code 네이티브 통합 (별도 창 불필요)
✅ JetBrains 지원
✅ 팀 단위 커스텀 에이전트 공유
✅ GitHub Actions와 연동

Claude Code가 앞서는 것:
✅ 코딩 품질 (SWE-bench Pro 64.3%)
✅ 터미널 네이티브 (IDE 없이 사용)
✅ 더 자연스러운 한국어
✅ /ultrareview, Task Budgets 등 세밀한 제어
✅ 멀티에이전트 병렬 실행

실전 추천:
IDE 안에서 작업 + PR 자동화 → Copilot Agent Mode
터미널 + 복잡한 리팩토링 → Claude Code

---