컨텍스트 손실 없이 GitHub Copilot에서 Codex로 마이그레이션하는 방법 (2026)

`AGENTS.md`는 아무 작업도 하지 않아도 이전됩니다. 두 도구 모두 이 파일을 읽고, 가장 가까운 파일을 먼저 적용합니다. 이미 AGENTS.md로 통합했다면, 리포지토리에서 Codex를 열기만 해도 지침이 바로 적용됩니다. 이는 이번 분기에 어떤 에이전트를 사용하든 이 파일로 표준화해야 하는 가장 강력한 이유입니다.

`.github/copilot-instructions.md`는 자동으로 이전되지 않지만, 깔끔하게 변환할 수 있습니다. GitHub는 이를 "리포지토리 컨텍스트에서 이루어지는 모든 요청에 적용되는" 지침으로 설명합니다. Codex에는 이와 정확히 일치하는 개념인 리포지토리 루트의 AGENTS.md가 있으므로, 파일 이름을 바꾸어 복사한 뒤 오래된 내용을 검토하여 삭제하면 됩니다.

경로 범위 지침은 변환이 가능하지만, 기계적으로 처리되지는 않습니다. Copilot은 .github/instructions 아래에 하나 이상의 NAME.instructions.md 파일을 지원하며, 각 파일에는 적용할 파일이나 디렉토리를 선언하는 glob 구문을 사용하는 applyTo 프런트매터(frontmatter) 필드가 있습니다. Codex에는 glob 메커니즘이 없습니다. Codex의 유일한 범위 지정 도구는 파일이 위치한 곳입니다. ~/.codex/AGENTS.md(또는 $CODEX_HOME), 리포지토리 루트, 중간 디렉토리, 작업 디렉토리 순으로 위에서 아래로 조립되며 가장 가까운 파일이 우선 적용됩니다.

