각 환경에서 어떤 Copilot 지침 파일이 읽히는지 정리하는 방법 (2026년 가이드)

GitHub는 전체 목록을 공개하며 이를 "다음 목록은 완전한 우선순위를 보여주며, 목록의 상위에 있는 지침이 하위에 있는 지침보다 우선합니다"라고 소개합니다. 그 순서는 다음과 같습니다. 먼저 개인 지침(personal instructions), 그 다음은 리포지토리 맞춤 지침(repository custom instructions)으로, 이는 다시 "적용 가능한 .github/instructions/**/*.instructions.md 파일의 경로별 지침", ".github/copilot-instructions.md 파일의 리포지토리 전역 지침", "에이전트 지침(예: AGENTS.md` 파일)" 순으로 정렬됩니다. 그리고 마지막으로 조직 맞춤 지침(organization custom instructions)이 위치합니다.

이 목록에서 사람들을 놀라게 하는 세 가지가 있습니다.

개인 설정이 모든 것을 이깁니다. 소프트웨어의 대부분의 지침 시스템은 조직을 최상위에 두고 개인을 최하위에 둡니다. Copilot은 그 반대이며, 이는 의도된 설계입니다. 항상 특정 언어로 답변하라는 조직의 지침은 기본값일 뿐 강제 사항이 아니며, 개인이 이를 재정의(override)할 수 있습니다. GitHub는 조직 지침이 "해당 조직으로부터 Copilot 구독을 받는지 여부와 관계없이 조직의 모든 구성원에게 사용된다"고 명시하고 있습니다. 즉, 광범위하게 적용되면서도 여전히 가장 마지막 순위에 위치합니다.

에이전트 파일은 리포지토리 파일보다 아래에 위치합니다. AGENTS.md, CLAUDE.md, GEMINI.md는 .github/instructions/**/*.instructions.md와 .github/copilot-instructions.md 모두의 아래에 나열되어 있습니다. 벤더 중립적인 에이전트 파일로 마이그레이션하면서 기존의 리포지토리 파일을 그대로 남겨둔 팀은 의도치 않게 새 파일의 우선순위를 낮춰버린 셈입니다. 마이그레이션 방향 자체는 고유한 트레이드오프가 있는 실제 작업이며, 저희는 CLAUDE.md를 AGENTS.md로 이동하기 및 이 특정 목적지를 위한 CLAUDE.md를 Copilot으로 이동하기에서 이 문제를 다루었습니다.

아무것도 버려지지 않습니다. 이 문장은 전체 목록을 읽는 방식을 바꾸어 놓습니다. "그러나 관련된 모든 지침 세트가 Copilot에 제공됩니다." 여기서 우선순위는 패자를 걸러내는 필터가 아닙니다. 적용 가능한 모든 세트가 모델에 전달되며, 우선순위는 충돌이 발생했을 때 어떤 것이 이기는지를 설명할 뿐입니다. 따라서 삭제하는 것을 잊어버린 모순된 규칙이 여전히 프롬프트에 남아 주의력을 소모하고, 예상치 못한 문구에서 가끔씩 우선권을 쥐게 됩니다. GitHub의 조언은 다음과 같이 바로 이어집니다. "가능하면 상충되는 지침 세트를 제공하지 않도록 하십시오."

이 모든 것의 밑바탕에는 지원 범위 문제가 깔려 있습니다. 에이전트 지침에 대해 GitHub는 "리포지토리 전역 맞춤 지침과 유사하지만, 현재 모든 Copilot 기능에서 지원되는 것은 아닙니다"라며, "이 지침들은 AGENTS.md, CLAUDE.md 또는 GEMINI.md라는 파일에 지정됩니다"라고 설명합니다. 조직 지침의 경우 지원 범위는 더욱 좁습니다. "조직 맞춤 지침은 현재 GitHub.com의 Copilot Chat, GitHub.com의 Copilot 코드 리뷰, GitHub.com의 Copilot 클라우드 에이전트에서만 지원됩니다."

이 두 가지 참고 사항을 함께 읽으면 실질적인 윤곽이 드러납니다. 어떤 파일이 답변을 제어하는지는 사용 중인 Copilot 환경에 따라 달라지며, 동일한 리포지토리라도 에디터, GitHub.com의 채팅, 풀 리퀘스트 리뷰에서 서로 다르게 동작할 수 있습니다. 이때 어떤 규칙이 로드되었는지 알려주는 메시지는 어디에도 표시되지 않습니다. 이것이 바로 저희가 에이전트가 지침 파일을 조용히 건너뛰는 이유에서 설명한 일반적인 실패 패턴입니다.

