당신이 아주 유능한 계약직 직원을 고용했다고 상상해 보세요.

날카롭고, 빠르며, 모든 기술을 알고 있습니다. 당신은 첫날 아침에 그들에게 브리핑을 합니다: "우리는 여기서 테스트 주도 개발 (TDD)을 합니다. 보안은 타협할 수 없는 사항입니다. PR은 300줄 이내로 유지해야 합니다. 모든 데이터베이스 쿼리는 매개변수화 (parameterize) 해야 합니다 — 예외는 없습니다."

그들은 고개를 끄덕입니다. 이해했습니다. 하루는 아주 훌륭하게 지나갑니다.

다음 날 아침, 그들은 그 어떤 것도 기억하지 못한 채 나타납니다.

당신은 다시 브리핑을 합니다. 그들은 다시 이해합니다. 하루는 아주 잘 흘러갑니다.

이 과정이 반복됩니다. 매. 일. 마다.

이것이 바로 설정이 없는 GitHub Copilot의 모습입니다.

아무도 말하지 않는 문제

Copilot은 진정으로 인상적입니다. 하지만 그것은 상태가 없는 (stateless) 방식입니다. 모든 세션은 제로(zero)에서 시작합니다. Copilot은 다음 사항들을 알지 못합니다:

• 당신의 테스트 철학 (TDD? 통합 우선 (integration-first)? 모의 객체 (mocks) 사용 여부?)
• 당신의 보안 규칙 (매개변수화된 쿼리, 코드 내 비밀 정보 금지, 경계에서의 검증)
• 당신의 리뷰 표준 (무엇이 PR을 승인 가능하게 만드는지, 혹은 차단하는지)
• 지금 당장 당신에게 필요한 전문가적 사고방식 (리뷰어? 테스터? 보안 감사관?)

그래서 당신은 매 세션마다 다시 프롬프트를 입력하거나 — 실제로 아무도 그렇게 하지 않죠 — 그 누구의 코드베이스에도 특별히 맞지 않는 일반적인 결과물을 받아들여야 합니다.

더 나은 방법이 있습니다.

해결책: Copilot에게 직원 핸드북을 제공하세요

GitHub Copilot에는 대부분의 사람들이 존재조차 모르는 기능이 있습니다: 만약 당신의 리포지토리(repo) 내 .github/copilot-instructions.md 경로에 파일을 두면, Copilot은 매 세션마다, 영구적으로 그 파일을 자동으로 읽습니다.

프롬프트를 입력할 필요도, 설정 의식을 치를 필요도 없습니다. 그저 당신의 규칙을 알게 될 뿐입니다.

그뿐만이 아닙니다. .github/agents/ 폴더에 전문가 페르소나(persona)를 넣어두면, Copilot Chat에서 단 한 번의 @ 언급으로 그들을 소환할 수 있습니다. 메시지 하나면 Copilot은 5축 코드 리뷰 (5-axis code review)를 수행하는 스태프 엔지니어(staff engineer)가 됩니다. 또 다른 메시지를 보내면 Prove-It 패턴을 사용하여 테스트를 작성하는 QA 엔지니어가 됩니다. 또 다른 메시지를 보내면 당신의 인증 흐름에 대해 STRIDE 분석을 수행하는 보안 감사관이 됩니다.

저는 이 모든 것을 당신을 위해 설정해 주는 템플릿을 만들었습니다. 어떻게 작동하는지 소개합니다.

당신이 얻게 될 것

.github/
  copilot-instructions.md   ← Copilot이 매 세션마다 이를 읽습니다. 당신의 규칙이 자동으로 적용됩니다.
  agents/
...

단축번호로 연결된 세 명의 전문가. 첫 설정 이후에는 설정이 전혀 필요 없습니다.

5분 설정 방법

먼저 필요한 것들

