GitHub Copilot 맞춤형 에이전트 설정 방법 커스텀 에이전트 만들기 완전 가이드

GitHub Copilot 커스텀 에이전트 공식 문서

GitHub Copilot에서 맞춤형 에이전트(Custom Agent) 는 특정 작업에 최적화된 전문 AI 부캐를 만드는 기능입니다. 기본 Copilot이 범용 AI 어시스턴트라면, 커스텀 에이전트는 “이 프로젝트의 보안 감사 전문가”, “이 팀의 테스트 코드 작성 전담 AI”처럼 역할과 동작 방식을 세밀하게 정의한 전문 에이전트입니다. 에이전트에게 작업을 요청하면, 메인 에이전트 컨텍스트를 오염시키지 않는 독립적인 서브에이전트 로 작업을 처리하므로 더 크고 복잡한 작업도 정확하게 처리할 수 있습니다.

커스텀 에이전트는 GitHub Copilot CLI, GitHub.com의 Copilot 클라우드 에이전트, VS Code, JetBrains 등 모든 Copilot 환경에서 동일하게 사용할 수 있습니다. 파일 형식은 .agent.md 확장자의 단순한 마크다운 파일이며, YAML 프런트매터로 에이전트 속성을 정의하고, 아래 마크다운 본문에 행동 지침을 작성합니다. 이 글은 커스텀 에이전트를 처음 만드는 사람을 위한 단계별 가이드입니다.

커스텀 에이전트 파일 구조와 핵심 속성 이해하기

커스텀 에이전트는 하나의 .agent.md 파일로 정의됩니다. 파일 상단의 YAML 프런트매터에 에이전트의 메타정보를 작성하고, 그 아래 마크다운 영역에 구체적인 행동 지침(프롬프트)을 작성하는 구조입니다. 전체 프롬프트는 최대 30,000자까지 작성할 수 있습니다.

YAML 프런트매터에서 사용할 수 있는 핵심 속성은 다음과 같습니다.

• name: 에이전트의 이름입니다. 설정하지 않으면 파일명이 이름으로 사용됩니다. /agent 슬래시 명령에서 표시되는 이름이므로 역할을 직관적으로 알 수 있도록 작성합니다.
• description (필수): 에이전트가 수행하는 작업과 전문 영역을 설명합니다. Copilot이 이 설명을 바탕으로 어떤 상황에 이 에이전트를 자동 호출할지 판단하므로, 트리거 조건을 명확하게 작성하는 것이 핵심입니다.
• tools: 에이전트가 사용할 수 있는 도구 목록입니다. read, edit, search 등을 지정하거나, 이 속성을 생략하면 모든 도구에 접근 가능합니다. 보안상 민감한 에이전트라면 읽기 전용(read, search)으로 제한하는 것을 권장합니다.
• target: vscode 또는 github-copilot으로 설정해 특정 환경에서만 에이전트를 사용하도록 제한할 수 있습니다. 생략하면 모든 환경에서 사용 가능합니다.
• mcp-servers: 에이전트에서만 사용할 MCP 서버를 별도로 구성해 기능을 확장할 수 있습니다.

파일 저장 위치는 두 가지입니다. 프로젝트 전체에 적용하려면 리포지토리의 .github/agents/ 폴더에, 개인 환경 어디서나 사용하려면 홈 디렉터리의 ~/.copilot/agents/ 폴더에 저장합니다. 같은 이름의 에이전트가 두 위치에 모두 있을 경우 홈 디렉터리의 것이 우선 적용됩니다.

커스텀 에이전트 만들기 두 가지 방법

방법 1: CLI 안에서 대화형으로 만들기

Copilot CLI 대화형 세션에서 /agent를 입력하고 “새 에이전트 만들기”를 선택합니다. 저장 위치(프로젝트 또는 홈 디렉터리)를 선택한 뒤, Copilot에게 만들고 싶은 에이전트를 자연어로 설명하면 Copilot이 자동으로 에이전트 프로필을 작성해줍니다. 예를 들어 아래처럼 입력할 수 있습니다.

너는 보안 전문가야. 코드 파일에서 잠재적인 보안 문제를 철저히 검토해. "seccheck"라는 단어가 포함된 프롬프트가 오거나 코드 보안 감사 요청이 있을 때 나를 사용해. 문제가 발견되면 GitHub 이슈를 자동으로 생성해줘.

Copilot이 프로필 초안을 생성하면 검토·수정 후 완성할 수 있습니다. 에이전트 생성 후 CLI를 재시작하면 새 에이전트가 로드됩니다.

방법 2: 파일을 직접 작성하기

.agent.md 파일을 직접 작성하는 방법입니다. GitHub 공식 문서가 제공하는 두 가지 에이전트 예시를 살펴보겠습니다.

**테스트 전문가 에이전트** — 프로덕션 코드는 건드리지 않고 테스트 코드 작성과 품질 개선에만 집중하는 에이전트입니다.


name: test-specialist
description: 테스트 커버리지 및 품질 개선에 집중하며 프로덕션 코드는 수정하지 않습니다

당신은 종합적인 테스트를 통해 코드 품질을 개선하는 테스팅 전문가입니다.