한 단계 위에서 규칙을 다시 추가하기. 규칙이 무시될 때 본능적으로 취하는 조치는 단계를 높이는 것입니다. 리포지토리 파일이 작동하지 않으면 조직 설정에 넣는 식입니다. 하지만 공개된 우선순위를 고려하면, 이는 규칙을 우선순위 목록에서 위가 아니라 아래로 이동시키는 결과를 낳습니다. 만약 개인 지침이 이와 상충하고 있다면, 단계를 높이는 것은 모순을 더 악화시킬 뿐입니다.

모든 것을 하나의 파일로 통합하기. 합리적인 방법이며 충돌을 제거해 줍니다. 하지만 이는 경로 범위 지침이 잘 수행하는 유일한 장점을 버리는 일이기도 합니다. .github/instructions/**/*.instructions.md는 일치하는 경로에만 적용되므로, 백엔드 답변에 프론트엔드 컨벤션이 섞이지 않도록 방지할 수 있습니다. 모든 것을 하나의 리포지토리 전역 파일로 축소하면 모든 규칙이 글로벌하게 적용됩니다.

어떤 환경이 무엇을 읽는지 확인하지 않고 이전 파일 삭제하기. 정답을 확실히 알고 있을 때만 안전한 방법입니다. 에이전트 지침은 모든 Copilot 기능에서 지원되지 않는 것으로 문서화되어 있으므로, AGENTS.md를 사용하기 위해 .github/copilot-instructions.md를 제거하면 일부 환경에는 아무런 지침도 남지 않게 될 수 있으며, 시스템은 이를 경고하지 않습니다.

잘못된 곳에서 테스트하기. 사람들은 에디터에서 리포지토리 지침을 검증하고 모든 곳에서 작동할 것이라 결론짓거나, GitHub.com의 채팅에서 테스트하고 그 반대로 결론을 내립니다. 환경별 지원 여부가 다르므로, 하나의 테스트는 오직 하나의 환경만을 증명할 뿐입니다.

풀 리퀘스트가 머지된 상태를 읽는다고 가정하기. 그렇지 않습니다. GitHub는 다음과 같이 명시하고 있습니다. "풀 리퀘스트를 리뷰할 때 Copilot은 베이스 브랜치(base branch)가 아닌 헤드 브랜치(head branch, 변경 사항이 있는 브랜치)에서 리포지토리 맞춤 지침, 에이전트 지침 및 에이전트 스킬을 읽습니다." 이로 인한 장점은 동일한 노트에 명시되어 있습니다. "따라서 동일한 풀 리퀘스트 내에서 지침 변경 사항을 테스트할 수 있습니다." 반대로 단점은 거울처럼 명확합니다. main 브랜치에서 멀어진 브랜치는 자체의 오래된 규칙을 기준으로 스스로를 리뷰하게 됩니다.

지침 파일을 메모리 레이어로 취급하기. 지침 파일은 다시 읽히는 설정 파일일 뿐, 누적되는 기록이 아닙니다. 영구적인 메모리 영역을 설정하는 것은 별도의 작업이며, 이는 VS Code에서 Copilot 메모리 설정하기에서 다루고 있습니다.

목표는 단 하나의 정답 파일을 고르는 것이 아닙니다. 특정 답변을 어떤 파일이 제어하는지 5초 만에 대답할 수 있도록 만드는 것입니다.

1단계: 우선순위를 적어두고, 실제로 어떤 파일이 있는지 확인하기

먼저 리포지토리에 존재하는 것들을 나열해 보세요. 경로 범위 지침 디렉터리, 리포지토리 전역 파일, 에이전트 파일 또는 이들의 조합이 있을 것입니다. 그런 다음 그 옆에 개인 지침을 두십시오. 공개된 우선순위에서 개인 지침이 이 세 가지 모두보다 우위에 있기 때문입니다.

이 단계에서 흔히 발견되는 것은 아무도 추가한 기억이 없는 파일입니다. 적용 가능한 모든 세트가 필터링되지 않고 Copilot에 제공되기 때문에, 방치된 파일도 비활성화 상태가 아닙니다. 여전히 프롬프트에 포함되어 작동하고 있습니다. 유지 관리하고 있는 파일을 튜닝하기 전에, 관리하지 않는 파일부터 삭제하십시오.

