Skip to main content
Hashnode
HA JIN-YOUNG's blog

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

Published 5 min readMarkdown
H
HA JIN-YOUNG

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
  1. pre-commit 훅 추가
bash

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

  1. 실패 시 메시지

    • 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 동작으로 변모하는 모습을 직접 확인할 수 있을 것입니다. 🚀

Comments

Join the discussion

No comments yet. Be the first to comment.

More from this blog