따라서 applyTo: "src/api/**"로 범위가 지정된 규칙은 src/api/ 내부의 AGENTS.md가 됩니다. 이는 glob 패턴이 디렉토리 구조를 따를 때는 잘 작동하지만, 그렇지 않을 때는 결정이 필요합니다. 예를 들어 **/*.test.ts와 같은 glob은 전체 트리 구조에 걸쳐 있으므로 단일 홈을 가질 수 없습니다.

조직(Organization) 지침은 전혀 이전되지 않습니다. GitHub는 "개인 지침이 가장 높은 우선순위를 가집니다. 그 다음은 리포지토리 지침이며, 조직 지침이 가장 마지막으로 우선순위를 가집니다"라는 3단계 우선순위를 명시하고 있습니다. Codex에는 이 세 번째 단계를 수용할 조직 관리 지침 레이어가 없습니다.

이것이 실질적으로 무엇을 의미하는지 유의하세요. Copilot 출력을 형성하는 일부 지침은 다른 사람이 작성했을 수 있으며, 여러분은 이를 읽어본 적이 없을 수도 있습니다. 마이그레이션하기 전에 조직에서 설정한 지침이 있는지 확인하고 사본을 확보하세요. 그렇지 않으면 Codex가 왜 팀의 스타일과 미묘하게 다른 코드를 작성하는지 의아해하며 몇 주를 보내게 될 것입니다.

`excludeAgent` 역시 대응하는 기능이 없습니다. Copilot의 경로별 지침은 code-review 또는 cloud-agent와 같은 값을 가진 선택적 excludeAgent 필드를 허용하므로, 특정 영역에서 규칙이 적용되지 않도록 의도적으로 제외할 수 있습니다. Codex에는 이를 표현할 수 있는 기능이 없습니다. 코드 리뷰에서 제외하도록 범위를 지정했던 규칙은 변환 후 파일이 로드되는 모든 곳에 적용되므로, 이러한 규칙들을 특별히 확인해야 합니다.

개인 지침은 글로벌 파일로 변환됩니다. GitHub의 개인 지침은 작업 전반에 적용되며 가장 높은 우선순위를 가집니다. 이에 해당하는 Codex의 기능은 ~/.codex/AGENTS.md입니다. 이 파일은 컴퓨터의 모든 프로젝트에서 로드되므로 짧게 유지하세요.

두 도구 모두 어떤 파일에도 보관하지 않는 것. GitHub의 커스텀 지침 문서는 Copilot이 세션 간에 메모리를 유지한다는 주장을 하지 않으며, Codex 자체의 메모리 기능은 기본적으로 꺼져 있습니다. 따라서 규칙 뒤에 숨겨진 추론(장애 사건, 제약 조건, 거부된 대안 등)은 이전할 시스템 어디에도 존재하지 않습니다. 이 때문에 완전히 마이그레이션된 설정임에도 불구하고 여전히 프로젝트를 잘 모르는 것처럼 느껴지게 되며, 이는 Copilot losing your codebase context에서 제기된 불만과 동일한 맥락입니다.

1단계: 직접 작성하지 않은 레이어를 포함하여 4개의 Copilot 레이어 모두 인벤토리 작성하기

Codex를 다루기 전에 다음 항목들을 수집하세요:

• .github/copilot-instructions.md — 리포지토리 전체 적용 파일
• .github/instructions/ 아래의 모든 파일과 각 파일의 applyTo 패턴 및 excludeAgent 값
• 리포지토리에 이미 존재하는 모든 AGENTS.md 파일 및 해당 위치
• GitHub 설정의 개인 지침
• 조직(Organization) 지침 (소유자나 관리자에게 요청해야 함)

그런 다음 출처별로 분류하세요. 이는 모든 마이그레이션 비용을 줄여주는 분류 작업입니다. 리포지토리에서 파생된 것(삭제 — Codex가 리포지토리를 읽음), 직접 작성했고 여전히 유효한 것(이것이 마이그레이션 대상), 더 이상 사용되지 않는 것(기억하고 있을 때 지금 삭제).

진행하면서 applyTo 패턴에 주의를 기울이세요. 이는 단순한 장식이 아니라 각 규칙이 언제 중요하게 작용해야 하는지에 대한 유일한 기록입니다. 범위 없이 복사된 규칙은 모든 세션에서 노이즈가 되거나, 무관해 보여 결국 삭제하게 되는 규칙이 됩니다.

2단계: 범위를 디렉토리 위치로 재구성하고 남은 항목 처리 결정하기

살아남은 각 규칙을 Codex가 찾을 수 있는 위치에 배치합니다:

• 리포지토리 전체 → 리포지토리 루트의 AGENTS.md에 추가하고 커밋합니다.
• 경로 범위 및 디렉토리 형태 → 해당 디렉토리 내부의 AGENTS.md. applyTo: "src/api/**"는 src/api/AGENTS.md가 되며, 이제 범위는 도구가 준수해야 하는 패턴이 아니라 위치에 의해 강제됩니다.
• 경로 범위 및 횡단 관심사(Cross-cutting) → 판단이 필요한 부분입니다. 수십 개의 패키지에 걸쳐 **/*.test.ts와 일치하는 규칙은 세 가지 옵션이 있습니다. 짧고 중요하다면 루트 파일로 승격시키거나, 테스트가 실제로 존재하는 2~3개 디렉토리에 복사본을 배치하거나, 아니면 삭제하고 린터(linter)에 의존하는 것입니다.
• 개인 → ~/.codex/AGENTS.md (짧게 유지).
• 조직 수준 → Codex에는 조직 계층이 없으므로 리포지토리 루트 AGENTS.md에 커밋된 섹션으로 추가합니다. 파일 내에 조직 정책에서 가져온 것임을 명시하여 누군가의 개인적인 선호도로 오해받아 삭제되지 않도록 하세요.
• `excludeAgent`가 포함된 모든 항목 → 이제 모든 곳에 적용해야 하는지 의식적으로 결정하고, 그렇지 않다면 삭제하세요.

두 가지 기계적인 참고 사항이 더 있습니다. Codex는 CLAUDE.md를 읽지 않으므로, 다른 도구에서 가져온 해당 파일이 리포지토리에 있다면 그 내용도 AGENTS.md에 존재해야 합니다. 그리고 Codex 메모리는 별도의 결정 사항입니다. 설정의 개인화(Personalization)에서 활성화하거나 [features] memories = true로 활성화할 수 있으며, 이것이 무엇을 제공하는지 알아두어야 합니다. 이는 ~/.codex/memories/에 저장되는 생성된 상태로, 프로젝트별이 아닌 글로벌하며 해당 컴퓨터에만 적용되며, 기록용이 아닌 편의성 레이어로 유용합니다.

그런 다음 조립된 결과 전체를 한 번에 쭉 읽어보세요. 이는 사람들이 흔히 건너뛰는 단계이지만, 이미 삭제한 패키지를 사용하라고 에이전트에게 지시하는 2024년의 오래된 규칙을 잡아낼 수 있는 단계입니다.

