GitHub Copilot 앱 초보자 가이드: 저장소 규칙·실행 설정으로 코드베이스 온보딩하기

GitHub Copilot 앱에서 기존 프로젝트를 처음 열었다면, 곧바로 기능 구현을 맡기기보다 낮은 위험의 브랜치 또는 복제 가능한 테스트 저장소를 연결하고, 구조 확인 → 실행 명령 확인 → 테스트 → 작은 변경 검토 순서로 시작하는 편이 좋습니다. 핵심은 Copilot에 코드를 영구 학습시키는 일이 아니라, 저장소 컨텍스트와 프로젝트 규칙을 제공하는 일입니다.

Copilot 앱은 일반적인 데스크톱 AI 앱과 달리 저장소·실행 환경을 다루는 개발 도구입니다. 운영체제별 AI 앱 선택 자체가 필요하다면 컴퓨터에 설치해 쓰는 AI 프로그램 비교도 함께 볼 수 있습니다.

GitHub Copilot 앱으로 코드베이스를 ‘가르친다’는 말의 의미: 학습이 아닌 컨텍스트 설정

저장소 컨텍스트가 있는 대화에서 Copilot은 저장소를 인덱싱해 코드 구조와 로직 관련 답변을 개선합니다. 큰 저장소의 최초 인덱싱에는 최대 60초가 걸릴 수 있으며, 이후 변경은 보통 빠르게 반영됩니다. 다만 GitHub은 이 저장소 인덱스를 모델 학습에 사용하지 않는다고 안내합니다. 즉 모델을 재훈련하는 것이 아니라, 필요한 코드를 찾고 답변에 참고할 맥락을 마련하는 과정입니다.

첫 연결: GitHub 저장소 또는 로컬 폴더를 연결하고 탐색부터 시작하기

GitHub 계정으로 Copilot 앱에 로그인한 뒤 GitHub 저장소 또는 로컬 폴더를 연결해 첫 에이전트 세션을 시작할 수 있습니다. 처음에는 코드 수정 요청 대신 “이 프로젝트의 목적과 주요 폴더를 실제 파일 근거와 함께 요약해 달라”, “로컬 실행 및 테스트 명령은 어디에 정의돼 있는가”처럼 탐색 질문을 합니다.

응답은 README, 패키지 설정 파일, CI 설정 등 실제 파일과 대조하세요. 실행 명령이 불명확하다면 자동 실행으로 넘어가지 말고, 저장소 담당자가 명령을 확인해 지시 파일에 남기는 것이 다음 단계입니다.

1단계 — `.github/copilot-instructions.md`에 저장소 전체 규칙 기록하기

저장소 전반에 적용할 지시는 .github/copilot-instructions.md에 작성할 수 있습니다. 파일이 이미 있다면 새 파일로 덮어쓰지 말고 현재 내용을 검토한 뒤 보완합니다. 이 파일에는 설명이 길기보다, 작업 판단에 필요한 사실을 명확히 적는 것이 좋습니다.

프로젝트의 목적과 주요 디렉터리 역할
빌드·로컬 실행·테스트·검증 명령
수정 전후 반드시 확인할 테스트 또는 검토 기준
변경하면 안 되는 영역이나 프로젝트 고유 규칙

예를 들어 명령 자체는 저장소의 실제 설정에서 확인한 값만 기록해야 합니다. 추측한 명령을 지시 파일에 넣으면 Copilot에도 잘못된 전제가 전달됩니다.

2단계 — `.github/instructions`에서 폴더별 규칙 분리하기

프런트엔드·백엔드·테스트 폴더처럼 규칙이 다르면 .github/instructions 아래에 NAME.instructions.md 파일을 두고 applyTo 글로브 패턴으로 적용 범위를 지정할 수 있습니다. 전체 규칙 파일에는 공통 명령과 품질 기준을, 경로별 파일에는 해당 영역에서만 필요한 규칙을 둡니다.

예를 들어 테스트 파일에는 테스트 방식과 검증 기준을, 프런트엔드 경로에는 UI 관련 규칙을 분리하는 식입니다. 서로 상충하는 지시가 늘어나지 않도록 각 파일의 적용 대상과 목적을 짧고 구체적으로 유지하세요.

3단계 — `.github/github-app.yml`의 instructions와 scripts를 실행 전에 검토하기

