컨텍스트 손실 없이 CLAUDE.md를 GitHub Copilot으로 마이그레이션하는 방법 (2026)

양사 공식 문서를 바탕으로 분석한 계층별 현황입니다.

루트 파일: 그대로 전송됩니다. GitHub의 지침 문서에 따르면 리포지토리 내 어디에나 AGENTS.md 파일을 둘 수 있으며 디렉터리 트리에서 가장 가까운 파일이 우선순위를 갖습니다. 또한 리포지토리 루트의 CLAUDE.md 또는 GEMINI.md를 대체 파일로 명시하고 있습니다. 따라서 루트 CLAUDE.md는 수정 없이 Copilot 에이전트에 의해 읽힙니다. 빌드 명령, 컨벤션, 아키텍처 노트 등 프로젝트 지식이 여기에 집중되어 있다면 이미 중요한 부분의 대부분을 마이그레이션한 것입니다.

경로 범위 규칙: 깔끔하게 매핑되어 전송됩니다. 이번 마이그레이션에서 가장 잘 매칭되는 쌍입니다. Claude Code의 .claude/rules/ 디렉터리에는 paths: 프런트매터 필드를 가질 수 있는 마크다운 파일이 포함되어 있어, Claude가 일치하는 파일로 작업할 때만 규칙이 로드됩니다. Copilot의 상응하는 기능은 .github/instructions/NAME.instructions.md이며, 이 파일의 프런트매터는 glob 구문을 사용하는 applyTo 필드를 가집니다. 동일한 개념, 동일한 glob 어휘, 단지 파일 이름 규칙만 다를 뿐입니다. 한 시스템에서 src/api/**/*.ts 범위로 지정된 규칙은 다른 시스템에서도 동일하게 src/api/**/*.ts 범위로 지정됩니다.

리포지토리 전체 지침: 중복될 수 있는 두 번째 공간. Copilot은 리포지토리 컨텍스트의 모든 요청에 적용되는 .github/copilot-instructions.md도 지원합니다. 루트 CLAUDE.md가 이미 읽히고 있다면 이 파일은 필요하지 않으며, 두 파일을 모두 유지하면 한 파일만 업데이트되어 내용이 어긋나는 동기화 문제가 발생할 수 있습니다. 하나만 단일 진실 공급원(Source of Truth)으로 선택하세요.

중첩된 `CLAUDE.md` 파일: 전송되지 않습니다. 이 부분이 많은 사람들이 놓치는 지점입니다. Claude Code 문서를 보면 작업 디렉터리부터 디렉터리 트리를 거슬러 올라가며 각 디렉터리의 CLAUDE.md 및 CLAUDE.local.md를 로드하고 발견된 모든 파일을 컨텍스트로 병합합니다. 하위 디렉터리의 파일도 감지되어 Claude가 해당 디렉터리의 파일을 읽을 때 필요에 따라 로드됩니다. 반면 Copilot은 리포지토리 루트에 있는 CLAUDE.md만 허용합니다. 이것이 문서에 명시된 범위입니다. 따라서 packages/billing/CLAUDE.md는 Copilot에게 보이지 않습니다. 디렉터리별 지침을 표현하는 Copilot 네이티브 방식은 중첩된 AGENTS.md를 사용하는 것이며, 문서에 따르면 트리에서 가장 가까운 파일이 우선순위를 갖습니다. 모노레포에서는 이 차이 하나 때문에 대부분의 지침이 소리 없이 적용되지 않을 수 있습니다.

`@` 임포트: 대상이 없습니다. Claude Code의 CLAUDE.md는 @path/to/import 구문을 사용하여 다른 파일을 재귀적으로 가져올 수 있으며, 문서상 최대 4단계 깊이까지 지원합니다. GitHub의 지침 문서에는 이러한 임포트 메커니즘이 설명되어 있지 않습니다. 루트 파일이 5개의 실제 문서를 가져오는 얇은 인덱스 파일인 경우, Copilot은 인덱스만 읽고 실제 문서는 하나도 읽지 못합니다.

