[Copilot] Github Copilot 사용자 정의 지침 정리

들어가며

GitHub Copilot은 코드를 치는 동안 다음 코드를 추천해 주고, 채팅 창에서 「이런 함수를 만들어 줘」라고 물으면 코드를 써 주는 AI 도구다. 그런데 아무것도 알려 주지 않으면 Copilot은 내 프로젝트의 약속을 모른다. 나는 함수 이름을 camelCase(getUserName처럼 첫 단어는 소문자, 이어지는 단어의 첫 글자는 대문자)로 짓는데 Copilot이 다른 모양으로 써 오면, 매번 채팅에 「camelCase로 써 줘」를 다시 적어야 한다.

사용자 정의 지침(Custom Instructions)은 이 반복을 없애는 장치다. 내 프로젝트의 규칙을 파일에 한 번 적어 두면, Copilot이 코드를 만들 때마다 그 규칙을 같이 읽는다. 최근 Copilot을 쓰면서 이걸 설정하는 것이 개발 생산성을 크게 올린다는 것을 깨달았다. 이 글에서는 지침을 설정하는 방법과 그 효과를 정리한다.

해당 문서는 아래의 링크를 참고하여 작성하였다.

• GitHub Copilot 사용자 정의 지침

---

현재 2025-06-24일 문서에서 제안하는 설정방법은 크게 3가지로 나뉜다.

1. .github/copilot-instructions.md 파일을 생성하여 사용자 정의 지침을 설정하는 방법
2. .instructions.md 파일을 생성하여 사용자 정의 지침을 설정하는 방법
3. .github/prompts 폴더에 프롬프트 파일을 두어 자주 쓰는 지시문을 저장하는 방법

세 번째는 엄밀히는 「항상 붙는 지침」이 아니라 「부를 때만 쓰는 지시문」이다. 둘의 차이는 그 절에서 다룬다. 두 번째의 .instructions.md는 파일 이름 전체가 아니라 끝에 붙이는 꼬리다. general.instructions.md, db.instructions.md처럼 앞에 이름을 붙여 만든다.

.github는 프로젝트 폴더 맨 위에 내가 직접 만드는 폴더다. GitHub이 저장소 안에서 자기 설정 파일을 찾는 자리로 정해 둔 이름이고, 앞의 점은 따로 하는 일 없이 이름의 일부다. Copilot도 이 폴더에서 지침 파일을 찾는다.

---

.github/copilot-instructions.md 설정 방법

사용자 지침을 .github/copilot-instructions.md 파일에 작성하여 Copilot이 코드를 만들 때 따를 규칙을 정할 수 있다. 이 파일은 다음과 같은 특징을 가진다:

• 모든 코드 생성 지침은 Markdown(.md 파일) 형식으로 작성된 하나의 파일에 통합되어 있으며, 워크스페이스(에디터에서 지금 열어 둔 프로젝트 폴더) 내에 저장된다.
• 이 지침 파일은 모든 채팅 요청에 자동으로 포함된다. Copilot 채팅 창에 내가 질문을 적어 보내면, 이 파일의 내용이 내 질문 앞에 붙어 함께 AI에게 간다. 그래서 질문마다 규칙을 다시 적지 않아도 된다.
• Copilot을 지원하는 모든 에디터 및 IDE에서 적용된다.
• 이 파일을 통해 다음과 같은 내용을 정의할 수 있다:
  • 일반적인 코딩 관례
  • 선호하는 기술 스택
  • 프로젝트 전반에 적용되는 요구사항

---

.instructions.md 설정 방법

특정 작업에 맞는 맞춤형 코드 생성 지침을 설정하려면 .instructions.md 파일을 사용한다. 여기서 「작업」은 테스트 코드 작성, DB 코드 작성처럼 내가 Copilot에게 시키는 일의 종류를 말한다. 이 파일은 다음과 같은 특징을 가진다:

