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

AGENTS.md 콘텐츠는 깔끔하게 이전됩니다. 두 도구 모두 필수 구조가 없는 일반 Markdown을 읽습니다. Amp의 문서는 "코드베이스 구조, 빌드/테스트 명령 및 컨벤션에 대한 지침을 위해" AGENTS.md 파일을 찾는다고 설명하며, Codex의 문서는 "작업을 수행하기 전에 AGENTS.md 파일을 읽는다"고 설명합니다. 텍스트 내용을 변경할 필요는 전혀 없습니다.

루트 수준의 지침은 이전됩니다. 리포지토리 루트에 있는 단일 AGENTS.md는 두 도구 모두 동일하게 처리하는 유일한 구성입니다.

중첩된 AGENTS.md 파일은 타이밍은 다르지만 이전됩니다. Amp는 "에이전트가 하위 트리의 파일을 읽을 때 하위 트리 AGENTS.md 파일...을 포함"합니다. 즉, 파일 액세스에 의해 트리거되는 지연(lazy) 방식입니다. 반면 Codex는 미리 체인을 구성합니다. 즉, "시작할 때(실행당 한 번, TUI에서는 일반적으로 세션이 시작될 때 한 번을 의미) 지침 체인을 빌드"하며, 프로젝트 루트에서 현재 작업 디렉터리(cwd)로 내려갑니다. 동일한 파일이지만 적용되는 시점이 다르며, Codex의 경우 루트에서 cwd로 가는 경로에 있는 디렉터리만 해당됩니다.

리포지토리 상위의 지침은 이전되지 않습니다. 이것이 첫 번째 실제 차이점입니다. Amp는 항상 "현재 작업 디렉터리(또는 에디터 워크스페이스 루트) 및 상위 디렉터리($HOME까지)"에 있는 AGENTS.md 파일과 $HOME/.config/amp/AGENTS.md, $HOME/.config/AGENTS.md 및 시스템 전반의 파일을 포함합니다. 반면 Codex의 프로젝트 범위는 프로젝트 루트("일반적으로 Git 루트")에서 시작하여 아래로 내려갑니다. 리포지토리 위의 상위 폴더에 보관했던 모든 것은 Codex의 경로에 포함되지 않습니다. Codex에도 전역 범위가 있지만, 이는 특정 위치인 Codex 홈 디렉터리의 AGENTS.override.md 또는 AGENTS.md로 제한되며, "이 수준에서 비어 있지 않은 첫 번째 파일만 사용"합니다.

CLAUDE.md 폴백은 기본적으로 이전되지 않습니다. Amp의 규칙은 명확합니다. "디렉터리에 AGENTS.md가 없지만 AGENT.md('S'가 없는 단수형) 또는 CLAUDE.md라는 이름의 파일이 있는 경우 해당 파일이 포함됩니다." Codex에는 이러한 암시적 폴백이 없습니다. Codex는 AGENTS.override.md, AGENTS.md를 확인한 다음 project_doc_fallback_filenames에 나열된 파일을 확인하며, 문서에서는 그 외의 파일에 대해 단호하게 설명합니다. "이 목록에 없는 파일 이름은 지침 탐색에서 무시됩니다." 리포지토리의 특정 디렉터리가 지금까지 CLAUDE.md에 의존하여 작동하고 있었다면, Codex로 이동할 때 이 지침은 아무런 경고 없이 비활성화됩니다.

Glob 범위의 지침은 이전되지 않습니다. 이것이 가장 큰 공백이며, Codex의 문서화된 범위 지정 메커니즘은 완전히 다른 축으로 작동합니다. Amp는 루트 AGENTS.md에서 다른 파일을 @-mention할 수 있게 하며, 언급된 파일은 YAML 프론트 매터에 globs를 가질 수 있습니다. "globs가 있는 언급된 파일은 Amp가 해당 glob 중 하나라도 일치하는 파일을 읽은 경우에만 포함"되며, glob은 "../ 또는 ./로 시작하지 않는 한 암시적으로 앞에 **/가 붙습니다." 이를 통해 조건부이면서 항상 평탄한(flat) 지침을 제공할 수 있습니다. 예를 들어, TypeScript 파일을 읽을 때 docs/typescript-conventions.md가 활성화되고 그렇지 않을 때는 무시됩니다. 이 패턴을 구축해 두셨다면, 저희가 작성한 scoping Amp's instructions to the files they apply to에서 해당 패턴을 설명한 바 있습니다.

Codex의 문서화된 범위 지정 메커니즘은 디렉터리 중첩입니다. glob 조건부 포함에 대한 문서화된 대응 기능은 없습니다. 따라서 이러한 범위 지정 파일들은 각각 해당 파일이 지배하는 디렉터리 내의 중첩된 AGENTS.md가 되거나, 상위 파일의 무조건적인 텍스트가 되어야 합니다. 그리고 무조건적인 텍스트는 크기 제한에 영향을 미치며, 이것이 다음 문제입니다.

