AGENTS.md, CLAUDE.md 및 홈 폴더 전반에서 Copilot CLI 지침을 연결하는 방법 (2026년 가이드)

목록부터 시작해 보겠습니다. CLI용 맞춤형 지침에 대한 GitHub 페이지에는 8가지 종류의 위치가 명시되어 있습니다. 사용자 수준에서는 "$HOME/.copilot/copilot-instructions.md"가 "저장소 전반에 적용되는 사용자 수준 지침"을 보관하고, $HOME/.copilot/instructions/**/*.instructions.md가 "모듈형 사용자 수준 지침"을 보관합니다. 저장소 내에는 "저장소 전체 지침"을 위한 .github/copilot-instructions.md, 모듈형 .github/instructions/**/*.instructions.md 파일, 그리고 세 가지 에이전트 지침 파일인 AGENTS.md, CLAUDE.md, GEMINI.md가 있습니다. CLAUDE.md에 대해 표에서는 "Copilot CLI는 .claude/CLAUDE.md도 사용합니다"라고 덧붙이고 있습니다.

다음으로 검색 위치입니다. "아래 표에 명시되지 않은 한, Copilot CLI는 표준 위치(저장소 루트, 현재 작업 디렉터리, 이들 사이의 중간 디렉터리, 작업 중인 파일의 경로에 중첩된 모든 디렉터리)에서 저장소 및 에이전트 지침 파일을 탐색합니다." 기억해 둘 만한 한 가지 예외는 모듈형 저장소 지침이 "표준 위치에서 탐색되지만 중간 디렉터리에서는 탐색되지 않는다"는 점입니다.

그 다음은 결합 방식입니다. 가장 중요한 문장은 다음과 같습니다: "적용 가능한 사용자 수준 및 저장소 지침 파일이 여러 개 존재하는 경우, Copilot CLI는 해당 지침들을 결합합니다. 동일한 사용자 수준 copilot-instructions.md, 저장소 전체 지침, 에이전트 지침의 중복 복사본은 제거하지만, 이 파일들 간의 일반적인 우선순위는 정의하지 않습니다. 충돌하는 지침은 피하십시오."

이는 많은 사람들이 Copilot 지침에 대해 생각하는 방식과 다릅니다. 에디터 및 github.com 문서는 개인, 경로 특정, 저장소 전체, 에이전트 및 조직 지침 간의 순위를 설명하며, 이는 which Copilot instruction file wins, and where에 명시되어 있습니다. 반면 CLI 페이지는 중복 제거를 포함한 결합과 충돌을 피하라는 명시적인 지침을 설명합니다. 만약 AGENTS.md가 한 가지를 말하고 CLAUDE.md가 다른 것을 말한다면, CLI 문서는 어느 것을 따를지 알려주지 않습니다. 대신 그런 상황을 만들지 말라고 경고합니다.

홈 폴더에 개인 AGENTS.md 두기. CLI 문서에 명시된 사용자 수준 위치는 copilot-instructions.md와 $HOME/.copilot 내부의 모듈형 지침 폴더입니다. 그 옆에 놓인 AGENTS.md는 문서화된 목록에 없습니다. 추가 AGENTS.md 파일을 위한 문서화된 경로는 다르며, 이는 2단계에서 다룹니다.

세션 도중에 지침 파일을 편집하고 변경 사항이 반영되기를 기대하기. GitHub 페이지에 따르면 "맞춤형 지침 파일을 변경하더라도 활성 CLI 세션에서 즉시 사용할 수는 없습니다." 세션을 종료하고 다시 시작하거나 새 세션을 시작해야 합니다. 이는 편집된 AGENTS.md가 무시되는 것처럼 보이는 가장 흔한 이유입니다.

홈 폴더에서 공유 파일을 참조하기. CLI는 .github/copilot-instructions.md, AGENTS.md, CLAUDE.md에서 @ 참조를 지원하지만, "절대 경로 및 ~/로 시작하는 경로는 로드되지 않습니다." ~/notes/conventions.md를 가리키는 행은 아무런 작동도 하지 않습니다.

GEMINI.md 또는 모듈형 파일에서 @ 참조 사용하기. "GEMINI.md 또는 *.instructions.md 파일에서는 파일 참조가 확장되지 않습니다." 참조는 일반 텍스트로 그대로 남습니다.