• GitHub 계정
• VS Code
• GitHub Copilot 구독 (Individual, Business, 또는 Enterprise)
• VS Code에 설치된 GitHub Copilot extension
• VS Code에 설치된 GitHub Copilot Chat extension

이것이 전부입니다. CLI 도구도, 수동으로 작성할 설정 파일도 필요 없습니다.

1단계 — 템플릿으로 리포지토리(repo) 생성하기

👉 github.com/panditAbhis/copilot-workflow 로 이동하세요.

초록색 "Use this template" 버튼을 클릭한 후 → **"Create a new repository"**를 선택합니다.

리포지토리 이름을 지정하고, 공개 범위(visibility)를 설정한 뒤, Create repository를 클릭합니다.

이제 당신의 새 리포지토리에는 모든 것이 사전 설정된 .github/ 폴더가 포함되어 있습니다. Copilot이 이를 자동으로 인식하므로 추가 작업은 필요하지 않습니다.

2단계 — 작동 여부 확인하기

VS Code에서 새 리포지토리를 엽니다. Copilot Chat을 엽니다 (Windows/Linux는 Ctrl+Alt+I, Mac은 Cmd+Alt+I).

다음과 같이 질문해 보세요:

What are the coding standards for this project?

당신이 단 하나의 지침도 직접 입력하지 않았음에도, Copilot은 테스트 피라미드 (testing pyramid), 리뷰 표준, 그리고 보안 규칙을 설명해야 합니다. 만약 제대로 작동한다면, 설정이 완료된 것입니다.

작동하지 않나요? VS Code 설정을 열고 github.copilot.chat.codeGeneration.useInstructionFiles가 true로 설정되어 있는지 확인하세요. 기본값이지만 확인해 볼 가치가 있습니다.

3단계 — 세 명의 전문가 만나기

Copilot Chat을 열고 다음을 시도해 보세요:

코드 리뷰어 (The Code Reviewer):

@code-reviewer Review the changes in src/auth/login.ts

구조화된 보고서를 받게 됩니다: 심각한 문제 (Critical issues, 머지 차단), 중요한 문제 (Important issues, 수정 권장), 제안 사항 (Suggestions, 선택 사항). 무엇이 필요한지 정확히 알 수 있도록 라벨이 지정되어 제공됩니다.

테스트 엔지니어 (The Test Engineer):

@test-engineer 버그가 있습니다. 사용자가 만료된 토큰으로 로그인할 수 있습니다. 제가 수정하기 전에 이 버그가 존재함을 증명하는 실패하는 테스트(failing test)를 작성해 주세요.

이것이 바로 **증명 패턴 (Prove-It Pattern)**입니다. 현재의 결함이 있는 코드에서 실패하는 테스트를 작성한 다음, 테스트가 통과할 때까지 코드를 수정하는 방식입니다. 테스트는 버그가 존재했었으며 이제는 사라졌음을 보여주는 증거가 됩니다.

보안 감사관 (The Security Auditor):

@security-auditor 내 파일 업로드 핸들러를 감사해 주세요. OWASP Top 10 범위를 충족하고 STRIDE 위협 분석 (threat analysis)을 수행하고 싶습니다.

결과물은 심각도(Critical/High/Medium/Low)에 따라 분류되며, 모호한 "입력값 검증을 고려하십시오"와 같은 조언이 아니라 개념 증명 (Proof-of-Concept, PoC) 공격 방식과 구체적인 수정 코드(remediation code)를 함께 제공합니다.

코딩 표준이 실제로 다루는 내용

copilot-instructions.md에는 세 가지 영역의 규율이 녹아 있습니다. 요약하면 다음과 같습니다.

테스트 (Testing)

Copilot은 테스트 피라미드 (test pyramid)를 알고 있습니다: 80%의 유닛 테스트 (unit tests, 순수 로직, 데이터베이스 미사용, 각 수 밀리초 소요), 15%의 통합 테스트 (integration tests, 실제 데이터베이스 사용, localhost 전용), 5%의 E2E 테스트 (end-to-end tests, 핵심 사용자 경로만 포함).