이제 AGENTS.md 크기가 중요해질 수 있습니다. Amp의 에이전트 파일 문서에는 결합된 크기 제한이 명시되어 있지 않습니다. 하지만 Codex의 문서에는 명시되어 있습니다. "빈 파일은 건너뛰고, 결합된 크기가 project_doc_max_bytes(기본값 32 KiB)로 정의된 제한에 도달하면 파일 추가를 중단합니다." 이 실패는 에러를 발생시키지 않으며, 단지 지침이 더 이상 포함되지 않을 뿐입니다. glob 범위의 파일 세트를 하나의 항상 켜져 있는 파일로 합치는 것은 정확히 이 제한 선을 넘게 만드는 원인이 됩니다.

Amp에는 없고 Codex에는 있는 것. Amp의 문서화된 지속성 메커니즘은 직접 작성하는 AGENTS.md 파일과 스레드뿐입니다. 이전 세션에서 스스로 기록하는 저장소에 대한 대응 기능은 Amp 문서에 없습니다. 반면 Codex에는 있습니다. "Memories를 사용하면 ChatGPT and Codex가 이전 작업의 유용한 컨텍스트를 미래 작업으로 전달할 수 있습니다." 이에 의존하기 전에 이것이 정확히 무엇인지 명확히 파악할 필요가 있으며, 이는 다음 섹션에서 다룹니다.

1단계: 하향식 탐색을 위한 탐색 트리 재구축

먼저 Amp의 커맨드 팔레트에서 agents-md list를 실행하세요. 그러면 Amp가 현재 실제로 사용하고 있는 파일 세트가 표시되며, 이는 거의 항상 여러분이 작성한 것으로 기억하는 세트보다 큽니다.

그 다음 해당 목록을 네 개의 그룹으로 분류하세요.

리포지토리 루트 또는 그 하위에 있으며 평소 작업하는 경로의 디렉터리에 있는 파일은 변경할 필요가 없습니다. Codex가 알아서 찾아냅니다.

리포지토리 상위 디렉터리에 있는 파일은 결정을 내려야 합니다. 콘텐츠가 개인적인 내용(기기 전용 명령, 테스트 중인 개인 설정 등)이라면 Codex의 전역 범위인 ~/.codex/AGENTS.md에 속합니다. 리포지토리 상위에 우연히 존재했던 프로젝트 콘텐츠라면 리포지토리 내부로 이동하세요. 현재 위치에서는 탐색되지 않습니다.

Amp가 조용히 승격하여 사용해 온 CLAUDE.md 및 AGENT.md 파일은 명시적으로 만들어야 합니다. 이 파일들을 AGENTS.md로 이름을 바꾸거나(이것이 더 깔끔한 결과이며, migrating CLAUDE.md to AGENTS.md에서 자세히 설명합니다), ~/.codex/config.toml의 project_doc_fallback_filenames에 추가하여 Codex가 이를 지침 파일로 처리하도록 하세요. Amp를 완전히 떠났다면 이름을 바꾸는 것이 좋고, 일부 팀원이 여전히 Amp를 사용하며 이전 이름을 기대한다면 폴백 목록을 사용하는 것이 좋습니다.

Glob 범위로 @-mention된 파일들은 이들이 지배하는 디렉터리로 재배치해야 합니다. globs가 src/components/** 및 **/*.tsx인 파일은 src/components/AGENTS.md가 됩니다. 여러 무관한 트리에 걸쳐 있는 glob을 가진 파일은 분할하거나, 항상 켜져 있는 파일로 승격하고 크기 제한 예산에 반영해야 합니다.

이 작업을 수행하는 동안 기억해야 할 두 가지 Codex 동작이 있습니다. 디렉터리당 하나의 파일만 사용되며("Codex는 디렉터리당 최대 하나의 파일만 포함합니다"), 동일한 디렉터리 내에서는 AGENTS.override.md가 AGENTS.md보다 우선하며 형제 파일은 완전히 무시됩니다. 그리고 병합 순서는 루트에서 아래 방향입니다. "현재 디렉터리에 더 가까운 파일이 결합된 프롬프트에서 더 나중에 나타나기 때문에 이전 지침을 덮어씁니다." 따라서 구체성은 규칙 유형이 아니라 깊이(depth)에서 나옵니다.

중첩된 디렉터리에서 Codex를 시작하고 로드된 지침 소스를 나열하도록 요청하여 검증하세요. 예상한 파일이 누락되었다면, 대개 프로젝트 루트 위에 있거나, 형제 오버라이드 파일에 의해 억제되었거나, 체인이 바이트 제한에 도달했기 때문입니다. 관련 탐색 실패는 why Codex skips your AGENTS.md rules에서 다루며, Copilot rather than Amp에서 마이그레이션하는 경우에도 동일한 탐색 모델이 적용됩니다.