• Markdown 파일에 코드 생성 규칙(스타일, 제한, 선호 등)을 작성한다.
• .instructions.md 파일은 하나 이상 만들 수 있고, 워크스페이스(프로젝트 폴더) 또는 사용자 프로필에 저장할 수 있다. 사용자 프로필은 VS Code가 내 컴퓨터에 따로 들고 있는 개인 설정 묶음이라, 거기 둔 지침은 어떤 프로젝트를 열든 적용된다(전역 설정).
• *.ts, **/*.controller.ts 같은 glob 패턴을 이용해 전체 파일 또는 특정 파일에만 지침을 자동 적용할 수 있다. **/*.controller.ts는 어느 폴더에 있든 이름이 .controller.ts로 끝나는 파일, 곧 요청을 받는 Controller 코드 파일만 고른다. .ts는 TypeScript 파일, 뒤에 나오는 .js는 JavaScript 파일의 확장자다.
• 이 기능은 VS Code의 GitHub Copilot 채팅에서 지원된다.
• 특정 작업(task)별로 코드 생성 규칙을 정의하고, 어떤 지침을 어떤 요청에 포함할지 더 세밀하게 제어하고 싶다면 이 파일을 사용한다.

사용 예시 — .instructions.md 파일 맨 위에 적용 대상을 적는다

.instructions.md 파일 하나는 맨 위의 설정 부분과 그 아래의 지침 본문으로 이루어진다. 맨 위 --- 두 줄 사이가 front matter이고 YAML 형식으로 적는다.

---
description: 이 지침 파일에 대한 간단한 설명
applyTo: "*.js"  # 자동 적용할 파일 경로 패턴 (glob)
---
함수 이름은 camelCase로 짓는다.

• 1줄과 4줄의 ---는 설정 부분의 시작과 끝을 표시한다.
• 2줄 description은 이 지침 파일이 무엇인지 사람이 알아보라고 적는 설명이다.
• 3줄 applyTo는 이 지침을 어떤 파일에 적용할지 glob 패턴으로 적는다. "*.js"면 JavaScript 파일을 다룰 때만 이 지침이 붙는다. # 뒤는 YAML 주석이라 동작에 영향을 주지 않는다.
• 5줄부터가 지침 본문이다. Copilot이 읽을 규칙 문장을 여기에 마크다운으로 적는다.

settings.json으로 지침을 직접 설정하기

지침 파일을 두는 방법 말고, VS Code의 설정 파일인 settings.json에 지침을 직접 적는 방법도 있다. settings.json은 VS Code가 설정값을 저장하는 JSON 파일이고, VS Code에서 명령 팔레트(Ctrl+Shift+P)를 열어 「Preferences: Open User Settings (JSON)」을 고르면 열린다. 여기에 GitHub Copilot Chat(Copilot의 채팅 기능)의 여러 작업(코드 생성, 테스트 작성 등)에 대해 맞춤형 지침(custom instructions)을 지정할 수 있다. 앞의 .instructions.md 파일도 여기서 이름으로 불러올 수 있다. 아래 예시는 코드 생성 지침(codeGeneration)이고, 테스트 작성 지침은 같은 모양으로 github.copilot.chat.testGeneration.instructions에 넣는다. 다만 이 두 설정은 VS Code 1.102부터 폐기 예정(deprecated)으로 바뀌었고, 공식 문서는 지침 파일을 쓰라고 안내한다.

지침 설정 방식 2가지

• text: 지침 내용을 직접 문자열로 설정
• file: 외부 .md 파일 경로 지정

예시

{
  "github.copilot.chat.codeGeneration.instructions": [
    {
      "text": "항상 주석으로 코파일럿이 생성한 코드임을 명시하세요."
    },
    {
      "text": "TypeScript에서는 항상 private 필드 이름에 언더스코어를 사용하세요."
    },
    {
      "file": "general.instructions.md" // import instructions from file `general.instructions.md`
    },
    {
      "file": "db.instructions.md" // import instructions from file `db.instructions.md`
    }
  ]
}

이 코드는 JSON 형식이다. 중괄호 { }는 하나의 묶음을 나타내고, 대괄호 [ ]는 그 안에 여러 개를 순서대로 나열한 목록이다. github.copilot.chat.codeGeneration.instructions 목록 안에 지침을 하나씩 넣는데, text로 적으면 그 글자 자체가 지침이 되고, file로 적으면 그 경로에 있는 파일 내용을 지침으로 가져와 쓴다.

