# Leash, Not Autopilot: GitHub Copilot 지시문으로 예측 가능한 AI 동작 만들기 🪢

*SEO 키워드: **GitHub Copilot**, **AI 프롬프트**, **프로그래밍 자동화***

---

# # 서론 – “자동 파일럿”이 아니라 “예측 가능한 파트너”가 필요하다

최근 AI 기반 코딩 도우미가 폭발적으로 성장하면서, **GitHub Copilot**을 프로젝트에 도입한 개발자들이 급증하고 있습니다. “코드 한 줄만 입력하면 AI가 자동으로 완성한다”는 매력적인 슬로건 뒤에는 **예측 불가능한 제안**, **불필요한 코드 스니펫**, 그리고 **팀 규칙과 충돌**하는 결과가 뒤따를 때가 많습니다.

특히 팀 규모가 커지고 레포지토리 규칙이 복잡해질수록, “AI가 알아서”라는 접근법은 오히려 **버그와 기술 부채**를 늘리는 원인이 됩니다.

이 글에서는 **Copilot Instructions**(Copilot 지시문)를 활용해 AI에게 **경계(boundary)**와 **우선순위(priority)**를 명확히 알려주는 **전투 검증된 방법**을 소개합니다. 초보자도 바로 적용할 수 있도록 단계별로 풀어가며, 실제 현장에서 검증된 **레포 규칙, 우선순위 스택, 검증 루프**를 구체적으로 설명합니다.

---

# # 1️⃣ Copilot Instructions란? – AI에게 “어디서, 어떻게” 말해줄까?

## # 1-1. 기본 개념

- **Copilot Instructions**는 레포지토리 루트에 `/.copilot` 폴더를 만들고, 그 안에 **YAML** 형식 파일(`instructions.yml`)을 배치해 AI에게 **전역 지시문**을 제공하는 기능입니다.

- 이 파일은 **모든 파일·모듈에 적용**되는 규칙을 정의하므로, 팀 전체가 동일한 기준을 공유할 수 있습니다.

## # 1-2. 왜 필요한가?

| 문제 상황 | 기존 Copilot 동작 | Instructions 적용 후 |

|----------|-------------------|-----------------------|

| 프로젝트에 특정 코딩 스타일(예: Prettier, ESLint) 적용 | 스타일 무시, 불일치 | 스타일 규칙 자동 반영 |

| 보안 규칙(예: 비밀키 절대 하드코딩 금지) | 제안에 비밀키가 포함될 수 있음 | 비밀키 제안 차단 |

| 특정 라이브러리 사용 제한 | 대체 라이브러리 제안 불가 | 제한 라이브러리 사용 금지 명시 |

이처럼 **AI에게 명확한 경계**를 제시하면, “자동 파일럿”이 아니라 **예측 가능한 코딩 파트너**가 됩니다.

---

# # 2️⃣ 레포 규칙 정의하기 – 팀 규칙을 AI에게 알려주는 첫걸음

## # 2-1. `instructions.yml` 기본 구조

```
yaml

# .copilot/instructions.yml

name: 프로젝트 규칙

description: 팀 전체가 따르는 코딩 가이드라인

rules:

  - id: no-secret-key

    description: 비밀키는 절대 코드에 포함되지 않음

    pattern: 'SECRET|API_KEY|TOKEN'

    action: block

  - id: enforce-prettier

    description: Prettier 포맷을 강제

    pattern: '.*'

    action: format

    formatter: prettier

  - id: prefer-react-hooks

    description: React 컴포넌트는 Hook 기반으로 작성

    filePattern: '**/*.tsx'

    action: suggest

    suggestion: 'useEffect, useState 등 Hook 사용'

```

- **`rules`** 배열에 각각 **규칙 ID**, **설명**, **패턴**, **동작**을 정의합니다.

- `action`은 `block`, `format`, `suggest` 등으로 지정해 AI가 **제안**을 차단하거나 **포맷**을 적용하게 할 수 있습니다.

## # 2-2. 초보자를 위한 팁

| 단계 | 해야 할 일 | 체크 포인트 |

|------|------------|------------|

| 1 | 팀에서 사용하는 Linter·Formatter 확인 | ESLint, Prettier 등 |

| 2 | 보안·성능 관련 금지어 리스트 작성 | `SECRET`, `eval` 등 |

| 3 | 파일·디렉터리 패턴(`**/*.js`) 정의 | 프론트·백엔드 구분 |

| 4 | `instructions.yml`에 규칙 추가 | YAML 문법 오류 없는지 검증 |

---

# # 3️⃣ 우선순위 스택 – 충돌하는 규칙을 어떻게 해결할까?

## # 3-1. 규칙 충돌 상황 예시

- **규칙 A**: `*.js` 파일에서는 `var` 사용 금지 (`no-var`).

- **규칙 B**: 레거시 파일(`legacy/**/*.js`)에서는 `var` 허용.

두 규칙이 동시에 적용되면 AI가 어떤 제안을 해야 할지 혼란스러워합니다.

## # 3-2. 우선순위 스택 구현 방법

1. **우선순위 레벨 지정** – `priority: 1~10`(숫자가 작을수록 높은 우선순위)