1단계의 인벤토리 작업이 실제로 무엇에 관한 것이었는지 주목해 보세요. 4개의 레이어, 3개의 포맷, 관리자에게 요청해야 했던 1개의 계층이 있었지만, 그 중 어느 것도 왜 그렇게 해야 하는지에 대한 단 한 문장도 포함하고 있지 않았습니다. 규칙은 문서화되지 않은 결정들의 압축된 결과물일 뿐입니다.

이 부분이 바로 재배치할 가치가 있는 부분입니다. 지침 파일은 에이전트가 읽는 리포지토리에 유지하되, 그 추론 과정은 특정 벤더의 설정 디렉토리 내부가 아닌 별도의 저장소에 보관하세요.

MemoryLake는 이를 위한 메모리 레이어입니다. 규칙 뒤에 있는 결정 사항, 장애 보고서, 소스 문서들을 하나의 저장소에 보관하여 Claude 및 Codex와 같은 MCP 지원 도구에서 직접 읽을 수 있고, API를 통해 ChatGPT에서도 읽을 수 있습니다. AGENTS.md는 무엇을 해야 하는지 알려주고, 저장소는 왜 그래야 하는지 알려주므로 다음번에 마이그레이션할 필요가 없습니다.

1단계: API 키 생성하기

키를 생성하고 약 30초 만에 첫 번째 요청을 보낼 수 있습니다. 세션에 직접 붙여넣는 대신 환경 변수나 비밀 관리자(secret manager)에 보관하세요.

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

규칙의 기반이 된 문서, 이미지, 파일을 업로드하세요. 아키텍처 결정 기록(ADR), 장애 보고서, API 계약서, 조직 지침이 강제하던 보안 요구사항, 모두가 동의한 RFC 등이 이에 해당합니다. 한 줄짜리 규칙보다는 소스 자체를 업로드하세요. 한 줄짜리 규칙은 이미 가지고 있는 것이며 끊임없이 의문이 제기되는 대상이기 때문입니다.

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

Claude, Codex, OpenClaw 및 기타 AI 에이전트에게 MCP 또는 API를 통해 메모리 접근 권한을 부여하세요. Codex는 AGENTS.md 파일과 함께 MCP를 통해 저장소를 직접 읽습니다. ChatGPT의 경우, API를 통해 필요한 내용을 검색하여 프롬프트나 모델을 호출하는 워크플로우에 주입합니다.

첫 번째 차이점은 횡단 관심사 규칙이 더 이상 딜레마가 되지 않는다는 것입니다. 모든 곳의 테스트 파일과 일치하는 규칙을 6개의 디렉토리에 중복해서 넣거나 루트 파일에 억지로 밀어 넣을 필요가 없습니다. 에이전트가 테스트 작업을 할 때만 검색되고, 그렇지 않을 때는 나타나지 않게 할 수 있습니다.

두 번째는 마이그레이션 시 조직 정책 레이어가 사라지지 않는다는 점입니다. 관리자가 설정한 규칙은 보이지 않는 인프라였습니다. 하지만 근거와 함께 문서화되고 검색 가능한 기록이 되면, 도구가 바뀌거나 관리자가 바뀌어도 그대로 유지됩니다.

세 번째는 루트 AGENTS.md를 준수하기 쉬울 만큼 짧게 유지할 수 있다는 점입니다. 모든 세션에 로드되는 모든 파일은 요청과 경쟁하게 됩니다. 검색 기능이 세부 사항을 처리하므로, 항상 로드되는 파일에는 답변을 틀리게 만들 수 있는 핵심 제약 조건만 담을 수 있습니다. 이로 인해 re-explaining your project each session과 같은 비효율적인 대안을 반복하지 않아도 됩니다.

또한 이는 Codex 자체의 메모리와도 결합됩니다. 로컬 메모리는 해당 컴퓨터에서 사용자의 습관을 계속 축적하고, 공유 저장소는 팀원들과 다른 도구들이 필요로 하는 정보를 보관합니다. 서로의 영역을 침범하지 않으므로, multi-tool setups from drifting과 같은 멀티 도구 설정의 괴리 현상을 방지할 수 있습니다.

필요하기 전에 미리 AGENTS.md로 표준화하기