• 원래 JSON에는 주석이 없지만 VS Code의 settings.json은 // 주석을 허용한다. 그래서 // import instructions ...는 사람이 보라고 단 메모이고 동작에는 영향을 주지 않는다.
• file에 적은 general.instructions.md를 어느 폴더 기준으로 찾는지는 확인하지 않았다. 따라 할 때는 파일을 둔 자리에서 지침이 실제로 붙는지 직접 확인해야 한다.

custom 지침 작성 팁

• 각 지침은 하나의 문장으로, 간단하고 자족적(self-contained)이게 쓴다. 자족적이란 그 문장 하나만 읽어도 다른 문서를 찾아보지 않고 뜻이 통한다는 말이다.
• 여러 가지 조건을 한 문장에 쓰지 말고, 지침을 나눠서 여러 줄로 작성한다.

1. 지침은 짧고 명확하게 작성한다.

예시 (좋음):

• “함수는 camelCase로 작성한다.”
• “JSDoc 주석을 사용한다.”

예시 (나쁨):

• “함수는 camelCase로 작성하고, JSDoc 주석도 포함하며 테스트도 작성한다.”

1. 외부 리소스를 지침에 참조하지 말 것

나쁜 예: 「Google Java Style Guide를 따르세요」. Google Java Style Guide는 구글이 공개한 자바 코드 작성 규칙 문서다.

이유: 지침에는 문서 이름만 들어갈 뿐 그 문서의 내용은 들어가지 않는다. Copilot이 그 외부 문서를 직접 열어 읽는다고 기대할 수 없으므로, 지침은 그 자체로 설명이 되어야 한다.

1. 지침을 파일별로 나눠서 관리하라

기능별, 언어별, 프레임워크별로 지침을 여러 개의 .instructions.md 파일로 분리해 두는 것이 좋다.

1. 팀 또는 프로젝트 간 공유를 쉽게 하기

• 지침 파일을 프로젝트 내에 저장하고 Git으로 버전 관리하면 팀원들과 공유가 쉬워진다.
• 지침 파일은 평범한 마크다운 파일이라, 다른 프로젝트의 같은 자리에 복사해 넣으면 그대로 다시 쓸 수 있다.

1. 지침 파일의 applyTo 속성 사용하기

• applyTo 속성을 사용하여 특정 파일 또는 폴더에 지침을 적용할 수 있다.
• 예를 들어, applyTo: "**/*.test.js" 라고 하면 테스트 파일(이름이 .test.js로 끝나는 JavaScript 파일)에만 지침이 적용된다.

---

.github/prompts 설정 방법

프롬프트 파일은 자주 수행하는 작업(예: 코드 생성, 보안 리뷰 등)을 위해 재사용 가능한 프롬프트(지시문)를 정의한 Markdown 파일이다. 보안 리뷰는 코드에 비밀번호가 그대로 적혀 있거나 외부 입력을 검사 없이 쓰는 곳이 없는지 살펴보는 일이다.

앞의 지침 파일과 다른 점은 언제 쓰이느냐다. 지침은 요청할 때마다 자동으로 붙는 「항상 지킬 규칙」이고, 프롬프트 파일은 내가 부를 때만 쓰이는 「자주 시키는 일 하나를 미리 적어 둔 지시문」이다. 프롬프트 파일은 이름 끝을 .prompt.md로 짓는다. 예를 들어 .github/prompts/react-form.prompt.md를 만들면, 채팅 창에서 /react-form처럼 / 뒤에 꼬리를 뺀 이름을 적어 부른다.

VS Code는 프롬프트 파일에 대해 두 가지 유형의 범위를 지원한다.

• 작업공간 프롬프트 파일: 작업 공간(앞에서 말한 워크스페이스) 내에서만 사용할 수 있으며 .github/prompts 폴더에 저장된다.
• 사용자 프롬프트 파일: 여러 작업 공간에서 사용할 수 있으며 현재 VS Code 프로필(앞에서 말한 사용자 프로필)에 저장된다.

프롬프트 파일 예시 — React 폼 컴포넌트를 만드는 지시문