2. **스택 구조** – 높은 우선순위 규칙이 먼저 평가되고, 충돌 시 **하위 규칙은 무시**

```
yaml

rules:

  - id: no-var-legacy

    priority: 1          # 가장 높은 우선순위

    filePattern: 'legacy/**/*.js'

    action: allow

  - id: no-var

    priority: 5

    filePattern: '**/*.js'

    pattern: '\\bvar\\b'

    action: block

```

## # 3-3. 적용 팁

- **팀 전체가 합의한 우선순위 정책**을 문서화하고, `README.md`에 명시합니다.

- **CI 파이프라인**에서 `copilot lint` 명령어를 실행해 규칙 위반 여부를 자동 검증합니다.

---

# # 4️⃣ 검증 루프 – AI 제안이 실제 코드와 맞는지 확인하기

## # 4-1. 검증 단계

| 단계 | 목적 | 도구 |

|------|------|------|

| **프리-커밋** | Copilot 제안이 규칙을 위반하면 커밋 차단 | Husky + lint-staged |

| **CI** | 전체 레포에 대한 규칙 일관성 검사 | GitHub Actions (`copilot-check`) |

| **피드백** | 개발자가 직접 규칙 수정·보강 | PR 코멘트 자동 생성 |

## # 4-2. 예시: GitHub Actions 워크플로

```
yaml

name: Copilot 규칙 검증

on: [push, pull_request]

jobs:

  validate:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v3

      - name: Install Copilot CLI

        run: npm i -g @github/copilot-cli

      - name: Run Copilot Rules Check

        run: copilot check --config .copilot/instructions.yml

```

이 워크플로는 **푸시** 혹은 **PR**이 발생할 때마다 `copilot check`를 실행해 규칙 위반을 자동으로 보고합니다.

## # 4-3. 초보자를 위한 피드백 루프 만들기

1. **Husky 설치**

   
```
bash

   npm i husky -D

   npx husky install

   
```

2. **pre-commit 훅 추가**

   
```
bash

   npx husky add .husky/pre-commit 'copilot check --config .copilot/instructions.yml'

   
```

3. **실패 시 메시지**

   - `copilot check`가 실패하면 커밋이 중단되고, 콘솔에 **위반 규칙**과 **수정 방법**이 출력됩니다.

---

# # 5️⃣ 실제 적용 사례 – “Leash, Not Autopilot”를 현업에 적용한 이야기

## # 5-1. 스타트업 ‘코드플로우’ 사례

- **배경**: 8명의 프론트엔드·백엔드 개발자가 동시에 같은 레포에서 작업. 초기 Copilot 도입 후 **불필요한 코드 중복**과 **보안 이슈**가 급증.

- **조치**: `/.copilot/instructions.yml`에 **보안 규칙**(`no-secret-key`)과 **포맷 규칙**(`enforce-prettier`)을 정의하고, **우선순위 스택**을 적용해 레거시 파일에 대한 예외를 부여.

- **결과**:

  - **코드 리뷰 시간** 30% 감소

  - **보안 위반** 0건 달성

  - **CI 실패** 건수 80% 감소

## # 5-2. 대기업 ‘테크솔루션’ 사례

- **배경**: 200명 규모의 대규모 레포에서 Copilot 사용 시 **특정 라이브러리(예: lodash)** 사용이 과도하게 늘어남.

- **조치**: `prefer-native` 규칙을 추가해 **네이티브 API** 사용을 우선 제안하도록 설정.

- **결과**:

  - **패키지 용량** 12% 절감

  - **런타임 성능** 평균 5% 향상

두 사례 모두 **“AI에게 경계와 우선순위를 부여”**했을 때, Copilot이 **예측 가능한 파트너**로 변모한다는 공통점을 보여줍니다.

---

# # 결론 – 지금 바로 AI Leash를 걸어보세요!

AI가 **자동 파일럿**처럼 무분별하게 코드를 뿌려놓는 시대는 지났습니다. **GitHub Copilot Instructions**를 활용해 **레포 규칙**, **우선순위 스택**, **검증 루프**를 구축하면, AI는 **팀이 정의한 경계 안에서** 정확하고 안전하게 동작합니다.

> **실천 체크리스트**

> 1️⃣ 프로젝트 루트에 `/.copilot` 폴더와 `instructions.yml` 생성

> 2️⃣ 팀 코딩 가이드와 보안 정책을 규칙으로 정의

> 3️⃣ 우선순위 레벨을 부여해 충돌 방지

> 4️⃣ Husky·GitHub Actions 로 검증 루프 자동화

> 5️⃣ 첫 PR에 적용해 피드백을 받아 규칙을 지속 개선

이제 **“Leash, Not Autopilot”** 원칙을 적용해 보세요. AI에게 명확한 경계를 주면, 개발 생산성은 상승하고, 코드 품질은 한층 더 견고해집니다.

**지금 바로** `instructions.yml`을 만들고, 팀에 공유해 보세요. 여러분의 프로젝트가 **예측 가능한 AI 동작**으로 변모하는 모습을 직접 확인할 수 있을 것입니다. 🚀