GitHub Copilot 코드 리뷰 맞춤 설정: 지침, Setup, Network 통제

GitHub Copilot 코드 리뷰는 이제 단순히 PR diff를 읽는 기능이 아닙니다. 2026년 7월 17일 업데이트 이후에는 PR 브랜치의 지침을 시험하고, 리뷰 전용 환경을 만들고, 네트워크와 runner를 코드 작성 에이전트와 분리할 수 있습니다. 좋은 리뷰를 얻으려면 프롬프트를 길게 쓰는 대신 저장소 규칙, 실행 환경, 외부 접근 범위를 각각 관리해야 합니다.

GitHub의 7월 17일 공식 변경 사항에는 네 가지 핵심 변화가 포함됐습니다.

변화	운영상 의미
custom instructions를 PR의 head 브랜치에서 읽음	지침 변경 자체를 PR에서 시험할 수 있음
`REVIEW.md`, `GEMINI.md`, `CLAUDE.md` 지원	기존 저장소 문서를 리뷰 컨텍스트로 재사용 가능
`.github/workflows/copilot-code-review.yml` 지원	코드 작성 에이전트와 리뷰 환경을 분리 가능
전용 firewall과 runner 설정	리뷰가 접근할 네트워크와 실행 자원을 별도로 제한 가능

핵심은 하나입니다. 리뷰 품질 문제를 모두 자연어 지침으로 해결하지 말고, 지침·환경·권한을 서로 다른 검증 계층으로 분리한 뒤 PR에서 각각 확인해야 합니다.

먼저 어떤 파일에 무엇을 써야 하는지 구분합니다

Copilot 코드 리뷰가 읽을 수 있는 파일이 늘었지만, 모든 규칙을 하나의 CLAUDE.md에 넣는 것은 좋지 않습니다.

파일	적합한 내용
`.github/copilot-instructions.md`	저장소 전체에 적용되는 짧은 원칙
`.github/instructions/*/.instructions.md`	특정 경로·언어·기능에만 적용되는 규칙
`AGENTS.md`	빌드, 테스트, 아키텍처, 작업 방식
`REVIEW.md`	PR 리뷰에서 반드시 확인할 항목
`CLAUDE.md`, `GEMINI.md`	이미 운영 중인 모델·도구별 프로젝트 설명
`.github/skills/*/SKILL.md`	반복 가능한 전문 검토 절차

현재 Copilot code review 문서는 repository-wide, path-specific, 공유 agent instruction, task-specific skill의 역할과 위치를 구분합니다. REVIEW.md, CLAUDE.md, GEMINI.md 지원은 7월 변경에서 추가됐습니다.

Restato 저장소처럼 이미 CLAUDE.md와 콘텐츠 정책이 있다면, 프로젝트 설명을 다시 복제하기보다 리뷰 전용 규칙만 REVIEW.md로 분리하는 편이 낫습니다.

# REVIEW.md

## 반드시 막아야 하는 변경
- `npm run build`를 실패시키는 Astro·MDX 변경
- 실제 `src/content/config.ts` 스키마와 다른 frontmatter
- 존재하지 않는 내부 링크 또는 프로젝트 경로
- 브라우저 전용 API를 SSR 단계에서 직접 호출하는 코드
- 비밀키, 토큰, 개인 데이터가 포함된 변경

## 집중해서 볼 영역
- `src/content/blog/**`: title, description, date, tags와 MDX 문법
- `src/pages/**`: 정적 생성 경로와 canonical URL
- `.github/workflows/**`: 최소 권한과 Node 버전
- `src/components/tools/**`: 모바일 레이아웃과 오류 처리

## 리뷰 응답
- 심각도와 영향을 먼저 설명합니다.
- 수정 가능한 경우 최소 diff를 제안합니다.
- 취향 차이는 차단 이슈처럼 표현하지 않습니다.

이 문서는 사람 리뷰어도 읽을 수 있어야 합니다. AI 전용 암호 같은 표현보다 팀의 실제 리뷰 기준을 기록하는 편이 유지보수에 유리합니다.

head 브랜치 지침은 리뷰 규칙을 PR로 시험하게 해줍니다

이전에는 리뷰 지침을 기본 브랜치에 먼저 합쳐야 새 규칙을 적용해 볼 수 있었습니다. 7월 17일 공식 changelog는 Copilot 코드 리뷰가 copilot-instructions.md, *.instructions.md, agent skills, AGENTS.md를 PR의 head 브랜치에서 읽는다고 설명합니다.

이 변화로 다음 순서가 가능해집니다.

