GitHub Copilot CLI: 터미널에서 동작하는 AI Coding Agent
업데이트:
개요
코드를 작성할 때 터미널은 빌드, 테스트, Git, 로그 분석이 만나는 작업 공간이다. GitHub Copilot CLI는 이 공간에서 질문에 답하는 것을 넘어, 저장소를 탐색하고 변경안을 만들고 테스트를 실행하는 Agent형 CLI다.
IDE를 벗어나지 않고도 작업할 수 있는 Copilot Chat과 달리, Copilot CLI는 현재 디렉터리와 셸 작업 흐름을 중심으로 동작한다. 따라서 “이 오류를 고쳐 줘”처럼 결과만 요청할 수도 있고, “먼저 원인을 분석하고 변경 계획과 검증 명령을 제시해 줘”처럼 작업 방식을 제어할 수도 있다.
이 글은 2026년 7월 기준 GitHub 공식 문서를 바탕으로 Copilot CLI의 개념과 작동 방식을 정리한다. 공개되지 않은 내부 모델·서버 구현을 사실처럼 설명하지 않기 위해, 아키텍처 부분은 공식 기능을 토대로 한 개념 모델로 구분한다.
GitHub Copilot CLI란?
GitHub Copilot CLI는 copilot 명령으로 실행하는 터미널 네이티브 AI Coding Agent다.
대화형 세션에서 코드와 파일을 다루며, GitHub.com의 이슈·Pull Request 같은 개발 흐름과도 연계할 수 있다.
| 구분 | GitHub Copilot CLI |
|---|---|
| 실행 위치 | 로컬 터미널(PowerShell, WSL, macOS, Linux 등) |
| 기본 명령 | copilot |
| 주요 역할 | 코드 탐색, 수정 제안 및 적용, 디버깅, 테스트·명령 실행, GitHub 작업 보조 |
| 사용 형태 | 대화형 세션, -p 옵션을 사용하는 비대화형 호출 |
| 통제 방식 | 디렉터리 신뢰, 도구·경로·URL 권한 승인, 샌드박스 |
| 확장 방식 | Custom Instructions, MCP, Custom Agent, Hook, Skill, LSP |
이름이 비슷한 과거 gh copilot GitHub CLI 확장과 혼동하지 않는 것이 좋다.
이 글에서 다루는 대상은 GitHub이 별도 CLI로 배포하는 @github/copilot 패키지와 copilot 명령이다.
Chatbot이 아니라 Agent인 이유
일반적인 챗봇은 프롬프트를 받고 텍스트를 돌려주는 데 초점을 둔다. Copilot CLI는 모델의 응답을 바탕으로 파일 검색, 파일 읽기·수정, 셸 명령, Git 작업 같은 도구 사용을 제안하고 그 결과를 다음 판단에 반영한다.
질문 응답 중심
사용자 → 모델 → 텍스트 답변
작업 수행 중심
사용자 → Copilot CLI → 계획 → 도구 실행 → 결과 관찰 → 수정/검증 → 요약
단, Agent가 제안한 변경이 곧 정답이라는 뜻은 아니다. 특히 데이터 삭제, 인프라 변경, 의존성 업그레이드, 보안 설정 변경은 사람이 diff와 실행 명령을 검토해야 한다.
설치와 첫 실행
GitHub Copilot 구독이 필요하며, 조직에서 제공받는 계정은 관리자가 Copilot CLI 사용 정책을 허용해야 한다. Windows에서는 PowerShell 6 이상이 필요하다.
| 환경 | 설치 방법 | 비고 |
|---|---|---|
| Windows | winget install GitHub.Copilot |
Windows 패키지 관리자 사용 |
| 모든 플랫폼 | npm install -g @github/copilot |
Node.js 22 이상 필요 |
| macOS / Linux | brew install --cask copilot-cli |
Homebrew 사용 |
프로젝트 루트에서 다음처럼 시작한다.
copilot
처음 실행하면 /login으로 GitHub 인증을 진행한다.
그 다음 CLI는 현재 디렉터리와 하위 파일을 AI 도구가 다뤄도 되는지 신뢰 여부를 묻는다.
실험용 저장소나 실제 작업 저장소처럼 내용을 알고 신뢰하는 디렉터리에서만 승인하는 것이 원칙이다.
> Give me an overview of this project.
> Find the failing tests, explain the likely root cause, and propose the smallest fix.
> Before editing any file, show the plan and the validation commands.
대화형과 비대화형 모드
Copilot CLI는 두 가지 인터페이스를 제공한다.
| 모드 | 사용 방법 | 적합한 작업 |
|---|---|---|
| 대화형 | copilot |
탐색, 단계적 구현, 피드백, 복잡한 디버깅 |
| 비대화형 | copilot -p "프롬프트" |
단일 질문, 스크립트·자동화의 AI 단계 |
비대화형 모드에서 -s를 함께 사용하면 부가 사용량 정보를 제외하고 Copilot의 응답만 받을 수 있다.
copilot -sp "Summarize the uncommitted changes in this repository in Korean."
스크립트에 넣을 때도 결과를 맹신하면 안 된다. 자동화 대상은 읽기 전용 분석이나 명확한 출력 형식의 요약부터 시작하고, 파일 변경이나 배포는 별도의 검증·승인 단계를 두는 편이 안전하다.
핵심 개념
Context: Agent가 판단할 재료
Agent의 품질은 모델 자체뿐 아니라 어떤 맥락을 제공하는지에 크게 좌우된다. Copilot CLI는 현재 작업 디렉터리, 사용자가 언급한 파일, 대화 이력, 도구 실행 결과를 조합해 다음 행동을 결정한다.
특히 저장소 규칙은 매번 프롬프트에 반복하지 말고 Custom Instructions로 관리하는 것이 좋다. Copilot CLI는 다음 형식의 지시 파일을 지원한다.
- 저장소 공통 지시:
.github/copilot-instructions.md - 경로별 지시:
.github/instructions/**/*.instructions.md - Agent 지시:
AGENTS.md
현재 블로그 저장소의 .github/copilot-instructions.md도 이 역할을 한다.
Jekyll 구조, 포스트 front matter, 한국어 본문, 외부 링크 형식, 이미지 경로와 빌드 명령을 명시해 두었기 때문에 Copilot CLI는 새 글을 작성할 때 이 규칙을 프롬프트에 자동으로 결합할 수 있다.
Tool: 답변을 행동으로 바꾸는 수단
Copilot CLI는 파일·셸·GitHub 관련 도구를 이용해 작업할 수 있다. 도구 결과는 다음 단계의 관찰값이 된다. 예를 들어 테스트 실패를 해결할 때는 실패 로그를 읽고, 관련 코드를 검색하고, 최소 변경을 적용하고, 테스트를 다시 실행하는 식이다.
중요한 것은 권한 경계다. 처음 사용하는 수정·실행 도구는 승인 여부를 묻고, 세션 중 해당 도구를 계속 허용할지 선택할 수 있다. 도구 전체를 허용하는 선택은 편리하지만, 그만큼 검토 기회를 잃는다.
Permission: Agent의 행동 반경
Copilot CLI의 권한은 단순한 yes/no가 아니다.
| 권한 층 | 제어 대상 | 기본적인 운영 원칙 |
|---|---|---|
| Trusted directory | 읽기·수정·실행을 허용할 작업 위치 | 신뢰하는 저장소 루트에서만 시작 |
| Tool permission | 셸·파일 작업 등의 도구 사용 | 필요한 도구만 세션 단위로 승인 |
| Path permission | 접근 가능한 파일·디렉터리 | 현재 작업 디렉터리 밖은 최소화 |
| URL permission | 웹 접근과 네트워크 명령의 URL | 필요한 도메인만 승인 |
| Sandbox | 파일 시스템·네트워크·시스템 능력 | 위험하거나 자율적인 작업은 격리 환경에서 실행 |
--allow-all 또는 별칭 --yolo는 도구·경로·URL 검증을 한 번에 완화한다.
신뢰 가능한 격리 테스트 환경이 아니라면 일반 개발 디렉터리에서 사용하지 않는 편이 좋다.
동작 메커니즘
Copilot CLI의 내부 구현 전체는 공개되어 있지 않다. 다만 공식 문서에 공개된 권한, 컨텍스트, 확장 기능을 기준으로 한 번의 작업 턴을 개념적으로 표현하면 다음과 같다.
1. 사용자 요청
|
2. Context 수집
- 현재 디렉터리와 명시한 파일(@)
- 대화 이력과 이전 도구 결과
- copilot-instructions.md, AGENTS.md 등 저장소 규칙
|
3. Agent 추론 및 계획
|
4. 도구 호출 제안
- 파일 탐색 / 코드 검색 / 셸 / GitHub / MCP / LSP
|
5. 권한 검사 및 사용자 승인
|
6. 도구 실행 결과 관찰
|
7. 추가 조사·수정·검증이 필요하면 3으로 반복
|
8. 변경 요약, 검증 결과, 남은 위험 보고
Context 관리
긴 세션은 대화 이력 때문에 컨텍스트가 가득 차기 쉽다.
Copilot CLI는 토큰 한도에 가까워지면 대화 이력을 자동 압축(auto-compaction)하며, 사용자는 /compact로 직접 압축할 수 있다.
/context 명령은 컨텍스트 사용량의 상세 내역을 확인할 때 사용한다.
압축은 작업을 계속하기 위한 요약이지 모든 세부 정보를 영구 보존하는 기능은 아니다.
중요한 결정, 정확한 오류 로그, 사용자 요구사항은 README, 이슈, 설계 문서 또는 Custom Instructions처럼 저장소에 남는 문서로 관리하는 편이 재현성이 높다.
반복과 Steering
Agent 작업은 한 번의 명령이 아니라 관찰과 조정의 반복이다. 대화형 세션에서 사용자는 다음처럼 중간에 방향을 바꿀 수 있다.
> Analyze the test failure. Do not edit files yet.
... 분석 결과 확인 후 ...
> Apply only the null-handling fix. Do not change public APIs.
> Run the focused test first, then the full test suite if it passes.
이 방식은 “수정해 줘”라고 넓게 요청한 뒤 큰 diff를 받는 것보다 안전하다. 목표, 수정 범위, 금지 사항, 검증 방법을 짧게 나누어 제공하면 사람과 Agent 모두 현재 상태를 확인하기 쉬워진다.
개념 아키텍처
아래 그림은 Copilot CLI를 팀 개발 환경에 배치할 때 이해하기 좋은 논리 아키텍처다.
┌───────────────────────────────────────────────────────────────────┐
│ Developer Terminal │
│ copilot / copilot -p │
└───────────────────────────────┬───────────────────────────────────┘
│ prompt · steering · approval
┌───────────────────────────────▼───────────────────────────────────┐
│ Copilot CLI Session │
│ Context manager ─ Agent/model orchestration ─ Conversation state │
└───────────────┬───────────────────────────────────────┬───────────┘
│ │
┌──────────▼──────────┐ ┌──────────▼──────────┐
│ Policy boundary │ │ Customization │
│ trusted directory │ │ Instructions │
│ tools / paths / URL │ │ Agents · Skills │
│ sandbox │ │ Hooks · Memory │
└──────────┬──────────┘ └──────────┬──────────┘
│ │
┌───────────────▼───────────────────────────────────────▼───────────┐
│ Execution and knowledge layer │
│ workspace · shell · Git · GitHub.com · MCP servers · LSP servers │
└───────────────────────────────────────────────────────────────────┘
| 구성 요소 | 역할 | 실무에서 확인할 점 |
|---|---|---|
| Terminal UI | 프롬프트, 진행 상태, 승인과 Steering | 사람이 중간 결과와 실행 명령을 검토 |
| Context manager | 대화·파일·지시 파일을 작업 맥락으로 구성 | 불필요한 비밀·대용량 파일을 넣지 않기 |
| Agent / model | 계획 수립, 도구 호출 판단, 결과 종합 | 출력은 제안이며 테스트·리뷰가 필요 |
| Policy boundary | 신뢰 디렉터리와 도구·경로·URL 권한 집행 | 최소 권한과 격리 환경 우선 |
| MCP server | 외부 데이터·도구를 Agent에 제공 | 서버의 신뢰성·권한·데이터 노출 검토 |
| LSP server | 정의 이동, 진단 등 언어별 코드 인텔리전스 제공 | 필요한 언어 서버를 별도 설치·설정 |
| Hook / Skill / Custom Agent | 반복 절차와 역할 전문화 | 팀 표준을 코드 리뷰 가능한 파일로 관리 |
확장 지점은 역할에 맞춰 선택한다
| 요구사항 | 적합한 확장 | 예시 |
|---|---|---|
| 모든 작업의 공통 규칙 | Custom Instructions | 빌드 명령, 코드 스타일, 금지 파일 |
| 특정 역할의 전문 지침 | Custom Agent | Java 리뷰어, 보안 점검 Agent |
| 외부 시스템의 데이터·도구 | MCP | 이슈 트래커, 내부 문서, 데이터베이스 조회 |
| 실행 전후의 강제 검사·로그 | Hook | formatter, secret scan, 감사 로그 |
| 재사용 가능한 절차·스크립트 | Skill | 배포 전 점검, 장애 로그 분류 |
| 언어 의미 분석 | LSP | 정의 탐색, hover, diagnostics |
모든 기능을 한꺼번에 켤 필요는 없다.
대부분의 팀은 우선 .github/copilot-instructions.md로 빌드·테스트·코딩 규칙을 정리하고, 반복 업무가 분명해진 뒤에 Custom Agent나 Hook을 추가하는 순서가 관리하기 쉽다.
활용 예제
1. Spring Boot 버그를 최소 변경으로 수정하기
먼저 전체 구현을 맡기기보다 분석과 변경을 분리한다.
> @src/main/java/com/example/order/OrderService.java
> @src/test/java/com/example/order/OrderServiceTest.java
> 이 테스트가 실패하는 원인을 분석해 줘.
> 아직 파일은 수정하지 말고, 재현 절차·근본 원인·최소 수정안을 표로 제시해 줘.
분석 결과가 타당하면 다음처럼 범위를 제한한다.
> 제시한 null 처리 수정만 적용해 줘.
> public API와 데이터베이스 스키마는 변경하지 마.
> 먼저 ./gradlew test --tests '*OrderServiceTest'를 실행하고,
> 통과하면 ./gradlew test를 실행해. 실행한 명령과 결과를 마지막에 요약해 줘.
이 프롬프트의 핵심은 다음 네 가지다.
@로 확인해야 할 파일을 좁혀 불필요한 추측을 줄인다.- 분석과 수정을 분리해 변경 전에 원인을 검토한다.
- public API·스키마처럼 바꾸면 안 되는 경계를 명시한다.
- 검증 명령과 성공 기준을 작업 요청에 포함한다.
2. 프로젝트 규칙을 Custom Instructions로 제공하기
반복되는 규칙은 사람의 기억이나 긴 프롬프트에 맡기지 말고 저장소에 둔다. 다음은 Spring Boot + Gradle 프로젝트의 간결한 예시다.
# .github/copilot-instructions.md
## Project rules
- Java 21과 Spring Boot를 사용한다.
- 의존성 주입은 생성자 주입을 사용한다.
- 새 기능에는 정상·예외 경로의 테스트를 추가한다.
- 비밀값, 토큰, 실제 운영 URL을 코드와 문서에 기록하지 않는다.
## Validation
- 수정 전 관련 테스트를 먼저 확인한다.
- Java 변경 후 `./gradlew test`를 실행한다.
- 빌드가 실패하면 원인과 재현 명령을 보고하고 무관한 파일을 수정하지 않는다.
Copilot CLI는 이 파일을 현재 저장소의 공통 지시로 발견해 프롬프트에 자동으로 포함할 수 있다. 여러 지시 파일이 적용되면 지시가 결합되므로, 같은 규칙을 서로 반대로 쓰지 않도록 관리해야 한다.
3. 이 Jekyll 블로그에 글 초안 만들기
이 저장소에는 이미 포스트 위치, Markdown 문법, front matter, 이미지 규칙, 외부 링크 형식이 .github/copilot-instructions.md에 정리되어 있다.
따라서 요구사항을 구체적으로 주면 작업 품질을 높일 수 있다.
> AI 카테고리에 GitHub Copilot CLI 소개 글 초안을 작성해 줘.
> 파일명은 오늘 날짜와 영문 slug를 사용해.
> 소개, 핵심 개념, 동작 메커니즘, 개념 아키텍처, Spring Boot 활용 예제,
> 보안 주의사항, 공식 참고 링크를 반드시 포함해.
> 외부 링크에는 target="_blank" 속성을 사용하고,
> 새 파일만 만들기 전에 목차와 front matter를 먼저 보여 줘.
글 생성 작업도 코드 변경과 같다. 생성 뒤에는 front matter의 필수 필드, 링크 대상, 코드 블록 언어, Jekyll 빌드 결과를 검토해야 한다.
bundle exec jekyll build
4. 비대화형으로 Git diff 요약하기
단일 분석은 비대화형 호출이 편리하다.
copilot -sp "현재 저장소의 git diff를 분석해. 변경 파일별로 의도, 위험, 필요한 테스트를 한국어 Markdown 표로 요약해. 파일을 수정하거나 명령을 실행하지 마."
이 예시는 읽기·요약 작업이므로 자동화 후보가 될 수 있다. 그러나 Pull Request 생성, 배포, 데이터 변경처럼 외부 상태를 바꾸는 일은 결과를 사람이 확인하는 별도 단계로 분리한다.
안전하게 사용하는 운영 패턴
Copilot CLI는 개발자의 권한 안에서 파일을 수정하고 명령을 실행할 수 있다. 따라서 보안은 기능을 끄는 문제가 아니라, 작업의 위험도에 맞춰 권한을 설계하는 문제다.
| 단계 | 권장 행동 | 이유 |
|---|---|---|
| 1. 시작 | 신뢰할 수 있는 저장소 루트에서 실행 | 홈 디렉터리·민감 파일 노출 위험 축소 |
| 2. 탐색 | 먼저 읽기 전용 분석과 계획 요청 | 큰 변경 전 방향을 확인 |
| 3. 실행 | 필요한 도구만 세션 단위로 승인 | 과도한 자동 실행 방지 |
| 4. 검증 | focused test → 전체 테스트 → diff 검토 | 변경 효과와 부작용 확인 |
| 5. 고위험 작업 | 샌드박스·VM·컨테이너 사용 | 파일·네트워크 영향 격리 |
| 6. 외부 연동 | MCP 서버의 권한·데이터 범위 확인 | 토큰과 사내 데이터의 불필요한 노출 방지 |
특히 rm, 패키지 설치, 배포 명령, DB 마이그레이션, 시크릿을 다루는 명령은 “이번 한 번만” 승인하는 습관이 좋다.
세션 전체 허용을 선택했다면 해당 도구가 이후에는 다른 인자로도 실행될 수 있음을 이해해야 한다.
Cloud 및 local sandbox는 격리 실행을 돕지만, 기능 상태와 조직 정책은 변할 수 있다. 제품 기본 보호 장치만으로 충분하다고 가정하지 말고, 팀의 보안 정책과 CI 검증을 함께 적용해야 한다.
마무리
GitHub Copilot CLI의 가치는 터미널에 채팅창을 하나 더 붙이는 데 있지 않다. 프로젝트 규칙과 현재 작업 맥락을 바탕으로 탐색 → 계획 → 도구 실행 → 검증 → 보고를 이어 주는 데 있다.
효과적으로 사용하려면 다음 원칙을 기억하면 된다.
- 지시 파일로 팀 규칙과 검증 방법을 저장소에 명시한다.
- 넓은 요청보다 목표·범위·금지 사항·검증 기준을 함께 제시한다.
- 분석과 변경을 분리하고, diff와 테스트 결과를 직접 확인한다.
- 권한은 최소화하고, 고위험 작업은 샌드박스나 격리 환경에서 수행한다.
- MCP, Hook, Skill, Custom Agent는 반복되는 필요가 확인된 뒤 작은 범위부터 도입한다.
AI Agent는 개발자의 검토를 대체하기보다 반복적인 탐색과 실행을 줄여 더 중요한 판단에 집중하도록 돕는 도구로 사용할 때 가장 안정적이다.
댓글남기기