GitHub Copilot와 작업하기: Custom Instructions & Agents

Source: Dev.to

저는 최근 GitHub Copilot에서 Custom Instructions와 Custom Agents를 탐색했습니다. 처음에는 이 기능들이 간단해 보이지만, 실제 코드베이스에서 Copilot의 동작 방식을 근본적으로 바꾸며—특히 의도적으로 사용할 때 그렇습니다.

이 가이드는 현재 제 이해와 실용적인 인사이트를 반영하며, 전적으로 GitHub Copilot Chat in Visual Studio Code를 기반으로 합니다(별도로 명시되지 않은 한).

용어 설명

맞춤 지시 vs. 맞춤 에이전트 (멘탈 모델)

• 맞춤 지시는 지속적인 프로젝트 컨텍스트를 제공합니다.
• 맞춤 에이전트는 특정 채팅 상호작용을 위한 전문화된 행동을 제공합니다.

지시를 프로젝트의 규칙서로, 맞춤 에이전트를 특정 리뷰어처럼 의도적으로 호출한다고 생각하세요.

맞춤 지시사항

1. 저장소 전체 지시사항

다음 위치에 파일을 생성합니다:

.github/copilot-instructions.md

이 파일은:

• 저장소 전체에 적용됩니다.
• Copilot의 지속적인 프로젝트 컨텍스트 역할을 합니다.
• 공유 규칙집 역할을 하며(강제 메커니즘은 아님)
• VS Code는 코드베이스를 분석하여 이 파일을 자동으로 생성할 수 있습니다. 이를 시작점으로 삼고, 권위적인 사양으로 여기지 마세요 — 인간 검토가 여전히 필요합니다.

2. 경로‑특정 지시사항

다음과 같이 적용‑대상 glob을 사용해 범위가 지정된 지시 파일을 만들 수 있습니다:

.github/instructions/**/*.instructions.md

이러한 지시사항은 해당 경로와 일치하는 파일이 컨텍스트에 있을 때만 로드되므로, 프런트엔드 규칙이 백엔드 코드에 누출되지 않고 그 반대도 마찬가지입니다.

예시

• .github/instructions/csharp-coding-standards.instructions.md → C# 백엔드 파일
• .github/instructions/typescript-coding-standards.instructions.md → TypeScript 프런트엔드 파일

저장소‑전체이든 경로‑특정이든 모든 지시사항은 제약이 아닌 가이드입니다.

예시: “TypeScript에서 any를 절대 사용하지 마세요.”
Copilot은 보통 any 사용을 피하지만, 타입이 모호하거나 간결성을 위해 삽입할 수 있습니다. 강제 적용을 위해서는 인간 검토나 맞춤 에이전트가 필요합니다.

지시 파일에 포함할 내용

코드만으로는 Copilot이 추론할 수 없는 정보만 포함하세요:

• 기술 스택 선택 – 예: “우리는 스타일링에 Tailwind CSS를, 테스트에 Vitest를 사용합니다.”
• 명명 규칙 – 예: “인터페이스는 항상 I 접두사를 붙입니다 (예: IUser).”
• 엄격한 제한 – 예: “TypeScript에서 any를 절대 사용하지 마세요.”
• 프로젝트 컨텍스트 – 예: “이 프로젝트는 레거시 모놀리식이며, 새로운 기능보다 호환성을 우선시합니다.”
• 컴파일러, 린터, CI에서 이미 강제하는 규칙은 중복해서 적지 마세요.

Awesome Copilot 저장소

Awesome Copilot 저장소에는 커뮤니티가 제공한 프롬프트, 지시 파일, 에이전트, 템플릿이 많이 있습니다.

• 프롬프트 예시: suggest-awesome-github-7_prompt.md – VS Code Copilot Chat에 붙여넣어 저장소와 관련된 AI‑추천 항목을 얻을 수 있습니다.
• 에이전트 프롬프트 예시: github-prompts/suggest-awesome-github-copilot-agents.prompt.md – 어떤 에이전트 프로필이 유용할지 제안합니다.

개인 및 조직 지시사항

GitHub Copilot은 다음도 지원합니다:

• 개인 지시사항
• 조직 지시사항

이들은 이제 VS Code와 Settings Sync를 통해 동기화되므로, GitHub.com에 정의한 규칙이 IDE에서도 적용됩니다.

지시 우선순위