모든 패키지에 모듈형 지침 폴더 두기. 모노레포에서는 각 수준에 자체 .github/instructions 폴더를 부여하는 것이 자연스럽게 느껴집니다. 하지만 패키지 내부에서 세션을 시작하면 저장소 루트와 해당 패키지 사이의 폴더는 중간 디렉터리가 됩니다. GitHub 표에 따르면 모듈형 저장소 지침은 표준 위치에서 탐색되지만 "중간 디렉터리에서는 탐색되지 않는다"고 되어 있으며, 이는 AGENTS.md에 대한 규칙보다 더 좁은 범위입니다. 이러한 중간 폴더 중 하나에 있는 모듈형 폴더는 건너뛰는 반면, 동일한 폴더에 있는 AGENTS.md는 감지됩니다.

세 개의 에이전트 파일을 수동으로 동기화하며 잘 작동하기를 바라기. 서로 다른 도구가 서로 다른 파일을 읽기 때문에 많은 저장소에 AGENTS.md, CLAUDE.md, GEMINI.md가 함께 존재합니다. CLI는 이 세 가지를 모두 읽습니다. 완전히 동일한 복사본은 제거되지만, 약간 다른 복사본은 모두 포함됩니다. 이로 인한 불일치 문제는 reconciling conflicting CLAUDE.md layers에서 설명한 것과 동일합니다.

목표는 모든 사실이 단 한 번만 나타나고, 모든 파일이 문서화된 위치에 있으며, 세션이 실제로 로드한 내용을 확인할 수 있는 지침 세트를 구성하는 것입니다.

1단계: 이번 세션에서 CLI가 탐색한 내용 확인하기

GitHub은 정확히 이를 위한 명령어를 문서화해 두었습니다: "현재 세션에서 탐색된 지침 파일을 보고 개별 파일을 활성화하거나 비활성화하려면 /instructions 명령어를 사용하십시오."

평소 작업하는 디렉터리에서 이 명령어를 실행하고 목록을 기록해 두세요. 그런 다음 하위 디렉터리에서 다시 실행해 보세요. 탐색 범위에는 저장소 루트, 작업 디렉터리 및 그 사이의 디렉터리가 포함되므로, 트리 깊은 곳에서 시작된 세션은 루트 세션이 감지하지 못하는 파일을 가져올 수 있습니다. 경로 특정 파일은 또 다른 변수를 추가합니다: 이 파일들은 "해당 applyTo 값이 Copilot CLI가 작업 중인 파일과 일치할 때만 포함됩니다."

목록을 예상했던 것과 비교해 보세요. 보통 세 가지가 나타납니다: 아무도 기억하지 못하는 CLAUDE.md 또는 .claude/CLAUDE.md, 하위 폴더에 중첩된 AGENTS.md, 그리고 이전에 누군가 비활성화한 파일입니다. GitHub은 비활성화된 파일이 제외된다는 점을 명확히 하고 있습니다: "/instructions를 사용하여 비활성화한 지침 파일은 포함되지 않습니다."

세션 중에 이 파일들을 편집했다면, 목록은 세션 시작 시점을 반영한다는 점을 기억하세요. 결론을 내리기 전에 세션을 종료하고 다시 시작하거나 새 세션을 시작해야 합니다.

2단계: 각 사실에 하나의 홈을 지정하고, 개인 파일을 올바르게 배치하기

이제 각 파일의 용도를 결정합니다. 여러 에이전트와 함께 사용하는 저장소에 적합한 구성은 다음과 같습니다:

AGENTS.md는 빌드 및 테스트 명령어, 컨벤션, 제약 조건 등 도구에 구애받지 않는 공유된 사실을 보관합니다. 이는 Copilot CLI를 포함하여 모든 에이전트가 읽는 파일입니다.

.github/copilot-instructions.md는 Copilot에만 해당하는 특정 내용이 있을 경우 이를 보관합니다.

CLAUDE.md 및 GEMINI.md는 해당 도구에만 해당하는 내용을 보관하거나 AGENTS.md를 가리키도록 설정합니다. @ 참조는 CLAUDE.md에서는 확장되지만 "GEMINI.md에서는 확장되지 않는다"는 점을 기억하세요. 따라서 포인터 패턴은 한쪽에서만 작동합니다. Claude Code가 동일한 파일 쌍을 처리하는 방식은 Claude Code's AGENTS.md default에서 다룹니다.