2단계: Codex Memories가 책임질 수 있는 범위 결정하기

Codex의 메모리 레이어는 기본적으로 꺼져 있습니다. Settings > Personalization에서 활성화할 수 있습니다. 활성화되면 "Codex는 적격한 이전 대화의 유용한 컨텍스트를 로컬 메모리 파일로 변환할 수 있습니다." 또한 "활성 상태이거나 수명이 짧은 세션은 건너뛰고, 생성된 메모리 필드에서 비밀 정보를 수정(redact)하며, 매 대화가 끝날 때 즉시 업데이트하는 대신 백그라운드에서 메모리를 업데이트합니다." 파일은 ~/.codex/memories/ 아래에 저장되며 "이전 대화의 요약, 영구 항목, 최근 입력 및 지원 증거를 포함"합니다. 대화별로 /memories 명령을 통해 현재 대화가 기존 메모리를 읽거나 미래 메모리에 제공할지 여부를 제어할 수 있으며, "대화 수준의 선택은 전역 메모리 설정을 변경하지 않습니다."

이에 얼마나 많은 비중을 둘지 결정하기 전에 OpenAI의 자체 지침을 읽어보세요. "필수 팀 지침은 AGENTS.md 또는 체크인된 문서에 보관하세요. 메모리는 항상 적용되어야 하는 규칙의 유일한 소스가 아니라 유용한 회상 레이어로 취급해야 합니다."

이것이 올바른 경계이며, 여러분만의 방식으로 재정의할 가치가 있습니다. Codex Memories는 로컬의, 설치별로 생성되는 회상 레이어입니다. 문서에서는 "이 파일들을 생성된 상태(generated state)로 취급"하고 "기본 제어 표면으로서 손으로 직접 편집하는 것에 의존하지 말 것"을 권장합니다. 이는 팀원들과 공유되지 않으며, 특정 Codex 홈 디렉터리에 종속되고, 속도 제한에 가까워지면 생성이 건너뛰어질 수 있습니다. 본인의 컴퓨터에서 반복 작업을 줄이는 데는 진정으로 유용하지만, 팀의 결정 사항을 보관할 곳은 아닙니다.

결국 Amp에서 가졌던 것과 동일한 공백이 이제 더 명확한 형태로 남게 됩니다. 작업하면서 팀이 확립한 것들(예: 스트리밍 파서에서 전환한 이유, 불안정한 테스트에서 이미 실패한 두 가지 수정 사항, 고객이 요구한 명명 규칙 등)은 지침 파일에도, 노트북별로 생성된 저장소에도 속하지 않습니다. 이는 sharing context between sessions을 이러한 모든 도구에서 해결되지 않은 문제로 만드는 것과 동일한 공백입니다.

이 마이그레이션이 까다로운 이유는 두 도구 모두 "에이전트가 항상 알아야 할 사항"은 해결하지만, "우리가 무엇을 배웠는가"는 해결하지 못하기 때문입니다. 지침 파일은 설계상 매 실행마다 다시 전송됩니다. 생성된 로컬 저장소는 설계상 머신별로 존재합니다. 팀의 지식은 둘 중 어디에도 해당하지 않습니다.

MemoryLake는 두 도구의 외부에 존재합니다. 발견된 사실들을 보관하고, 이를 MCP 및 API를 통해 노출하며, 이번 주의 클라이언트가 Amp인지, Codex인지, 혹은 아직 도입하지 않은 다른 도구인지 신경 쓰지 않습니다. 덕분에 다음 마이그레이션은 아주 지루하고 평범한 작업이 되며, 이것이 바로 우리가 진정으로 원하는 목표입니다.

1단계: API 키 생성

키를 생성하고 약 30초 만에 첫 번째 요청을 만들어 보세요. 팀이 사용하는 모든 환경에서 읽을 수 있는 단 하나의 키 덕분에, 지식이 특정 에디터의 설정 디렉터리의 전유물이 되지 않도록 방지할 수 있습니다.

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

아키텍처 노트, 현재 재시도 정책의 배경이 된 장애 보고서, 아무도 반복하고 싶지 않은 디자인 리뷰 등 이미 확립된 결정 사항이 담긴 문서, 이미지, 파일을 업로드하세요. 매번 다시 설명하기 지겨운 내용부터 시작해 보세요.

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

Claude, Codex, OpenClaw 및 기타 에이전트에 MCP 또는 API를 통해 액세스 권한을 부여하세요. 실제 작업 시에는 작업 시작 시 관련 메모리를 읽고, 작업 중에 수정한 사항을 다시 기록하여 수정 사항이 해당 세션보다 더 오래 지속되도록 합니다.