Copilot은 코드가 내부적으로 어떻게 작동하는지가 아니라, 코드가 무엇을 하는지를 테스트해야 한다는 점을 알고 있습니다. 메서드 호출 순서를 검증하는 테스트는 동작이 변경되지 않더라도 리팩터링 (refactoring) 시 깨지게 됩니다. 상태 기반 단언 (State-based assertions)은 리팩터링 후에도 유지됩니다.

코드 품질 (Code Quality)

약 100줄 미만의 PR (Pull Request)이 이상적입니다. 1,000줄이 넘어가면 코드를 분할하라고 조언할 것입니다. 리팩터링 PR과 기능 구현 PR은 항상 분리되어 유지됩니다. 죽은 코드 (dead code)나 "나중에 정리하겠다"는 식의 임시 방편 (shims)은 허용되지 않습니다. 추상화 (Abstractions)는 세 번째로 필요할 때까지 작성되지 않습니다.

보안 (Security)

모든 외부 입력은 검증될 때까지 적대적인 것으로 간주됩니다. 데이터베이스 쿼리는 매개변수화 (parameterized)됩니다. 사용자 입력을 SQL에 결합(concatenating)하는 일은 절대 없습니다. 비밀 정보 (Secrets)는 .env 파일에 머물며, 코드에는 절대 포함되지 않습니다. LLM 출력(네, Copilot의 출력조차도)은 신뢰할 수 없는 입력으로 취급되며, eval, SQL, 또는 HTML에 직접 전달되지 않습니다.

나에게 와닿았던 비유

이 설정을 **주방 (kitchen)**이라고 생각해보세요.

Vanilla Copilot은 당신의 레스토랑 요리가 무엇인지, 시그니처 메뉴가 무엇인지, 알레르기 규칙이나 준비 표준(prep standards)이 무엇인지 전혀 모른 채 나타나는 요리사와 같습니다. 당신은 매 서비스마다 모든 것을 설명해야 합니다.

이 템플릿은 **주방 성경 (kitchen bible)**과 같습니다. 코팅되어 벽에 붙어 있으며 영구적입니다. 요리사는 매 교대 근무 시작 시 이를 한 번 읽습니다. 당신은 더 이상 기초적인 사항을 다시 설명할 필요가 없습니다.

세 명의 에이전트(agent)는 당신의 **수셰프 (sous-chefs)**입니다. 주방을 떠나기 전 모든 요리를 맛보는 품질 검사관(quality inspector), 서비스 시작 전 스테이션을 올바르게 설정하는 준비 전문가(prep specialist), 그리고 아무것도 누군가를 아프게 하지 않도록 확인하는 위생 검사관(health inspector)이 그들입니다.

당신은 여전히 헤드 셰프(head chef)입니다. 결정은 당신이 내립니다. 그들은 당신을 더 빠르고 안전하게 만들어 줍니다.

이 시리즈의 다음 단계

이것은 파트 1입니다. 앞으로 다룰 내용은 다음과 같습니다:

파트	배우게 될 내용
1 — 이번 편	설정: 지침 파일 (instructions file) + 세 명의 에이전트 페르소나 (agent personas)
...

템플릿 가져오기

👉 github.com/panditAbhis/copilot-workflow

Use this template을 클릭하세요. 5분이면 끝납니다.

이 내용이 도움이 되었다면, 시리즈의 나머지 부분을 위해 팔로우해 주세요. 그리고 다른 사람들도 찾을 수 있도록 리포지토리(repo)에 ⭐를 남겨주세요.

이 템플릿의 코딩 표준은 Addy Osmani의 agent-skills, Google의 소프트웨어 엔지니어링 (Software Engineering) 관행, 그리고 OWASP 가이드라인에서 유도되었습니다.