Copilot 앱은 저장소별 .github/github-app.yml에서 instructions, 수동·자동 실행 scripts, 서버 준비 패턴, 브라우저 열기, 세션 자동화 동작을 설정할 수 있습니다. 기존 .github/copilot-desktop.yml도 하위 호환 목적으로 지원됩니다.

여기서 중요한 기준은 편의성보다 실행 범위입니다. 어떤 명령이 실행되는지, 새 의존성을 설치하는지, 서버를 준비하거나 브라우저를 여는지 먼저 읽고 승인하세요. 설정 파일을 추가하거나 바꾼 뒤에는 코드와 마찬가지로 변경 diff를 검토합니다.

제대로 이해했는지 확인하기: 구조 요약 → 실행 명령 → 테스트 → 비파괴적 변경

구조 요약: 프로젝트 목적, 주요 폴더, 특정 기능의 구현 위치를 질문하고 실제 파일과 대조합니다.
실행 명령: 로컬 실행과 테스트 명령을 각각 물어보고 README·설정 파일에 적힌 내용과 맞는지 확인합니다.
테스트: 명령이 확인된 경우에만 테스트 실행을 요청하고, 결과와 실패 원인을 검토합니다.
작은 변경: 운영 코드 대수정보다 문서 수정이나 제한된 테스트 추가처럼 영향 범위가 작은 작업을 요청합니다.

완료 조건은 Copilot의 답변이 아니라 변경 diff가 의도와 맞고, 확인 가능한 테스트 결과가 기대와 일치하는지입니다. 테스트가 실패하거나 명령이 불명확하면 변경을 유지하지 말고 원인과 수동 확인 항목을 남긴 뒤 중단하세요.

자동 실행과 보안 검토: 스크립트·의존성·토큰·MCP 서버 승인 전 확인할 것

저장소 설정의 명령과 의존성은 검토·승인 후 적용됩니다. 특히 scripts와 하위 프로세스는 GitHub 인증 관련 환경변수를 받을 수 있습니다. 토큰을 출력·기록·저장하도록 하는 명령은 두지 않아야 합니다.

스크립트가 실제로 실행하는 명령과 설치하는 의존성은 무엇인가
외부 네트워크 접근, 파일 변경, 서버 실행이 필요한가
인증 정보가 로그·파일·하위 프로세스에 남을 가능성이 있는가
조직 정책이 허용한 모델과 MCP 서버만 사용하는가

Copilot이 만든 코드나 실행 결과가 자동으로 안전하거나 정확해지는 것은 아닙니다. 자동화 범위를 넓히기 전 권한·실행 조건·검토 지점을 정하는 원칙은 AI 도구를 고를 때 확인해야 할 기준에서도 참고할 수 있습니다.

플랜과 사용량: 무료 시작과 에이전트 작업의 AI 크레딧

2026년 10월 확인 기준 Copilot Free는 월 2,000회 코드 완성을 제공하며, 개인 플랜 표시는 Pro 월 10달러, Pro+ 월 39달러, Max 월 100달러입니다. Copilot 앱은 모든 Copilot 플랜에서 이용할 수 있다고 안내되지만, 에이전트 기능·모델 접근·사용량은 플랜과 조직 정책에 따라 달라질 수 있습니다.

AI 사용량은 AI 크레딧 단위로도 측정되며, GitHub 청구 문서는 1 AI credit을 0.01달러로 설명합니다. 따라서 앱을 쓸 수 있는지와 원하는 에이전트 작업을 충분히 수행할 수 있는지는 별도로 확인해야 합니다. 가격, 포함 크레딧, 모델 목록은 바뀔 수 있으므로 결제 전 공식 플랜 페이지를 다시 확인하세요.

시작 결론: 지시 파일보다 먼저 검증 가능한 한 작업을 고르기

처음에는 저장소 연결과 인덱싱 뒤 실제 구조·실행·테스트 정보를 확인하고, 그 사실을 copilot-instructions.md에 기록하세요. 폴더별 규칙은 실제로 달라지는 곳에만 추가하고, github-app.yml의 자동 실행은 명령과 권한을 이해한 뒤 승인하는 순서가 적합합니다. 첫 변경이 문서 또는 작은 테스트처럼 되돌리기 쉬운 범위에서 diff와 테스트 결과를 통과했다면, 그때 다음 개발 작업으로 범위를 넓힐 수 있습니다.