`CLAUDE.local.md`: 대상이 없습니다. Claude Code는 버전 관리에서 제외하고 개인적인 선호 설정을 유지할 수 있도록 프로젝트 루트의 CLAUDE.local.md를 지원합니다. Copilot에서 개인 선호 설정을 위한 레이어는 리포지토리가 아닌 GitHub 계정에 저장되는 개인 지침(Personal instructions)입니다. 이는 실제 작동하는 레이어이며, GitHub가 밝힌 우선순위는 "개인 지침이 가장 높은 우선순위를 가집니다. 그 다음은 리포지토리 지침이며, 조직 지침이 마지막으로 우선순위를 갖습니다."입니다. 하지만 이는 로컬 체크아웃 파일이 아니므로 복사해서 붙여넣는 것이 아니라 직접 다시 입력하여 이동해야 합니다.

자동 메모리: 대상이 없으며, 애초에 이식할 수 있는 성격이 아니었습니다. Claude Code의 자동 메모리는 기본적으로 활성화되어 있으며, 프로젝트별 노트를 ~/.claude/projects/<project>/memory/ 아래에 저장하고, 매 세션마다 MEMORY.md 파일의 처음 200행 또는 25KB를 로드합니다. 이는 명시적으로 머신 로컬 방식입니다. 문서에 따르면 이 파일들은 "머신이나 클라우드 환경 간에 공유되지 않습니다." GitHub의 지침 문서에는 세션 간에 메모리나 컨텍스트가 유지된다는 언급이 없으며, 지침 파일이 문서화된 유일한 영속성 메커니즘입니다. 따라서 이 레이어는 전송되지 않으며, 그 이유는 Copilot의 설계 때문이 아니라 애초에 이 레이어가 공유 가능한 아티팩트가 아니었기 때문입니다. 이미 이 문제에 부딪히셨다면, Claude Code가 머신 간에 망각하는 이유에서 설명한 것과 동일한 장벽을 만난 것입니다.

단계를 시작하기 전에 한 가지 짚고 넘어갈 점은, 두 시스템 모두 지침을 강제 사항이 아닌 컨텍스트로 설명한다는 것입니다. Claude Code 문서는 지침이 "강제된 구성이 아닌 컨텍스트"이며, 시스템 프롬프트 이후 사용자 메시지로 전달되므로 "엄격한 준수를 보장하지 않는다"고 명시하고 있습니다. GitHub의 우선순위 설명 역시 "그러나 관련된 모든 지침 세트가 Copilot에 제공됩니다"로 끝납니다. 어느 벤더도 완벽한 복종을 약속하지 않습니다. 따라서 마이그레이션은 준수되기를 바라는 내용이 아니라, 실제로 무엇이 읽히는지를 중심으로 계획해야 합니다.

1단계: 대상 위치가 있는 레이어 매핑하기

하향식(Top-down)으로 작업하되, 모든 것을 하나의 거대한 파일로 통합하려는 유혹은 참으세요.

루트 CLAUDE.md는 그대로 두세요. 잘 작동합니다. Copilot이 이 파일을 읽는다는 사실을 모르는 팀원들을 위해 명시적으로 표시하고 싶다면, 파일 상단에 두 에이전트 모두 이 파일을 읽는다는 주석을 한 줄 추가하세요. 이를 .github/copilot-instructions.md에 중복해서 작성하지 마세요. 두 개의 복사본을 관리하게 되어 결국 하나는 최신 상태를 잃게 됩니다.

