GitHub Copilot에서 저장소 맞춤 지침을 설정하여 팀 코딩 표준과 아키텍처 규칙을 강제하는 방법

엔지니어링 팀이 GitHub Copilot을 도입할 때 흔히 겪는 문제 중 하나는 생성되는 코드의 일관성 부족입니다. 프로젝트별 명시적 가이드라인이 없다면 Copilot은 광범위한 퍼블릭 학습 데이터와 현재 열려 있는 파일의 파편화된 컨텍스트에만 의존하여 코드를 제안합니다. 그 결과 동일한 프로젝트 내에서도 레거시 콜백 문법이 제안되거나, 레이어 아키텍처 규칙이 위반되거나, 풀 리퀘스트(PR)에 검증되지 않은 외부 라이브러리가 유입되곤 합니다.

GitHub Copilot의 저장소 맞춤 지침(Repository Custom Instructions) 기능은 이러한 협업 문제를 해결하는 핵심 메커니즘입니다. Git 저장소의 루트에 .github/copilot-instructions.md를 배치하고, 필요에 따라 .github/instructions/**/*.instructions.md를 통해 경로별 규칙을 모듈화하면 팀의 아키텍처 경계, 코딩 컨벤션, 테스트 원칙, 보안 규칙을 전체 팀원의 Copilot 환경과 PR 코드 리뷰 프로세스에 자동으로 적용할 수 있습니다.

본 가이드에서는 저장소 맞춤 지침의 동작 원리, 우선순위 계층, 전역 및 경로별 지침 설정법, GitHub PR 코드 리뷰 자동화 연동, 그리고 토큰 낭비 없이 지침을 최적화하는 모범 사례를 살펴봅니다.

맞춤 지침의 적용 범위와 동작 방식

지침 파일을 작성하기 전에 GitHub Copilot이 맞춤 지침을 어떤 작업 환경에서 불러오는지 명확히 이해해야 합니다.

저장소 맞춤 지침은 사용자가 고차원 추론 및 대화형 워크플로를 호출할 때 LLM에 전달되는 프롬프트의 시스템 컨텍스트 최상단에 자동으로 포함됩니다:

• IDE 내 Copilot Chat: VS Code, Visual Studio, JetBrains IDE 제품군(IntelliJ IDEA, PyCharm, WebStorm 등), Xcode, Eclipse.
• GitHub.com 환경: 웹 저장소 내 Copilot Chat, Copilot 클라우드 에이전트(Cloud Agent), PR 자동 생성.
• Copilot Code Review: GitHub.com에서 PR 생성 시 코드 변경점(diff)을 저장소 맞춤 지침에 맞춰 자동 검토.
• Copilot CLI: 터미널 셸 환경에서의 명령어 생성 및 안내.

인라인 자동완성(Ghost Text)과의 차이점

맞춤 지침 파일은 에디터에서 타이핑 중에 표시되는 밀리초 단위의 인라인 회색 자동완성(고스트 텍스트)에는 실시간으로 엄격하게 적용되지 않습니다. 인라인 자동완성은 초저지연 응답을 위해 커서 주변의 코드와 열려 있는 탭을 우선 참조하도록 설계되어 있습니다. 저장소 맞춤 지침은 주로 Copilot Chat, 리팩터링 명령어(/fix, /explain), 자율 에이전트 작업, PR 코드 리뷰를 제어합니다. 따라서 들여쓰기, 세미콜론 등의 문법 서식은 ESLint, Prettier, Ruff와 같은 정적 분석 도구에 맡기고, 맞춤 지침은 아키텍처 및 설계 원칙을 가이드하는 용도로 사용하는 것이 효과적입니다.

지침 우선순위 계층 구조

여러 계층의 지침이 함께 존재할 때 GitHub Copilot은 다음 순서로 규칙을 결합하고 평가합니다(위쪽이 우선순위 높음):