React 컴포넌트 생성 프롬프트 파일 예시:

---
mode: 'agent'
tools: ['githubRepo', 'codebase']
description: '리엑트 컴포넌트를 생성하는 프롬프트'
---
당신의 목표는 #githubRepo contoso/react-templates에 있는 템플릿을 기반으로 새로운 React 폼 컴포넌트를 생성하는 것입니다.

폼 이름이나 필드 정보가 제공되지 않은 경우, 사용자에게 먼저 해당 정보를 요청하세요.

Requirements for the form:
- design-system/Form.md에 정의된 디자인 시스템의 폼 컴포넌트를 사용하세요.
- react-hook-form 을 사용하여 폼 상태를 관리하세요.
- 폼 데이터를 위한 TypeScript 타입을 반드시 정의하세요.
- 컴포넌트는 가능한 한 uncontrolled 방식(register 사용)을 선호합니다.
- defaultValues 를 사용하여 불필요한 리렌더링을 방지하세요.
- 유효성 검사는 yup 라이브러리를 사용하세요:
- 재사용 가능한 검증 스키마는 별도의 파일로 분리해서 관리하세요.
- TypeScript 타입을 사용하여 타입 안정성을 보장하세요.
- 사용자 친화적인 UX 중심의 검증 규칙을 정의하세요.

이 예시는 폼(입력 칸 묶음) 화면 조각을 만들게 하는 프롬프트다. 위에서부터 따라가면 이렇다.

• 맨 위 --- 사이는 앞의 .instructions.md와 같은 front matter다. mode: 'agent'는 Copilot 채팅을 에이전트 모드로 돌리라는 뜻이다(지금 공식 문서는 같은 일을 agent: 'agent' 필드로 적는다). 에이전트 모드에서는 Copilot이 답만 하지 않고 파일을 찾아 읽고 고치는 일을 스스로 이어 간다.
• tools는 그 모드에서 Copilot이 쓸 도구 목록이다. #githubRepo는 지정한 GitHub 저장소의 코드를 참고하게 하는 기능이고, 뒤에 적은 contoso/react-templates가 그 저장소 이름이다. front matter의 tools에 githubRepo를 켜 두고, 본문에서는 #githubRepo처럼 앞에 #을 붙여 그 도구를 부른다. 지금 공식 문서는 프롬프트 파일 본문에서 도구를 부를 때 #tool:githubRepo처럼 #tool: 뒤에 도구 이름을 적으라고 한다. codebase는 지금 열어 둔 프로젝트의 코드에서 관련된 부분을 찾아 참고하게 하는 도구다.
• 그 아래는 AI에게 주는 지시문 본문이다. 템플릿을 바탕으로 폼을 만들고, 정보가 없으면 먼저 사용자에게 물으라고 한다.
• 요구사항 목록의 design-system/Form.md는 이 예시 프로젝트 안에 있다고 가정한 디자인 시스템 문서다. react-hook-form과 yup은 둘 다 자바스크립트 라이브러리인데, react-hook-form은 폼의 입력값과 상태를 관리해 주고 yup은 그 입력값이 조건에 맞는지 검증하는 규칙(검증 스키마)을 적는 데 쓴다.
• uncontrolled 방식(register 사용), defaultValues, 리렌더링(화면 다시 그리기)은 react-hook-form을 쓸 때의 세부 방식이다. 이 글에서 볼 것은 그 뜻이 아니라, 이런 세부 요구를 프롬프트 파일에 한 번 적어 두면 매번 다시 타이핑하지 않아도 된다는 점이다. 타입 안정성은 값의 타입을 미리 적어 두어, 잘못된 종류의 값이 들어가는 실수를 실행 전에 잡는다는 뜻이다. UX 중심의 검증 규칙은 사용자가 무엇을 잘못 입력했는지 알아보기 쉽게 알려 주라는 뜻이다.

프롬프트 파일 기능은 아직 실험 중인 기능이라, 내가 직접 써 본 결과는 이 글에 아직 없다. 기능이 완성되면 추후 업데이트하겠다.

---

자신만의 철학을 만들어가는 중입니다.

---

최상단으로 이동했습니다!