이번 마이그레이션에서 AGENTS.md 레이어가 무료인 이유는 두 도구 모두 이 파일을 읽기 때문입니다. 이 특성은 최적화할 가치가 있습니다. 벤더 전용 파일 대신 AGENTS.md에 표현할 수 있는 모든 내용은 다시는 마이그레이션할 필요가 없는 콘텐츠가 됩니다.

조직 지침을 문서로 확보하기

이는 Copilot을 떠날 때 가장 흔히 간과되는 단일 항목입니다. 가장 낮은 우선순위 단계에서 다른 사람의 규칙이 여러분의 출력을 형성하고 있었습니다. 이를 요청해서 읽어보고 무엇을 가져갈지 결정하세요. 6주 후에 미묘하게 잘못된 코드를 보고 나서야 지침이 누락되었음을 깨닫지 않도록 하세요.

위치로 범위를 표현하고, 일부 규칙의 정밀도 저하를 수용하기

디렉토리 배치는 Codex의 유일한 범위 지정 메커니즘이며, 이는 트리 구조를 가로지르는 glob 패턴에 있어서는 확실한 다운그레이드입니다. 변환이 무손실인 것처럼 가장하는 대신, 규칙별로 이러한 트레이드오프를 명확히 정의하세요. 승격시키거나, 복사본을 만들거나, 아니면 삭제하세요.

항상 로드되는 파일은 작게 유지하기

루트 AGENTS.md와 ~/.codex/AGENTS.md는 지속적으로 로드됩니다. 여기에 엄격한 제약 조건만 넣고 다른 것은 넣지 마세요. 긴 지침 파일은 에러를 발생시키지 않으며, 단지 조용히 무시될 뿐입니다. 그게 더 나쁜 상황입니다.

신뢰하기 전에 실제로 로드된 내용 확인하기

지침 마이그레이션 후의 실패 모드는 조용히 일어납니다. 에이전트는 규칙을 보지 못했다고 알려주지 않습니다. 파일을 배치한 후 리포지토리에서 세션을 열고 Codex에 현재 작동 중인 지침을 말해달라고 요청한 다음, 하위 디렉토리에서 작업하면서 다시 물어보세요. 해당 디렉토리에서 작업할 때 디렉토리 범위의 AGENTS.md가 나타나지 않는다면 배치가 잘못된 것입니다. 한 달 동안 미묘하게 어긋난 diff를 확인하는 것보다 1분 만에 이를 알아내는 것이 훨씬 낫습니다.

지침과 강제 적용을 혼동하지 않기

두 도구의 지침 파일 모두 동작을 보장하지는 않으며, 단지 프롬프트에 컨텍스트를 추가할 뿐입니다. 포맷팅, 금지된 임포트, 보호된 파일, 커밋 정책 등은 린터, 훅(hook), CI의 영역입니다. 지침 파일은 이유를 설명하게 하고, 도구가 이를 보장하도록 하세요.

GitHub Copilot에서 Codex로의 마이그레이션은 무료인 부분과 그렇지 않은 부분으로 명확히 나뉩니다. 무료인 부분: 두 도구 모두 리포지토리 내 어디서나 읽고 가장 가까운 파일이 우선 적용되는 AGENTS.md입니다. 무료가 아닌 부분: 리포지토리 전체에 적용되는 .github/copilot-instructions.md, applyTo glob 패턴을 디렉토리 배치로 변환해야 하는 경로 범위의 .instructions.md 파일, 그리고 Codex에 상응하는 기능이 없는 조직(Organization) 계층입니다. 또한 /import는 Claude Code와 Cursor를 대상으로 하므로 이 중 어떤 것도 처리해주지 않습니다.

따라서 관리자가 소유한 레이어를 포함하여 4개의 레이어 모두 인벤토리를 작성하고, 삭제 키를 손에 쥔 채 출처별로 분류하고, 범위를 위치로 재구성한 다음, 신뢰하기 전에 조립된 결과를 한 번 읽어보세요. 그런 다음 에이전트가 읽을 수 있는 단일 저장소에 규칙 뒤에 숨겨진 이유를 보관하여, 다음 전환 시에는 발굴 작업 대신 단순한 설정 변경만으로 끝나도록 하세요. 만약 목적지가 Cursor라면, the Copilot-to-Cursor path에서 정반대의 트레이드오프(실제 조건부 로딩 및 자체 변환 비용)를 가진 규칙 시스템을 다룹니다.