2단계: 파일 단위가 아닌 규칙 단위로 범위 결정하기

GitHub의 자체 가이드도 범위에 관한 것입니다. 맞춤 지침은 "짧고 독립적인 문장일 때 가장 효과적"이며, "개인, 리포지토리 또는 조직 수준 중 어디에 지침을 추가할지 선택할 때 해당 지침이 적용되기를 원하는 범위를 고려해야 합니다."

이것이 올바른 결정 기준입니다. 선호하는 언어 설정은 개인적인 것입니다. 프레임워크 컨벤션은 리포지토리 전역에 해당합니다. 단 하나의 디렉터리에만 적용되는 규칙은 경로 범위 파일에 속하며, 이는 통합 시 포기해야 하는 유일한 기능입니다. 모든 구성원이 기본적으로 적용받되 재정의할 수 있는 정책은 조직 수준에 해당합니다. 이는 가장 마지막 순위에 위치하며 GitHub.com의 세 가지 환경에서만 지원된다는 점을 인지하고 작성할 가치가 있습니다.

3단계: 환경별로 검증하고, 리뷰 중인 브랜치에서 검증하기

팀이 실제로 사용하는 각 환경에서 동일한 프롬프트를 실행하고 규칙이 적용되는지 확인해 보세요. 반복되는 논쟁을 종식시킬 수 있는 10분짜리 작업입니다.

풀 리퀘스트의 경우 헤드 브랜치 규칙을 기억하십시오. 지침 파일을 변경하고 리뷰에 반영되기를 원한다면, 리뷰 중인 브랜치에서 변경해야 합니다. 장기 실행 브랜치에서 지난달 모두가 합의한 규칙을 무시한 채 리뷰가 생성되고 있다면, 해당 규칙이 그 브랜치에 반영되었는지 확인해 보세요. 리포지토리 전반에 걸쳐 상충되는 레이어가 존재하는 것은 그 자체로 유지 관리의 골칫거리이며, 저희는 상충되는 CLAUDE.md 레이어 조정하기에서 이 문제를 다루었습니다.

지침 파일은 "어떻게 행동해야 하는가"에 대한 답을 제공합니다. 하지만 사람들이 계속해서 그 안에 저장하려고 하는 "우리가 무엇을 왜 결정했는가"를 담기에는 적합하지 않은 공간입니다. MemoryLake는 이러한 결정 사항들을 의도적으로 기록하는 저장소로, 특정 도구의 설정과 분리되어 있으며 연결된 모든 어시스턴트에서 읽을 수 있습니다. 여러분은 자신의 언어로 직접 항목을 작성합니다. GitHub 시스템이나 다른 벤더의 저장소에서 데이터를 읽거나, 쓰거나, 삭제하지 않으므로 리포지토리 파일과 Copilot 설정은 전적으로 자체 제어 하에 유지됩니다.

1단계: API 키 생성하기

대시보드에서 키를 생성합니다. 이 키를 통해 Copilot, 터미널 에이전트, 채팅 어시스턴트가 각각 자체 파일을 가질 필요 없이 동일한 사실 집합에 접근할 수 있게 됩니다.

2단계: 첫 번째 메모리 업로드하기

규칙 뒤에 숨겨진 결정 사항부터 시작해 보세요. 컨벤션이 존재하는 이유, 그것이 무엇을 대체했는지, 어떤 접근 방식이 어떤 근거로 배제되었는지 등을 기록합니다. 지침 파일은 규칙을 전달할 뿐, 그 이유를 전달하는 경우는 드뭅니다. 하지만 그 이유야말로 다음 사람이 규칙을 뒤집는 것을 방지하는 핵심 요소입니다.

3단계: AI 및 에이전트 연결하기

도구들이 규칙 파일에서 유추하는 대신 세션 시작 시 해당 사실들을 로드할 수 있도록 레이어를 지정해 줍니다. 그런 다음 유일하게 검증할 수 있는 방법으로 테스트해 보세요. 다른 어시스턴트에게 이전 결정 사항 중 하나를 다시 물어보는 것입니다. 답변을 얻는다면, 여러분의 의사 결정 논리는 더 이상 특정 벤더의 파일 형식에 종속되지 않게 된 것입니다.

