GitHub Copilot 저장소 지침 파일(copilot-instructions.md) 작성과 적용 범위

GitHub Copilot에 매번 "이 프로젝트는 pnpm을 쓴다", "테스트는 Vitest로 작성한다"를 반복해서 말하고 있다면 저장소 지침 파일이 필요하다. GitHub 공식 문서는 저장소에 지침 파일을 두면 Copilot Chat, 코드 리뷰, 클라우드 에이전트가 이를 참고한다고 설명한다. 이 글은 파일 종류, 적용 범위, 작성 예시, 적용 확인 방법을 순서대로 정리한다. Cursor에서 같은 역할을 하는 규칙 파일은 Cursor Rules 작성법 글에서 다뤘다.

지침 파일 세 종류와 위치

종류	위치	적용 대상
저장소 전체 지침	.github/copilot-instructions.md	저장소의 모든 요청
경로별 지침	.github/instructions/이름.instructions.md	applyTo 패턴과 일치하는 파일 작업
에이전트 지침	AGENTS.md(어느 위치든, 가장 가까운 파일 우선) 또는 루트의 CLAUDE.md·GEMINI.md	에이전트 작업

문서에 따르면 기능마다 읽는 지침이 다르다. Copilot Chat은 저장소를 첨부했을 때 저장소 전체 지침을 쓰고, 코드 리뷰는 저장소 전체 지침과 경로별 지침을 지원하며, 클라우드 에이전트는 세 종류를 모두 지원한다. 따라서 모든 기능에 공통으로 필요한 규칙은 저장소 전체 지침에 둔다.

1단계: 저장소 전체 지침 작성하기

# .github/copilot-instructions.md

## 프로젝트 개요
Next.js App Router 기반 사내 주문 관리 도구. 패키지 매니저는 pnpm.

## 빌드와 테스트
- 의존성 설치: pnpm install
- 테스트: pnpm test (Vitest). 새 함수에는 같은 폴더의 *.test.ts를 추가한다.
- 타입 검사: pnpm typecheck

## 코드 규칙
- 서버 데이터 변경은 app/actions의 서버 액션으로만 한다.
- 날짜 처리는 date-fns만 사용한다. moment를 추가하지 않는다.
- API 응답 타입은 src/types/api.ts에 정의된 타입을 재사용한다.

문서는 지침을 두 페이지 이내로 짧게 쓰고, 특정 작업에만 해당하는 지시는 넣지 말라고 권한다. "항상 빌드 전에 pnpm install을 실행한다"처럼 행동이 분명한 문장이 좋은 예다.

2단계: 경로별 지침으로 폴더 규칙 나누기

특정 폴더나 확장자에만 해당하는 규칙은 .github/instructions/에 분리한다. 파일 맨 위 frontmatter의 applyTo에 glob 패턴을 쓰고, 여러 패턴은 쉼표로 구분한다.

---
applyTo: "src/components/**/*.tsx,src/app/**/*.tsx"
---

- 컴포넌트는 named export만 쓴다.
- 스타일은 Tailwind 클래스만 사용하고 인라인 style 속성을 쓰지 않는다.
- 이미지에는 alt 속성을 반드시 넣는다.

특정 기능에서는 빼고 싶은 지침이 있다면 excludeAgent 필드를 쓴다. 예를 들어 excludeAgent: "code-review"를 두면 코드 리뷰에서는 그 지침을 적용하지 않는다.

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

- 작업을 시작하기 전에 pnpm install과 pnpm typecheck를 실행한다.

개인·저장소·조직 지침이 함께 있을 때

문서에 따르면 우선순위는 개인 지침이 가장 높고, 그다음 저장소 지침, 조직 지침 순이다. 다만 서로 덮어쓰는 방식이 아니라 적용 가능한 지침이 모두 합쳐져 전달된다. 그래서 개인 지침에 "답변은 영어로"가 있고 저장소 지침에 "주석은 한국어로"가 있으면 둘 다 반영된다. 서로 모순되는 지침이 생기지 않도록 저장소 지침에는 코드 규칙만, 개인 지침에는 답변 스타일만 두는 식으로 역할을 나눈다.

3단계: 지침이 실제로 쓰였는지 확인하기

1. Copilot Chat에서 저장소를 첨부한 상태로 질문한다.
2. 응답 위의 References 목록을 펼친다.
3. 목록에 .github/copilot-instructions.md가 있으면 지침이 참조된 것이다.
4. 경로별 지침은 해당 패턴과 일치하는 파일을 대상으로 코드 리뷰나 에이전트 작업을 요청해 결과에 규칙이 반영되는지 본다.

지침이 참조되는데도 규칙이 지켜지지 않는다면 문장이 모호한 경우가 많다. "깔끔하게"처럼 판단 기준이 없는 표현을 "40줄이 넘는 함수는 분리한다"처럼 바꾼다. 리뷰 단계에서 지침과 같은 기준을 쓰려면 AI 생성 코드 리뷰 규칙 글의 항목과 맞춰 둔다.

여러 AI 도구를 함께 쓰는 저장소라면

Copilot의 에이전트는 AGENTS.md와 루트의 CLAUDE.md도 읽는다. Cursor와 Claude Code를 함께 쓰는 팀이라면 도구와 무관한 공통 규칙은 AGENTS.md에 두고, Copilot 전용 설정만 .github/copilot-instructions.md에 남기면 같은 규칙을 여러 파일에 복사하지 않아도 된다.

지침에 넣을 내용과 뺄 내용

넣을 내용	뺄 내용
설치·빌드·테스트·린트 명령	특정 이슈 하나를 처리하는 절차
폴더별 역할과 새 파일을 둘 위치	프로젝트 역사나 긴 아키텍처 설명
사용 금지 라이브러리와 대체 라이브러리	"좋은 코드를 작성한다" 같은 판단 기준 없는 문장
공통 에러 처리·응답 형식 규칙	비밀번호, 내부 서버 주소 같은 민감 정보
테스트 파일 위치와 이름 규칙	외부 문서 전체를 복사한 내용

지침 파일은 저장소에 커밋되므로 저장소 접근 권한이 있는 사람이면 누구나 읽을 수 있다. 내부 서버 주소나 계정 정보를 적지 않는 것은 물론, 공개 저장소라면 내부 프로세스 설명도 최소한으로 둔다. 지침 변경도 일반 코드처럼 PR로 올려 팀 리뷰를 거치면 개인 취향이 팀 규칙으로 섞여 들어가는 일을 막을 수 있다.