기능 브랜치에서 REVIEW.md나 path-specific instructions를 수정합니다.
같은 PR에 Copilot 리뷰를 요청합니다.
새 규칙이 과도한 경고를 만들거나 중요한 문제를 놓치는지 확인합니다.
규칙과 코드를 함께 수정합니다.
검증된 규칙만 기본 브랜치에 합칩니다.

그럴듯한 review comment만 보고 적용됐다고 판단하지 마세요. Copilot code review 사용 가이드에 따라 연결된 review session을 열고 실제 사용한 tool, skill, MCP server를 확인합니다. 오래된 캐시 문서에 base branch 설명이 남아 있다면 날짜가 있는 changelog와 현재 concept page를 기준으로 삼고 실제 session으로 검증하세요.

코드 리뷰 전용 setup workflow를 분리합니다

Copilot 코드 리뷰는 GitHub Actions 기반의 임시 환경에서 실행됩니다. 기본적으로 copilot-setup-steps.yml을 재사용하지만, 리뷰에 코드 작성 에이전트와 같은 도구·권한이 꼭 필요한 것은 아닙니다.

.github/workflows/copilot-code-review.yml을 만들면 리뷰 전용 환경을 구성할 수 있습니다. GitHub 문서의 setup workflow 규칙에 따라 job 이름은 copilot-setup-steps여야 합니다.

name: Copilot Code Review Setup

on:
  workflow_dispatch:
  push:
    paths:
      - .github/workflows/copilot-code-review.yml
  pull_request:
    paths:
      - .github/workflows/copilot-code-review.yml

jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    permissions:
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: npm

      - name: Install dependencies
        run: npm ci

예시는 현재 Restato 배포 환경에 맞춰 Node 20을 사용했습니다. 실제 repository에서는 lockfile, framework 지원 범위와 배포 runtime을 함께 검토해 값을 선택해야 합니다.

setup 단계에는 리뷰에 실제로 필요한 것만 넣습니다.

타입과 import를 확인해야 한다면 npm ci
생성 코드가 있어야 정확히 리뷰할 수 있다면 코드 생성 명령
특정 linter나 schema validator가 필요하다면 해당 도구 설치
private registry가 필요하면 최소 범위의 secret과 firewall 규칙

반대로 배포, 데이터 변경, 외부 서비스 쓰기 권한은 리뷰 환경에 넣지 않는 편이 좋습니다. 리뷰는 코드를 이해하는 작업이지 운영 환경을 복제하는 작업이 아닙니다.

Job 이름은 반드시 copilot-setup-steps여야 합니다. GitHub의 환경 setup reference는 지원 job 설정과 timeout-minutes 최대 59분도 문서화합니다.

setup 실패가 리뷰를 자동 중단시키지 않는 점을 주의합니다

GitHub의 개발 환경 문서에 따르면 setup step이 실패하면 남은 setup 단계를 건너뛰지만, Copilot은 현재 환경에서 작업을 계속할 수 있습니다. 따라서 npm ci가 실패했는데도 리뷰 결과가 생성될 수 있습니다.

이 동작은 다음 문제를 만들 수 있습니다.

의존성이 없는 상태에서 import 오류를 놓침
generated type이 없어 잘못된 경고를 생성
테스트 도구를 사용할 수 없어 diff만 보고 판단

그래서 setup workflow 성공 여부를 별도 required check로 취급하는 편이 안전합니다. Copilot 리뷰 댓글이 달렸다는 사실만으로 환경 준비가 정상적이었다고 판단하면 안 됩니다. Setup이 실패하면 환경을 고친 뒤 새 review를 요청하고, 제한된 결과를 원래 tool이 실행된 review처럼 평가하지 마세요.

두 결과를 독립적으로 기록합니다.

review setup workflow: passed
Copilot review session: completed and used expected context

firewall은 기본 허용 목록보다 작업 목적부터 정합니다

Copilot 코드 리뷰는 기본적으로 firewall 뒤에서 실행됩니다. repository settings의 Copilot → Internet access에서 cloud agent와 code review의 규칙을 각각 설정할 수 있습니다.

먼저 리뷰가 외부 네트워크를 정말 필요로 하는지 판단합니다.

작업	외부 접근 필요성
저장소 코드와 diff 검토	대부분 불필요
공개 npm package metadata 확인	registry 접근 필요 가능
사내 schema·문서 참조	private endpoint allowlist 필요
외부 API 실제 호출	리뷰 환경에서는 가급적 금지
Playwright로 공개 페이지 확인	대상 도메인만 제한적으로 허용