여러 출처가 존재할 경우, Copilot은 이를 결합하고 일반적으로 다음 우선순위를 따릅니다(위에 있을수록 우선순위 높음):

1. 개인/사용자 지시사항
2. 저장소 지시사항 (.github/copilot-instructions.md)
3. 조직 지시사항

충돌 해결은 확률적으로 이루어지며, 동작이 완전히 결정적인 것은 아닙니다.

지시 파일 전략 (지시 과다 방지)

하나의 거대한 파일 대신 도메인 및 기술별로 지시를 나누세요:

.github/
│
├─ copilot-instructions.md          # 전역, 절대 양보할 수 없는 항목
└─ instructions/
   ├─ frontend.instructions.md
   ├─ backend.instructions.md
   ├─ security-iam.instructions.md
   └─ dotnet-framework-legacy.instructions.md

전역 플레이북 (.github/copilot-instructions.md)

절대 양보할 수 없는 항목만 포함합니다:

• 아키텍처: 상속보다 컴포지션을 선호합니다. 공개 API에는 제로 트러스트를 적용합니다.
• 보안: PII, 원시 토큰, 비밀 정보를 절대 로그에 남기지 않습니다.
• 성능: O(n) 이상이 아닌 알고리즘을 우선 사용하고, async I/O는 명시적으로 표시합니다.
• 문서화: 공개 계약과 복잡한 로직에만 문서를 작성합니다.

이 파일은 작고 안정적이어야 합니다.

범위별 지시 예시

• 프런트엔드: 프레임워크 관례, 반응성 패턴, 타입 규칙 등.
• 백엔드: 명명 규칙, 오류 처리, 포맷팅 등.
• IAM: 인증/인가 규칙.
• 레거시 프레임워크: 제약 내에서 안전한 현대화.

Custom Agents

Custom agents shift Copilot from:

“AI that writes code” → “AI that applies a specific engineering lens”

정의 위치

• 워크스페이스 수준: .github/agents (특정 리포지토리 전용)
• 사용자 프로필 수준: 워크스페이스 간에 공유

Custom agents는 VS Code Agent 모드보다 더 강력한 것이 아니라 더 집중되고 의견이 명확한 도구입니다.

Custom Agents의 실용적인 사용

(원본 가이드에 내용이 계속됩니다 – 필요한 섹션과 예시는 동일하게 유지하십시오.)

Source: …

에이전트

가벼운 팀 패턴

• VS Code Agent 모드 → 구현 전용
• 커스텀 에이전트 → 팀 관례에 따라 필요한 리뷰어 지정 (Copilot에서 강제하지 않음)

커스텀 에이전트의 출력은 PR 리뷰 피드백처럼 다루고, 제안으로 보지 마세요.

예시 워크플로

권장: 저장소 전체 및 경로별 지시사항을 설정하여 결과를 개선합니다.

1. VS Code Copilot에서 @plan 모드를 사용해 기능 또는 변경 사항을 개요합니다.
2. VS Code Agent 모드를 이용해 기능/동작을 구현합니다.
3. @dotnet-security-reviewer 실행 → 누락된 인증 정책을 표시합니다.
4. 문제를 수정합니다.
5. @typescript-api-contract-reviewer 실행 → nullable 불일치를 표시합니다.
6. 문제를 수정합니다.

Why Not Bake All of This Into VS Code Agent Mode?

• Goals conflict (speed vs. caution)
• Rules dilute as constraints grow
• Context matters—most checks aren’t always relevant
• Humans bypass friction when slowed down
• LLMs average; they don’t arbitrate
• Completion bias beats prevention

Silent violations are worse than explicit reviews.

VS Code Agent mode builds. Custom agents judge.
That separation is the difference between AI that helps and AI you can trust.

최종 메모

• 개인 및 조직 지시가 이제 대부분의 사용자에게 VS Code와 동기화됩니다.
• 맞춤형 에이전트를 도구와 연결할 수 있으며, 이는 Copilot 기능 가용성 및 작업공간 권한에 따라 달라집니다.

GitHub Copilot Chat은 오픈 소스입니다:

• VS Code Copilot Chat

내장 에이전트(예: Plan 모드)는 여기에서 확인할 수 있습니다:

• Plan‑agent.md

리소스

• VS Code에서 사용자 지정 에이전트 만들기
• Awesome Copilot