홈을 제외한 모든 곳에서 중복된 사실을 삭제하세요. CLI는 완전히 동일한 복사본은 제거하지만, 거의 동일한 복사본은 모순을 일으키는 원인이 됩니다.

개인 지침의 경우, 문서화된 사용자 수준 파일인 $HOME/.copilot/copilot-instructions.md 또는 $HOME/.copilot/instructions/ 아래의 모듈형 파일을 사용하세요. 모든 저장소에서 참조하려는 개인 AGENTS.md를 유지하고 싶다면, GitHub은 추가 디렉터리를 위한 변수를 제공합니다: "COPILOT_CUSTOM_INSTRUCTIONS_DIRS에 나열된 디렉터리"는 "추가 AGENTS.md 및 *.instructions.md 파일"을 제공합니다. "여러 디렉터리는 쉼표로 구분하십시오." 개인 AGENTS.md를 전용 디렉터리에 넣고 해당 디렉터리를 나열하세요.

기본값이 아닌 Copilot 홈을 사용하는 경우, "COPILOT_HOME 환경 변수를 설정하면 Copilot CLI는 두 사용자 수준 지침 위치 모두에 대해 $HOME/.copilot 대신 해당 디렉터리를 사용합니다"라는 점에 유의하세요.

3단계: 새 세션을 시작하고 결과 확인하기

종료 후 새 세션을 시작하고 instructions 명령어를 다시 실행합니다. 이제 목록이 계획과 일치해야 합니다: 하나의 공유 에이전트 파일, 문서화된 위치의 개인 지침, 그리고 의도하지 않은 파일은 없어야 합니다.

그 다음 동작을 테스트합니다. 이제 정확히 하나의 파일에만 존재하는 사실에 의존하는 질문을 CLI에 던져보세요. 답변이 맞다면 연결이 잘 된 것입니다. 그렇지 않다면 좁은 applyTo 패턴을 가진 경로 특정 파일이 관여하고 있는지 확인하세요. 이러한 파일은 일치하는 파일이 작동 중일 때만 적용되기 때문입니다.

실제로 가장 자주 작업하는 하위 디렉터리에서 전체 확인 과정을 반복해 볼 가치가 있습니다. 패키지 폴더에 AGENTS.md가 중첩된 모노레포는 해당 패키지 내부에서 시작된 세션에 루트에서 시작된 세션과 다른 지침 세트를 제공하며, 탐색 규칙에 따르면 둘 다 올바른 동작입니다. 자신이 어느 세션에 있는지 아는 것이 "어제는 규칙을 따랐는데"라는 보고의 대부분을 설명해 줍니다.

누군가 새로운 에이전트의 지침 파일을 추가할 때마다 이 확인 과정을 반복하세요. 저장소에는 이러한 파일들이 조용히 쌓이게 되며, CLI는 요청하지 않아도 새로운 파일을 모두 읽을 것입니다.

2단계의 분류 작업을 거치면 어떤 에이전트가 읽든 상관없이 프로젝트에 유효한 짧은 사실 목록이 만들어집니다. MemoryLake는 특정 도구가 올해 어떤 파일 이름을 읽는지에 의존하지 않고 이 목록을 보관할 수 있는 공간입니다.

사용자는 자신의 언어로 직접 항목을 작성합니다. 사용자의 .copilot 폴더, 저장소의 지침 파일 또는 다른 벤더의 저장소에서 데이터를 읽거나 쓰거나 삭제하지 않습니다.

1단계: API 키 생성하기

로그인한 후 대시보드에서 키를 생성합니다. 이 키는 에이전트가 AGENTS.md, CLAUDE.md를 읽든 혹은 둘 다 읽지 않든 상관없이 사용자가 작성한 항목을 읽을 수 있도록 해줍니다.

2단계: 첫 번째 기억 업로드하기

2단계의 공유된 사실들을 각 제약 조건이 존재하는 이유와 함께 항목당 하나씩 추가합니다. 그 이유는 다음 사람이 해당 규칙이 여전히 유효한지 판단할 수 있도록 돕습니다.

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