기본 원칙은 필요한 도메인만 allowlist하는 것입니다. firewall을 끄는 것보다 리뷰가 왜 네트워크를 필요로 하는지 setup과 instructions에 명시하는 편이 낫습니다.

자체 호스팅 runner에서는 Copilot 코드 리뷰의 통합 firewall이 같은 방식으로 보호하지 않습니다. 현재 runner 문서는 ARC-managed Ubuntu x64 runner를 지원 경계로 제시합니다. 내부 네트워크에 접근하는 runner라면 GitHub 설정과 별개로 runner network 계층에서 egress와 내부 접근을 통제해야 합니다.

코드 작성 agent와 code review runner를 분리합니다

코드 작성과 review는 필요한 자원과 권한이 다릅니다.

coding agent: 빌드, 테스트, 파일 수정, 긴 실행 시간이 필요할 수 있음
code review: diff 탐색과 정적 검토가 중심이며 쓰기 권한이 불필요

따라서 code review에 더 작은 hosted runner를 쓰고, coding agent에만 큰 runner나 내부 리소스 접근을 허용할 수 있습니다. 비용보다 중요한 장점은 권한 경계입니다. 조직 기본값과 repository override 상태를 함께 기록하고 실제 test PR로 분리를 확인하세요.

agent skills는 리뷰 용도로 이름과 범위를 좁힙니다

GitHub Docs는 Copilot 코드 리뷰가 repository의 agent skills와 MCP server를 사용할 수 있다고 설명합니다. 다만 모든 일반 작업 스킬이 리뷰에 적합한 것은 아닙니다.

.github/skills/
└── astro-content-review/
    └── SKILL.md

---
name: astro-content-review
description: Astro MDX와 콘텐츠 컬렉션 변경을 검토할 때 사용
---

# Astro Content Review

1. 실제 content schema를 먼저 읽습니다.
2. 새 MDX의 frontmatter 필드를 schema와 비교합니다.
3. slug와 내부 링크가 정적 경로로 생성되는지 확인합니다.
4. JSX로 해석될 수 있는 MDX 기호를 확인합니다.
5. 날짜, 제품 버전, 가격 주장은 공식 출처와 비교합니다.

스킬 이름과 description에 review 목적이 드러나야 Copilot이 관련 상황에서 사용할 가능성이 높아집니다. 게시·배포 스킬과 리뷰 스킬을 같은 디렉터리에 섞지 않는 편이 좋습니다.

Skill 선택은 deterministic required check가 아닙니다. 모든 PR에 반드시 실행해야 하는 정책은 test나 ruleset check로 만들고, skill은 결과 해석과 전문 검토에 사용하세요.

실제 적용 순서

REVIEW.md에 사람이 합의한 차단 기준을 작성합니다.
.github/copilot-instructions.md에는 짧은 저장소 공통 규칙만 둡니다.
path-specific instructions로 MDX, workflow, React 규칙을 분리합니다.
copilot-code-review.yml에서 최소 의존성만 설치합니다.
setup workflow 자체를 Actions 탭에서 먼저 검증합니다.
firewall allowlist를 최소화합니다.
테스트 PR에서 지침 변경과 Copilot 리뷰를 함께 실행합니다.
review session logs에서 사용한 지침, skill, MCP tool을 확인합니다.
Rule version별 누락과 오탐을 기록합니다.
반복되는 오탐은 instruction을 늘리기 전에 코드·schema·테스트로 해결합니다.

Copilot은 항상 approve나 request changes가 아니라 comment review를 남기므로 required human approval을 대신하지 않습니다.

권고

사람이 읽을 수 있는 review checklist 하나, 최소 setup job 하나, 불필요한 외부 접근이 없는 hosted runner로 시작하세요. Test PR에서 setup check와 session evidence를 확인하고, 명시적인 review 필요가 있을 때만 skill, MCP, private dependency, self-hosted runner를 추가합니다.

좋은 AI 코드 리뷰는 “더 똑똑한 모델”만으로 만들어지지 않습니다. 어떤 규칙을 읽고, 어떤 환경에서 검사하고, 어디까지 접근할 수 있는지를 저장소가 명확히 제공해야 합니다. 지속 가능한 설정은 가장 긴 instruction이 아니라 활성화, 환경, 권한을 각각 관찰하고 되돌릴 수 있는 작은 통제 집합입니다.

주요 출처

함께 읽기: Agent Governance control plane · GitHub Issues 에이전트 자동화 통제 · Copilot managed settings governance