1. 개인 지침(Personal instructions): 사용자가 Copilot 개인 설정에서 정의한 프롬프트.
2. 경로별 저장소 지침(Path-specific instructions): .github/instructions/**/*.instructions.md에서 현재 작업 파일의 glob 패턴과 일치하는 지침.
3. 전역 저장소 지침(Repository-wide instructions): 프로젝트 루트의 .github/copilot-instructions.md.
4. 에이전트 지침: AGENTS.md, CLAUDE.md, GEMINI.md 파일.
5. 조직 단위 맞춤 지침(Organization instructions): GitHub Enterprise/Business 관리자가 조직 전체에 일괄 적용한 정책.

1단계: 전역 저장소 지침 작성 (.github/copilot-instructions.md)

가장 기본이 되는 지침 파일은 Git 저장소 루트 디렉터리의 .github 폴더에 생성합니다:

mkdir -p .github
touch .github/copilot-instructions.md

AI 모델의 이해도와 준수율을 극대화하려면 명확한 Markdown 제목, 불릿 포인트 기반의 기술 요구사항, 그리고 긍정문 형태의 지침으로 간결하게 작성해야 합니다.

권장 구성 항목

1. 프로젝트 개요 및 아키텍처 경계: 서비스 역할, 아키텍처 패턴(Clean Architecture, 모듈형 모놀리스 등), 계층 간 의존성 금지 규칙(예: "Domain 계층은 UI 컴포넌트나 데이터베이스 드라이버를 직접 임포트할 수 없음").
2. 언어 버전 및 핵심 도구: 명확한 런타임 및 프레임워크 버전 명시(예: Node.js 22 LTS, TypeScript 5.5, Next.js 15 App Router).
3. 코딩 스타일 및 오류 처리 패턴: 명명 규칙, 비동기 오류 처리 방식(예: "원시 예외를 직접 throw하지 않고 Result 타입을 사용할 것").
4. 테스트 가이드라인: 테스트 러너(Vitest, Jest), 테스트 작성 패턴(AAA: Arrange-Act-Assert), 신규 비즈니스 로직에 대한 테스트 필수 원칙.
5. 보안 및 입력 검증: 필수 유효성 검증 라이브러리(Zod, Pydantic), 파라미터화된 SQL 쿼리 강제, 하드코딩된 자격 증명 금지.

프로덕션 예시 (TypeScript & Next.js 서비스)

# 저장소 아키텍처 및 코딩 표준

## 프로젝트 개요
본 저장소는 PostgreSQL 및 Stripe 결제 시스템과 연동되는 Next.js/Node.js 기반의 코어 결제 서비스(Core Billing Service)입니다.

## 아키텍처 계층 원칙
- 엄격한 계층 분리: UI 컴포넌트 (`/app`, `/components`) -> 애플리케이션 서비스 (`/src/services`) -> 도메인 모델 (`/src/domain`) -> 인프라 리포지토리 (`/src/infrastructure`).
- 도메인 계층은 특정 프레임워크에 종속되지 않아야 합니다. `/src/domain` 내부에서 `next/*` 모듈이나 DB 드라이버를 임포트하는 행위를 금지합니다.
- 데이터베이스 접근은 `/src/infrastructure/repositories`에 위치한 Prisma 리포지토리를 거쳐야 하며, 마이그레이션 외 파일에서 직접 작성한 Raw SQL 쿼리는 금지됩니다.

## TypeScript 표준
- TypeScript 5.x의 strict 모드를 준수합니다. `any` 사용은 금지되며, `unknown`과 타입 가드 또는 Zod 스키마를 사용해야 합니다.
- 객체 정의 시 `type` 별칭을 우선 사용하며, 확장이 필요한 인터페이스 계약에만 `interface`를 사용합니다.
- 비동기 오류는 `Result<T, E>` 타입 또는 표준 사용자 정의 에러 클래스로 처리하고, 처리되지 않은 Promise rejection을 남기지 않습니다.
- 가드 절(Guard Clauses)과 조기 반환(Early Return)을 활용하여 중첩 if/else를 방지합니다.