paths: 필드가 있는 각 .claude/rules/*.md 파일을 applyTo 아래에 동일한 glob 패턴을 가진 .github/instructions/<name>.instructions.md로 변환하세요. diff에서 쌍이 명확히 보이도록 파일 이름을 알아보기 쉽게 유지하세요. paths: 필드가 없는 규칙은 무조건 적용되는 규칙입니다. Claude Code는 시작할 때 .claude/CLAUDE.md와 동일한 우선순위로 이를 로드하므로, 이러한 규칙은 경로 범위 디렉터리가 아닌 루트 파일이나 AGENTS.md에 포함되어야 합니다.

중첩된 CLAUDE.md 파일을 동일한 디렉터리의 중첩된 AGENTS.md 파일로 승격시키세요. 이는 이름 변경과 더불어 한 가지 결정이 필요합니다. 두 에이전트가 동일한 중첩 콘텐츠를 읽게 하려면, Claude Code 문서가 비대칭성에 대해 직접적으로 언급하고 있음을 유의해야 합니다. "Claude Code는 AGENTS.md가 아닌 CLAUDE.md를 읽습니다." 따라서 권장되는 패턴은 @AGENTS.md를 통해 AGENTS.md를 임포트하는 CLAUDE.md를 두거나 심볼릭 링크를 사용하는 것입니다. 즉, 각 하위 디렉터리에 하나의 실제 파일(AGENTS.md)을 유지하고, 이를 임포트하는 한 줄짜리 CLAUDE.md를 둘 수 있습니다. 이렇게 하면 두 에이전트 모두 동일한 텍스트를 읽으며, 수정할 곳은 단 한 곳이 됩니다.

더 진행하기 전에 임포트를 평탄화(Flatten)하세요. @로 임포트된 모든 파일은 임포트한 파일 내의 인라인 콘텐츠가 되거나, 해당 디렉터리의 중첩된 AGENTS.md가 되거나, 경로 범위 지침 파일이 되어야 합니다. Claude Code 자체 문서에서도 임포트로 분할하는 것이 "정리에는 도움이 되지만, 임포트된 파일이 시작 시 로드되므로 컨텍스트를 줄이지는 못한다"고 지적합니다. 따라서 평탄화 작업을 해도 Claude 측의 컨텍스트 관점에서는 손해 볼 것이 없으며, 이것이 콘텐츠가 Copilot에 전달될 수 있는 유일한 방법입니다.

2단계: 대상 위치가 없는 레이어 처리 결정하기

세 가지 분류가 있으며, 기본값에 의존하기보다는 실제 결정을 내려야 합니다.

`CLAUDE.local.md`. 파일을 읽고 분류하세요. 이러한 파일의 대부분은 순수한 개인적 선호 설정(샌드박스 URL, 선호하는 테스트 데이터)과 진작에 커밋되었어야 할 프로젝트 사실들이 섞여 있습니다. 두 번째 종류는 루트 파일에 커밋하세요. Copilot 사용 여부와 관계없이 잘한 결정이 될 것입니다. 첫 번째 종류는 Copilot의 개인 지침에 다시 입력하세요. 이 지침은 현재 리포지토리뿐만 아니라 작업하는 모든 리포지토리에 적용된다는 점을 기억해야 합니다. 어느 곳에도 두고 싶지 않은 내용은 삭제하세요. 한 머신의 단 하나의 도구만 읽을 수 있는 파일은 지식 저장소가 아닙니다.

자동 메모리. 메모리 디렉터리를 열고 MEMORY.md와 주제 파일들을 읽어보세요. 이 작업은 마이그레이션 전체에서 가장 가치 있는 시간입니다. 빌드 특이사항, 디버깅 인사이트, 테스트가 불안정한 이유 등 여러분이 미처 기록하지 못했지만 Claude가 프로젝트에 대해 스스로 파악해 낸 기록들이 담겨 있기 때문입니다. 이 중 어떤 것도 자동으로 Copilot으로 넘어가지 않습니다. 영구적인 사실들은 루트 파일이나 경로 범위 지침 파일로 승격시키세요. 특정 모델의 습관에 대한 노트나 일회성 디버깅 흔적 같은 나머지는 그대로 두세요. 틀린 내용은 아니지만 공유할 지식은 아닙니다.

돌아오는 길에 필요할 수 있는 Copilot 전용 메커니즘. Copilot 측에는 Claude Code에 상응하는 기능이 없는 두 가지 요소가 있으며, 이를 미리 알아두면 나중에 당황하는 일을 방지할 수 있습니다. 경로별 지침 파일은 선택 사항으로 excludeAgent 필드를 지원하여 "code-review" 또는 "cloud-agent"에서의 사용을 방지할 수 있습니다. 따라서 코드 리뷰에서 의도적으로 제외했던 규칙이 반대편 시스템에서는 제외할 방법이 없을 수 있습니다. 또한 조직 지침(Organization instructions)은 다른 사람이 제어할 수 있는 실제 레이어입니다. GitHub는 이를 우선순위에서 가장 낮게 배치하지만 여전히 제공합니다. 다시 마이그레이션해 돌아오거나 두 도구를 모두 실행하는 경우, 관리자에게 해당 레이어에 무엇이 있는지 문의하세요. 여러분이 구성하지 않은 출력을 형성할 수 있습니다.

위 작업을 한 번 하는 것은 합리적입니다. 하지만 새로운 에이전트가 등장할 때마다 이 작업을 반복해야 하는 것이 진짜 문제입니다. 상황은 점점 더 나빠지고 있습니다. 도구마다 고유한 파일 이름, 프런트매터, 우선순위, 자체 비공개 메모리 저장소를 만들어내기 때문에, N개의 도구가 있다면 동일한 프로젝트 지식의 복사본 N개가 서로 다른 속도로 어긋나게 됩니다.

MemoryLake는 이러한 패턴을 깨기 위해 존재합니다. 프로젝트의 지식을 하나의 메모리 레이어에 유지하고, 각 에이전트가 자체 로컬 복사본 대신 이 레이어에서 읽도록 하는 것입니다. 지침 파일은 매 세션마다 컨텍스트에 있어야 하는 규칙을 위해 원래 위치에 유지되는 반면, 누적되고 성장하는 지식 체계는 두 에이전트 모두 접근할 수 있는 곳에 위치합니다. 설정은 3단계로 진행됩니다.

1단계: API 키 생성

MemoryLake에 로그인하고 API 키를 생성하세요. 연결하는 모든 도구에서 하나의 자격 증명을 사용하게 되며, 이것이 핵심입니다. 이 자격 증명은 현재 선택한 에이전트보다 더 오래 유지됩니다.

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

마이그레이션 과정에서 방금 발굴한 자료부터 시작하세요. 자동 메모리의 영구적인 사실들, CLAUDE.local.md에 숨겨져 있던 프로젝트의 진실들, 결정 로그, 그리고 설명 없이는 임의적인 것처럼 보이는 컨벤션 뒤에 숨겨진 이유들입니다. 항목은 짧고 구체적으로 유지하세요. 좋은 항목인지 테스트하는 방법은 새로운 팀원이나 새로운 에이전트가 추가 질문 없이 그 내용을 바탕으로 행동할 수 있는지 여부입니다.

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

도구들을 연결하세요. MemoryLake는 MCP 및 API를 통해 접근할 수 있으므로, Claude Code, Codex, OpenClaw를 포함한 MCP 네이티브 에이전트들은 MCP 서버를 가리켜 연결하고, 그 외의 도구들은 API를 통해 동일한 메모리를 읽습니다. 지침 파일은 원래의 좁은 역할을 계속 수행하며, 공유 지식은 도구별로 중복되지 않게 됩니다.

두 가지 솔직한 한계가 있습니다. MemoryLake는 강제 레이어가 아닙니다. 모델의 결정과 관계없이 반드시 지켜져야 하는 규칙이 있다면, 양사 문서에서 지침을 구성이 아닌 컨텍스트라고 부르는 것과 마찬가지로 훅(hook)이나 CI 검사에 포함되어야 합니다. 또한 기존 파일을 대신 읽어주지 않으므로, 위의 마이그레이션 인벤토리 작업은 여전히 한 번은 직접 수행해야 합니다.

두 번째 에이전트 도입 비용이 첫 번째보다 적게 듭니다. Claude Code와 함께 Copilot을 추가할 때 비용이 많이 드는 부분은 구성이 아니라, 첫 번째 도구의 설정에 이미 암묵적으로 포함되어 있던 지식을 다시 도출해내는 것입니다. 이를 공유 레이어에 한 번만 정리해 두면, 세 번째 에이전트는 프로젝트가 아니라 단순한 연결 작업이 됩니다.

모노레포가 더 이상 예외 케이스가 되지 않습니다. 중첩된 파일의 비대칭성은 지침이 소리 없이 적용되지 않는 가장 흔한 원인입니다. 영역별 지식이 각 도구가 어느 디렉터리에서 어떤 파일을 발견하는지에 의존하지 않고 검색 가능해지면, 트리 구조는 더 이상 호환성 마찰을 일으키는 표면이 되지 않습니다.

지침 파일이 짧아져 더 잘 작동합니다. Claude Code 문서는 파일당 200행 미만을 유지할 것을 권장하며, 파일이 길어질수록 "더 많은 컨텍스트를 소비하고 준수율을 떨어뜨린다"고 지적합니다. Copilot의 가이드라인도 같은 방향입니다. 항상 로드되는 파일에서 참조 지식을 분리하여 검색 가능한 형태로 이동시키는 것은 단순히 깔끔하게 정리하는 것을 넘어, 남은 규칙들이 얼마나 안정적으로 준수되는지를 눈에 띄게 향상시킵니다.

검토 과정에서 불일치를 숨기지 않고 잡아낼 수 있습니다. 단일 진실 공급원이 있으면 오래된 항목은 diff로 나타납니다. 하지만 도구별로 5개의 복사본이 있으면, 오래된 항목은 왜 한 에이전트가 다른 에이전트와 다르게 믿고 있는지에 대한 미스터리가 됩니다.

디렉터리당 하나의 실제 파일과 포인터. AGENTS.md를 실제 콘텐츠로 유지하고, 이를 임포트하는 한 줄짜리 CLAUDE.md를 두세요. 두 에이전트 모두 동일한 텍스트를 읽으며 수정할 곳은 정확히 한 곳이 됩니다.

루트 파일을 절대 중복해서 만들지 마세요. 거의 동일한 텍스트를 포함하는 루트 CLAUDE.md와 .github/copilot-instructions.md를 함께 두는 것은 향후 불일치를 보장하는 지름길입니다. 하나만 선택하세요.

두 시스템 간에 glob 패턴을 동일하게 유지하세요. paths:와 applyTo가 동일한 구문으로 동일한 파일 세트를 설명할 때, 이들을 쌍으로 검토할 수 있습니다. 이들이 어긋나면 특정 영역 규칙이 한 도구에는 적용되고 다른 도구에는 적용되지 않는 현상이 발생하며, 이는 규칙이 아예 없는 것보다 더 나쁩니다.

구조를 변경할 때마다 로드된 내용을 확인하세요. Claude Code는 세션 내에서 로드된 메모리 파일 목록을 보여줍니다. 파일을 이동한 후 이를 확인하세요. Copilot 측에서는 중첩된 AGENTS.md가 실제로 인식되고 있는지 확인한 후에 적용되었다고 가정하세요. 읽히지 않는 파일은 모델이 지침을 무시하는 것처럼 보입니다. 이 차이점은 GitHub Copilot이 코드베이스 컨텍스트를 망각하는 이유에서 다루고 있습니다.

조직 레이어에 대해 문의하세요. 리포지토리가 지침이 구성된 조직 아래에 있는 경우, 여러분이 읽었든 읽지 않았든 해당 텍스트가 Copilot에 제공됩니다. 꼭 읽어보세요.

반드시 지켜야 하는 규칙은 지침이 아닌 강제 장치에 두세요. 양사 모두 지침 파일이 행동을 보장하기보다는 유도하는 역할을 한다고 명시하고 있습니다. 모든 커밋 전에 반드시 실행되어야 하는 작업은 훅이나 CI에 포함되어야 합니다.

이번 마이그레이션의 핵심은 이례적으로 반가운 소식입니다. Copilot이 루트 CLAUDE.md를 읽으므로 이미 관리하고 있는 파일이 계속 작동한다는 점입니다. 진짜 작업은 그 주변의 4개 레이어에 있습니다. AGENTS.md로 승격해야 하는 중첩된 파일, 평탄화해야 하는 임포트, 분류해야 하는 로컬 파일, 그리고 애초에 공유할 수 없었던 지식을 담고 있는 자동 메모리 디렉터리입니다.

이 인벤토리 작업을 한 번 수행하고 그 결과를 두 에이전트 모두 읽을 수 있는 곳에 두세요. 그렇지 않으면 다음 도구에서 약간 더 불리한 출발선에서 이 작업을 다시 해야 할 것입니다. 그때쯤이면 두 복사본이 이미 어긋나 있을 것이기 때문입니다. 반대 방향으로 이동하는 경우 GitHub Copilot을 Claude Code로 마이그레이션하기에서 역방향 마이그레이션을 다루고 있으며, CLAUDE.md를 Cursor로 마이그레이션하기에서 세 번째로 흔한 대상을 다룹니다.