마이그레이션의 리스크가 사라집니다. 탐색 트리가 재구축되고 팀 지식이 두 도구 외부로 분리되면, 향후 도구를 변경할 때 수정해야 할 것은 오직 지침 파일 구문뿐입니다. 이는 몇 달간의 재발견 프로젝트가 아니라 반나절 만에 끝낼 수 있는 작업이 됩니다.

AGENTS.md 파일이 더 가벼워지고 개선됩니다. 대부분의 비대해진 지침 파일은 갈 곳 없는 발견된 사실들이 누적되었기 때문에 비대해진 것입니다. 이를 외부로 이동하면 32 KiB 제한 아래로 여유롭게 유지할 수 있으며, 더 유용하게는 남은 콘텐츠가 실제로 리포지토리에서 작업하는 방법에 집중할 수 있게 됩니다.

Codex Memories를 안전하게 활성화할 수 있습니다. 필수 규칙이 체크인된 파일에 있고 팀 지식이 공유 저장소에 있으면, 로컬 회상 레이어는 중요한 역할을 짊어지지 않는 순수한 편의 기능이 됩니다. 이것이 바로 OpenAI 문서가 권장하는 방식입니다.

그리고 구전으로만 전해지던 지식들이 더 이상 구전에 머물지 않게 됩니다. 신입 엔지니어의 Codex는 3개월 동안 지적받으며 지식을 습득하는 대신, 첫 번째 작업부터 다른 모든 사람들과 동일하게 확립된 결정 사항을 읽고 반영할 수 있습니다.

신뢰하기 전에 트리를 재구축하세요. 가장 깊은 작업 디렉터리에서 Codex를 시작하고 무엇이 로드되었는지 물어보세요. Amp와 달리 Codex는 깊이에 따라 결과가 달라집니다.

폴백 목록보다 이름 변경을 선호하세요. project_doc_fallback_filenames가 작동하긴 하지만, 이는 로컬 설정 파일입니다. 이름을 변경한 AGENTS.md는 리포지토리에 포함되어 모든 사람에게 적용됩니다.

오버라이드를 작업 위치와 가깝게 두세요. Codex의 자체 권장 사항은 "탐색이 현재 디렉터리에서 멈추므로, 오버라이드를 특수 작업에 최대한 가깝게 배치하라"는 것입니다.

glob을 평탄화할 때 크기 제한을 주의하세요. 항상 켜져 있는 텍스트가 되는 모든 glob 범위의 Amp 파일은 이제 32 KiB 제한을 두고 경쟁하게 됩니다. 제한을 늘리는 것보다 중첩(nesting)을 활용하는 것이 더 효율적입니다.

## Code Review Rules의 범위를 제한하여 유지하세요. Codex는 해당 규칙이 지배하는 코드와 가장 가까운 AGENTS.md에서 이 섹션을 읽으므로, 루트 수준의 검사는 루트에 두고 서비스별 검사는 중첩된 파일에 두세요.

메모리에 비밀 정보를 넣지 마세요. Codex는 생성된 필드에서 비밀 정보를 수정(redact)하지만, 문서에서는 여전히 Codex 홈 디렉터리를 공유하기 전에 파일을 검토할 것을 권장합니다. 두 가지 모두 사실이므로, 자동 수정을 맹신하지 말고 최종 방어선으로만 취급하세요.

Amp와 Codex는 동일한 파일 형식을 읽지만, 파일을 어디서 찾을지에 대해서는 거의 모든 면에서 의견이 다릅니다. Amp는 상위 방향으로 검색하여 관대하게 포함하는 반면, Codex는 하위 방향으로 하나의 체인을 구성하고 디렉터리당 하나의 파일만 가져오며 바이트 제한에서 멈춥니다. 두 가지 접근 방식 모두 틀린 것은 아니며, 파일 호환성이 곧 동작 호환성을 의미하는 것은 아니라는 점만 인지하면 마이그레이션 자체는 기계적으로 처리할 수 있을 만큼 각 도구의 동작이 명확하게 문서화되어 있습니다.

기계적이지 않은 부분은 두 도구 모두 지원한다고 주장하지 않는 영역입니다. Codex의 자체 문서가 그 경계를 명확히 해줍니다. 메모리는 "항상 적용되어야 하는 규칙의 유일한 소스가 아니라... 유용한 회상 레이어"라는 점입니다. 이에 따른 당연한 귀결로 제3의 범주가 존재합니다. 바로 팀이 알아낸 지식으로, 이는 지침 파일에 담기에는 너무 구체적이고 노트북별 저장소에 두기에는 너무 많이 공유되는 정보입니다. 이를 두 도구 모두 읽을 수 있는 곳에 두고, 하향식 탐색을 위해 탐색 트리를 재구축하면 마이그레이션은 반나절 만에 완료되고 안정적으로 유지될 것입니다.