## 상태 관리 및 데이터 요청
- 클라이언트 데이터 패칭은 TanStack Query (`@tanstack/react-query`)를 사용합니다. 캐싱 처리되지 않은 API 호출을 위해 `useEffect`를 사용하는 것을 지양합니다.
- Server Actions는 도메인 서비스를 호출하기 전에 Zod 스키마를 통해 입력값을 검증해야 합니다.

## 테스트 작성 기준
- 테스트 러너: Vitest 및 React Testing Library.
- 단위 테스트 파일은 대상 소스코드와 동일한 디렉터리에 배치합니다 (`*.spec.ts` 또는 `*.spec.tsx`).
- 모든 테스트는 Arrange-Act-Assert (AAA) 패턴을 따라야 합니다.
- 외부 네트워크 통신은 Mock Service Worker (MSW)로 모킹하며, 언어 내장 표준 유틸리티는 모킹하지 않습니다.

## 주요 검증 명령어
- 테스트 실행: `pnpm test`
- 타입 검사: `pnpm typecheck`
- 린트 검증: `pnpm lint`

2단계: 경로별 맞춤 지침 분리 (.github/instructions/)

대규모 모노레포나 풀스택 프로젝트의 경우 모든 지침을 하나의 파일에 모아두면 컨텍스트 윈도우가 낭비되고 AI의 집중도가 떨어집니다. 예를 들어 백엔드 Go 코드를 수정할 때 프론트엔드 React나 Tailwind 관련 규칙은 불필요한 노이즈가 됩니다.

경로별 지침(Path-specific instructions)을 활용하면 glob 패턴을 통해 필요한 시점에만 특정 규칙을 활성화할 수 있습니다.

디렉터리 구성

.github/instructions/ 폴더 내에 규칙 파일을 모듈화하여 배치합니다:

.github/
  ├── copilot-instructions.md
  └── instructions/
      ├── frontend.instructions.md
      ├── backend.instructions.md
      └── migrations.instructions.md

파일 문법 및 Frontmatter 설정

경로별 지침 파일은 반드시 .instructions.md 확장자로 끝나야 하며, 파일 상단에 applyTo를 포함한 YAML Frontmatter 블록을 선언해야 합니다:

---
applyTo: "apps/web/**/*.{ts,tsx}"
---

# 프론트엔드 컴포넌트 표준

- 컴포넌트는 명명된 내보내기(Named Export)를 적용한 함수형 컴포넌트로 작성합니다.
- 스타일은 Tailwind CSS 유틸리티 클래스를 사용하며 인라인 CSS 객체는 지양합니다.
- 상호작용 가능한 모든 요소에는 적절한 `aria-*` 접근성 속성과 키보드 탐색 지원을 포함해야 합니다.
- 아이콘은 `lucide-react`에서만 임포트합니다.

주요 Glob 패턴 예시

• **/*.py: 저장소 내 모든 깊이의 Python 파일에 적용.
• services/billing/**/*.go: 결제 서비스 하위의 Go 코드에만 한정 적용.
• **/*.test.ts,**/*.spec.ts: 쉼표로 구분하여 여러 테스트 파일 패턴에 동시 적용.

특정 에러/에이전트 제외 (excludeAgent)

클라우드 에이전트 빌드 작업 시에만 사용하고 PR 코드 리뷰 시에는 적용하지 않으려면 excludeAgent 속성을 추가합니다:

---
applyTo: "**"
excludeAgent: "code-review"
---

# 자율 에이전트 빌드 가이드
- 통합 테스트를 실행하기 전에 `pnpm db:migrate`를 먼저 실행하십시오.
- 새로운 환경 변수 추가 시 반드시 `.env.example`을 업데이트하십시오.

3단계: GitHub PR 코드 리뷰 자동화와 연동

맞춤 지침은 에디터 내 개발 지원뿐만 아니라 GitHub Pull Request에서 Copilot이 수행하는 자동 코드 리뷰의 평가 기준으로도 작동합니다.