첫 번째 변화는 우선순위에 대한 논쟁이 끝난다는 점입니다. 순서는 공개되어 있고, 개인 설정이 조직 설정을 앞서며, 순서와 상관없이 모든 세트가 제공됩니다. 팀이 이 목록을 함께 읽고 나면 대부분의 논쟁은 간단한 정리 작업으로 전환됩니다.

두 번째는 사람들이 실제로 던지는 질문이 지원 범위로 바뀐다는 점입니다. "어떤 파일이 이기는가"는 "여기서 어떤 파일이 읽히기나 하는가"보다 훨씬 덜 중요하며, 환경별 지원 참고 사항에서 예상치 못한 사실들을 발견하게 됩니다.

세 번째는 방치된 파일이 더 이상 무해하지 않다는 점입니다. 적용 가능한 모든 세트가 모델에 도달하기 때문에, 오래된 파일도 활발히 작동하는 참여자가 됩니다. 삭제를 단순한 청소가 아닌 유지 관리 작업으로 취급하면 행동이 즉각적으로 달라집니다.

네 번째는 풀 리퀘스트 리뷰를 예측할 수 있게 된다는 점입니다. 헤드 브랜치에서 지침을 읽는 것은 합리적인 설계입니다. 동일한 풀 리퀘스트 내에서 규칙 변경을 테스트할 수 있기 때문입니다. 이는 오직 그 사실을 모를 때만 함정이 됩니다.

범위당 하나의 파일만 유지하고 나머지는 삭제하세요. 디렉터리 규칙은 경로 범위 파일로, 프로젝트 규칙은 리포지토리 전역 파일로, 다른 도구에 필요한 경우 에이전트 파일로, 자신을 위해서는 개인 설정을 사용하세요.

짧고 독립적인 문장으로 작성하세요. GitHub의 자체 지침이기도 하며, 여러 세트가 결합될 때 더욱 중요해집니다.

개인 지침이 우선 적용될 것을 예상하세요. 팀 규칙이 계속 무시된다면 리포지토리 파일을 다시 쓰기 전에 누군가의 개인 설정과 충돌하는지 확인해 보세요.

각 환경을 개별적으로 검증하세요. 에이전트 지침은 모든 Copilot 기능에서 지원되지 않는 것으로 문서화되어 있으며, 조직 지침은 GitHub.com의 세 가지 환경에서만 지원됩니다.

리뷰 중인 브랜치에서 지침 파일을 변경하세요. 풀 리퀘스트 리뷰는 베이스 브랜치가 아닌 헤드 브랜치에서 지침을 읽습니다.

의사 결정 배경은 다른 곳에 보관하세요. 자체 이력까지 담고 있는 규칙 파일은 더 이상 짧게 유지될 수 없으며, 짧게 유지하는 것이야말로 규칙이 제대로 작동하게 만드는 비결입니다.

GitHub는 Copilot 지침에 대한 완전한 우선순위를 공개하고 있으며, 그 구조를 알아둘 가치가 있습니다. 개인 지침이 가장 먼저이고, 그 다음은 경로 범위 리포지토리 지침, 리포지토리 전역 파일, AGENTS.md와 같은 에이전트 파일 순이며, 조직 지침이 마지막입니다. 적용 가능한 모든 세트가 여전히 Copilot에 제공되므로, 우선순위는 패자를 제거하는 것이 아니라 충돌을 해결하는 역할을 합니다.

더 많은 오후 시간을 허비하게 만드는 부분은 순서보다는 지원 범위입니다. 에이전트 지침은 "현재 모든 Copilot 기능에서 지원되는 것은 아니며", 조직 지침은 GitHub.com의 세 가지 환경에서만 지원되는 것으로 문서화되어 있고, 풀 리퀘스트 리뷰는 헤드 브랜치에서 이 파일들을 읽습니다. 규칙이 완벽하게 작성되고 올바른 위치에 있더라도, 테스트한 환경에서 단순히 로드되지 않았을 수 있습니다.

이 중 어느 것도 결함이 아니며, GitHub는 이 모든 것을 공개적으로 문서화하고 있습니다. 실질적인 해결책은 더 적은 수의 파일을 유지하고, 각 규칙의 범위를 의도적으로 결정하며, 팀이 사용하는 각 환경에서 검증하고, 규칙 뒤에 숨겨진 의사 결정 배경은 설정 파일이 아닌 다른 곳에 보관하는 것입니다.