- 기존 테스트를 분석하고 커버리지 공백을 파악합니다
- 단위 테스트, 통합 테스트, E2E 테스트를 모범 사례에 따라 작성합니다
- 테스트 품질을 검토하고 유지보수성 개선안을 제안합니다
- 테스트는 독립적이고 결정론적이며 잘 문서화된 형태로 작성합니다
- 특별히 요청받지 않는 한 프로덕션 코드는 수정하지 않습니다
 
항상 명확한 테스트 설명을 포함하고 해당 언어와 프레임워크에 맞는 테스팅 패턴을 사용합니다.

구현 플래너 에이전트 — 코드 구현 대신 기술 사양과 구현 계획 문서화에 특화된 에이전트입니다. 읽기·검색·편집 도구만으로 액세스를 제한합니다.

name: implementation-planner
description: 마크다운 형식의 상세한 구현 계획과 기술 명세서를 작성합니다
tools: ["read", "search", "edit"]

당신은 포괄적인 구현 계획 수립에 특화된 기술 기획 전문가입니다.

- 요구사항을 분석하고 실행 가능한 태스크로 분해합니다
- 명확한 단계, 의존성, 타임라인이 포함된 상세 기술 명세서를 작성합니다
- API 설계, 데이터 모델, 시스템 상호작용을 문서화합니다
- 개발팀이 따를 수 있는 구조화된 계획 파일을 마크다운으로 생성합니다
--- 

항상 명확한 헤딩, 태스크 분류, 완료 기준으로 계획을 구성합니다. 테스트, 배포, 잠재적 리스크에 대한 고려사항을 포함합니다. 코드 구현보다 철저한 문서화에 집중합니다.

커스텀 에이전트 호출하는 4가지 방법

에이전트를 만들었다면 네 가지 방식으로 호출할 수 있습니다.

슬래시 명령: 대화형 모드에서 /agent를 입력하면 사용 가능한 에이전트 목록이 나타납니다. 원하는 에이전트를 선택하고 작업 프롬프트를 입력합니다.

명시적 지시: 에이전트 이름을 직접 언급하는 방식입니다.

Copysecurity-auditor 에이전트를 사용해서 /src/app 디렉터리의 모든 파일을 검토해줘

유추 호출: 에이전트 description에 정의된 트리거 조건에 맞는 프롬프트를 입력하면 Copilot이 자동으로 적절한 에이전트를 선택합니다.

Copyseccheck /src/app/validator.go

또는

Copysrc 디렉터리의 모든 TypeScript 파일에서 잠재적 보안 문제를 확인해줘

프로그래밍 방식: CLI 플래그로 에이전트를 지정해 스크립트나 자동화 파이프라인에서 호출합니다.

Copycopilot --agent security-auditor --prompt "Check /src/app/validator.go"

GitHub.com의 클라우드 에이전트 환경에서는 이슈에 Copilot을 할당할 때 드롭다운 메뉴에서 커스텀 에이전트를 선택할 수 있으며, 에이전트가 이슈를 처리하고 PR을 자동으로 생성합니다.

커스텀 에이전트 설정 시 놓치면 안 되는 핵심 팁

description을 트리거 조건 중심으로 작성하세요. 에이전트가 자동으로 호출되려면 description이 Copilot의 유추 엔진이 정확히 읽어낼 수 있는 트리거 조건을 포함해야 합니다. “보안을 점검한다” 보다 “코드 보안 감사 요청이 있을 때, 또는 프롬프트에 ‘seccheck’라는 단어가 포함될 때 호출한다”처럼 구체적인 조건을 명시하는 것이 좋습니다.

tools 속성으로 권한을 최소화하세요. 문서 생성 전용 에이전트라면 ["read", "search", "edit"]처럼 필요한 도구만 허용하는 것이 보안상 안전합니다. 특히 팀 프로젝트에서 여러 사람이 사용하는 에이전트라면 도구 범위를 명확히 제한하는 것이 권장됩니다.

에이전트 파일도 버전 관리하세요. .github/agents/ 폴더의 에이전트 파일은 일반 코드처럼 Git으로 관리됩니다. 팀 전체가 공통 에이전트를 사용하려면 이 파일을 리포지토리에 커밋하고, 팀원 모두가 동일한 에이전트를 활용할 수 있도록 공유합니다. GitHub 커뮤니티의 awesome-copilot 리포지토리에는 다양한 커스텀 에이전트 예시가 공개되어 있으니 참고할 수 있습니다.

결론

GitHub Copilot 커스텀 에이전트는 .agent.md 파일 하나로 만드는 전문화된 AI 협업자입니다. YAML 프런트매터의 name, description, tools 속성과 마크다운 행동 지침만 잘 작성하면, 보안 감사·테스트 작성·구현 기획 등 반복적인 전문 업무를 에이전트에게 완전히 위임할 수 있습니다. 에이전트는 메인 컨텍스트를 오염시키지 않는 독립 서브에이전트로 작동하므로, 크고 복잡한 코드베이스에서도 안정적으로 동작합니다. 오늘 팀에서 가장 반복적으로 요청하는 작업 하나를 골라 첫 번째 커스텀 에이전트로 만들어 보는 것이 가장 빠른 시작점입니다.