코드 리뷰 연동 활성화 방법

1. GitHub 저장소 페이지에서 Settings(설정) 탭으로 이동합니다.
2. 좌측 메뉴의 Code, planning, and automation -> Copilot -> Code review를 클릭합니다.
3. Use custom instructions when reviewing pull requests(PR 리뷰 시 맞춤 지침 사용) 토글을 켭니다.

브랜치 읽기 메커니즘 (Head Branch)

Copilot은 PR을 검토할 때 대상 브랜치(main)가 아니라 **PR의 변경 대상 브랜치(Head Branch)**에 있는 .github/copilot-instructions.md와 경로 규칙을 읽습니다.

이 구조는 팀 운영에 큰 이점을 제공합니다. 코딩 표준을 개선하거나 새로운 아키텍처 규칙을 도입할 때, 기능 브랜치에서 지침 파일과 예제 코드를 함께 수정하여 PR을 올릴 수 있습니다. Copilot은 머지 전 브랜치에 작성된 새로운 지침을 기준으로 PR 코드를 검토하므로, 규칙 변경의 효과를 사전에 검증할 수 있습니다.

4단계: 개발자 환경에서 지침 로드 상태 검증

팀원들의 로컬 작업 환경에 지침이 제대로 반영되고 있는지 확인하는 방법은 다음과 같습니다:

1. IDE 설정 확인:
   • VS Code: 설정(Ctrl+, 또는 Cmd+,)에서 instruction file을 검색하여 Code Generation: Use Instruction Files가 체크되어 있는지 확인합니다(기본값: 활성화).
   • JetBrains IDE: Copilot Chat 패널 우측 상단 톱니바퀴 아이콘을 클릭하고 Customizations를 선택하여 활성화된 지침 파일을 점검합니다.
2. Chat 응답의 References(참조) 확인:
   • Copilot Chat에서 프로젝트 관련 작업(예: "사용자 인증 서비스 생성해줘")을 요청합니다.
   • 응답 상단의 References 드롭다운을 펼칩니다.
   • 정상 구성되어 있다면 .github/copilot-instructions.md 또는 매칭된 .instructions.md 링크가 표시되어 AI가 팀 표준을 참조했음을 확인할 수 있습니다.

엔지니어링 모범 사례와 주의점

Prompt 파일 (.github/prompts/*.prompt.md)과의 상호 보완

저장소 맞춤 지침이 "항상 지켜야 할 기본 제약 조건"이라면, 새로운 API 라우트 스캐폴딩, 마이그레이션 생성 등 자주 반복되는 작업은 공개 프리뷰 중인 Copilot Prompt 파일(.github/prompts/*.prompt.md)과 함께 사용하는 것이 좋습니다. 작업 템플릿은 Prompt 파일로 호출하고, 전체적인 아키텍처 일관성은 .github/copilot-instructions.md가 보장하도록 설계하는 것이 이상적입니다.

도입 체크리스트

1. 저장소 루트에 .github/copilot-instructions.md를 생성하고 아키텍처 경계, 기술 버전, 필수 규칙을 정의합니다.
2. 모노레포 또는 특정 서브시스템의 경우 .github/instructions/ 아래에 applyTo를 선언한 모듈형 지침을 구성합니다.
3. GitHub 저장소 설정에서 PR Code Review 맞춤 지침 사용 옵션을 켭니다.
4. IDE 내 Copilot Chat의 References 목록에서 지침 파일이 정상 참조되는지 확인합니다.
5. 라이브러리 업데이트 및 설계 변경에 맞추어 PR을 통해 지침을 지속적으로 개선합니다.

참고 자료

• Adding repository custom instructions for GitHub Copilot - GitHub Docs
• Adding repository custom instructions for GitHub Copilot in your IDE - GitHub Docs
• Support for different types of custom instructions - GitHub Docs
• About customizing GitHub Copilot responses - GitHub Docs
• 5 tips for writing better custom instructions for Copilot - The GitHub Blog