에이전트가 워크스페이스를 가리키도록 설정합니다. 그러면 동일한 사실들을 CLI, 에디터, 그리고 이러한 지침 파일을 전혀 읽지 않는 도구에서도 사용할 수 있게 됩니다.

첫 번째 차이점은 "AGENTS.md를 읽지 않는 문제"를 진단할 수 있게 된다는 것입니다. 대부분의 경우는 세션 도중에 파일이 편집되었거나, 문서화된 위치를 벗어났거나, 비활성화된 경우 중 하나로 밝혀집니다. instructions 명령어가 그 원인을 보여줍니다.

두 번째는 충돌이 소리 없이 묻히지 않는다는 점입니다. CLI 문서에는 "일반적인 우선순위가 정의되어 있지 않기" 때문에, 두 파일 간의 모순은 찾아볼 수 있는 규칙으로 해결되지 않습니다. 각 사실을 한 곳에만 보관하면 이러한 의문 자체가 사라집니다.

세 번째는 개인 지침과 팀 지침이 깔끔하게 분리된다는 점입니다. 개인적인 선호 사항은 홈 폴더나 나열된 디렉터리로 가고, 팀의 사실들은 저장소로 갑니다. 이는 저장소 범위의 기억과 개인 지침이 서로 다른 역할을 수행하는 setting up Copilot memory in VS Code의 배경이 되는 분리 방식이기도 합니다.

네 번째는 컨텍스트가 가볍게 유지된다는 점입니다. CLI가 탐색하는 모든 파일은 작업의 기반이 되는 내용으로 결합됩니다. 파일 수가 적고 명확할수록 반복이 줄어들며, 이는 how Copilot assembles context per request에서 다루는 우려 사항과도 일치합니다.

동작을 디버깅하기 전에 instructions 명령어를 실행하세요. 현재 세션에서 탐색된 파일을 보여주며, 이것이 유일하게 중요한 목록입니다.

편집 후에는 재시작하세요. 지침 변경 사항은 세션을 재개하거나 새 세션을 시작할 때 적용됩니다.

각 사실에 대해 하나의 홈만 유지하세요. 완전히 동일한 복사본은 제거되지만, 거의 동일한 복사본은 모두 포함되어 서로 모순될 수 있습니다.

문서화된 사용자 수준 위치를 사용하세요. $HOME/.copilot/copilot-instructions.md, 모듈형 지침 폴더, 또는 개인 AGENTS.md 파일을 위한 COPILOT_CUSTOM_INSTRUCTIONS_DIRS에 나열된 디렉터리를 사용하세요.

홈 폴더 참조를 피하세요. ~/로 시작하는 경로는 로드되지 않으며, GEMINI.md 또는 모듈형 파일에서는 참조가 확장되지 않습니다.

새로운 에이전트 파일을 Copilot 컨텍스트의 변경으로 취급하세요. 다른 도구를 위해 추가된 CLAUDE.md도 CLI가 읽습니다. 도구 간에 지침을 이동하는 경우, migrating CLAUDE.md to Copilot에서 매핑을 다루며, why Copilot forgets codebase context에서는 지침 파일에 담을 수 없는 내용을 다룹니다.

Copilot CLI의 지침 처리 방식은 매우 관대합니다. 자체 파일, 다른 에이전트의 파일, 개인 파일 및 사용자가 나열한 모든 디렉터리를 저장소 루트부터 편집 중인 파일에 이르기까지 모두 읽습니다. GitHub은 이 모든 것을 명확하게 문서화하고 있습니다.

마찬가지로 명확하게 문서화된 점은 CLI가 순위를 매기기보다는 결합한다는 것입니다. 즉, "이 파일들 간의 일반적인 우선순위를 정의하지 않으며", 충돌을 피할 것을 요구합니다. 이는 일관성을 유지할 책임이 파일을 어떻게 구성하느냐에 달려 있음을 의미합니다.

세션이 탐색한 내용을 확인하고, 각 사실에 하나의 홈을 지정하고, CLI가 검색하는 위치에 개인 파일을 배치하고, 편집 후에는 재시작하세요. 파일 이름 규칙보다 더 오래 지속될 수 있는 곳에 공유된 사실들을 보관하면, 저장소에 다음 에이전트를 추가할 때 이전 에이전트의 설정을 다시 정리할 필요가 없어집니다.