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

두 도구 모두 탐색 방식을 정확하게 문서화하고 있으므로, 나란히 비교해 보면 차이점을 쉽게 이해할 수 있습니다.

Codex는 작업을 시작하기 전에 모든 것을 하나의 정렬된 체인으로 결합합니다:

"Codex는 시작할 때 명령 체인을 빌드합니다(실행당 한 번, TUI에서는 보통 시작된 세션당 한 번을 의미합니다)."

탐색은 전역적으로 Codex 홈 디렉터리에서 시작되며, 여기서 "AGENTS.override.md가 존재하면 이를 읽고, 그렇지 않으면 AGENTS.md를 읽으며" "이 수준에서 비어 있지 않은 첫 번째 파일만 사용합니다." 그런 다음 프로젝트를 탐색합니다:

"프로젝트 루트(일반적으로 Git 루트)에서 시작하여 Codex는 현재 작업 디렉터리까지 내려갑니다."

해당 경로의 각 디렉터리에서 AGENTS.override.md, AGENTS.md, 그리고 project_doc_fallback_filenames에 구성된 대체 이름을 확인하고 "디렉터리당 최대 하나의 파일만 포함"합니다. 병합은 단순 연결 방식입니다. "Codex는 루트에서부터 아래로 파일을 연결하며, 빈 줄로 구분합니다. 현재 디렉터리에 더 가까운 파일은 결합된 프롬프트에서 더 나중에 나타나므로 이전 가이드를 재정의(override)합니다."

그리고 엄격한 상한선이 있습니다. Codex는 "결합된 크기가 project_doc_max_bytes(기본값 32 KiB)로 정의된 제한에 도달하면 파일 추가를 중단"합니다.

OpenHands는 정반대의 전제에서 시작합니다. 루트 AGENTS.md는 항상 활성화되어 있지만, 다른 모든 것은 관련이 있을 때까지 의도적으로 보류됩니다. 문서에서는 이 메커니즘을 표로 설명합니다. 리포지토리 루트의 AGENTS.md는 "전체 콘텐츠가 초기 시스템 프롬프트에 포함됨"을 의미하는 반면, .agents/skills/<skill-name>/SKILL.md에 있는 에이전트 스킬(Agent Skill)은 "이름과 설명이 먼저 공개되고, 에이전트는 관련이 있을 때 전체 스킬을 호출함"을 의미합니다.

이어지는 안내는 Codex에서 전환하는 모든 사람에게 가장 중요한 문장입니다:

"리포지토리 전체에 적용되는 짧은 규칙에는 AGENTS.md를 사용하세요. 특정 작업에만 필요한 집중적인 지식에는 SKILL.md를 사용하세요."

그리고 이에 따르는 경고 메시지입니다:

"항상 활성화된 콘텐츠는 처음부터 대화 컨텍스트를 차지합니다. AGENTS.md를 간결하게 유지하고, 길거나 전문적인 명령은 온디맨드 스킬 및 참조로 이동하세요."

즉, 규칙의 콘텐츠는 그대로 전송되지만, 규칙의 구조는 전송되지 않습니다. Codex에서 디렉터리를 중첩하는 것은 조건부 메커니즘입니다. 전문화된 작업에 가까운 곳에 파일을 배치하면 연결된 프롬프트의 뒷부분에 배치되는 방식입니다. 반면 OpenHands에서 중첩은 메커니즘이 아닙니다. 메커니즘은 스킬의 설명, 선언된 트리거 또는 선언된 경로 패턴입니다.

Codex 체인을 하나의 OpenHands AGENTS.md로 평탄화(flattening)하는 것은 지름길이 아닙니다. 이는 대상 도구의 문서에서 명시적으로 하지 말라고 경고하는 행동입니다.

1단계: 각 부분이 실제로 적용되는 빈도에 따라 체인 분할하기

Codex 명령 체인을 루트부터 아래로 살펴보며 모든 블록을 다음 세 가지 범주 중 하나로 분류하세요.

언제 어디서나 항상 참인 것. 테스트 명령, 패키지 관리자, "생성된 파일은 절대 편집하지 말 것" 규칙, 리포지토리 전체에 적용되는 명명 규칙 등이 이에 해당합니다. 이것이 새로운 루트 AGENTS.md가 되며, 짧아야 합니다. 현재 루트 AGENTS.md가 32 KiB 제한에 맞춰 길어졌다면, 이번 기회에 실제로 보편적인 내용이 얼마나 되는지 확인해 보세요.

특정 영역에서만 참인 것. 결제 서비스, 프론트엔드 또는 마이그레이션 폴더에 적용되어 중첩된 AGENTS.md에 있던 모든 내용입니다. 이들은 paths 선언이 포함된 스킬이 됩니다. OpenHands는 이를 제안이 아닌 결정론적 규칙으로 문서화합니다. paths는 "파일을 경로 트리거 규칙으로 변환합니다. 이 규칙은 모델에 노출되지 않으며, 일치하는 파일을 읽거나 편집하거나 생성할 때 대화당 한 번 주입됩니다."

이 범주에서 마이그레이션의 이점이 드러납니다. Codex에서는 해당 디렉터리 내부 또는 하위에서 세션을 시작했기 때문에 중첩된 파일이 적용됩니다. 즉, 범위 지정(scoping)이 현재 위치의 부작용으로 발생합니다. 반면 paths 패턴은 세션이 어디서 시작되었는지와 관계없이 에이전트가 일치하는 파일을 실제로 터치할 때 적용됩니다. 이는 여러분이 표현하고자 했던 의도를 더 정확하게 구현한 버전입니다.

특정 작업에만 참인 것. 릴리스 체크리스트, 장애 대응 런북, 데이터 파이프라인 연결 방식에 대한 긴 설명 등이 이에 해당합니다. 이들은 이름과 설명이 있는 일반적인 스킬이 됩니다. 호출되기 전까지는 비용이 거의 들지 않으므로, 연결된 체인과 바이트 제한이라는 제약 조건 하에서 작업하던 것과 달리 필요한 만큼 길게 작성할 수 있습니다. 스킬로 이동할 때 염두에 두어야 할 한 가지 주의 사항은 agent skills are not memory라는 점입니다. 스킬은 에이전트가 호출할 수 있는 절차이지, 팀이 결정한 사항에 대한 기록이 아닙니다.

이름을 붙일 만한 네 번째 범주도 있습니다. 파일이 아닌 특정 문구에 의해 트리거되는 가이드입니다. OpenHands도 이를 지원합니다. triggers는 "사용자 메시지에 키워드나 명령이 나타날 때 스킬을 주입"하며, 모델 호출에도 계속 사용할 수 있습니다. 파일이 두 가지를 모두 선언하는 경우, 문서에서는 "paths가 우선권을 가집니다"라고 명시하고 있습니다.

2단계: 방향이 바뀌는 파일 이름 가정 수정하기

두 가지 세부 사항이 문제를 일으킬 수 있으며, 이들은 서로 반대 방향을 가리킵니다.

Codex는 표준이 아닌 명령 파일 이름을 등록하도록 요구합니다. 문서에 따르면 project_doc_fallback_filenames 목록에 없는 파일 이름은 "명령 탐색에서 무시됩니다." 리포지토리에 Codex가 읽는 CLAUDE.md가 있다면, 누군가 해당 목록에 추가했기 때문입니다.

OpenHands는 기본적으로 그 반대입니다. "OpenHands는 CLAUDE.md 및 GEMINI.md도 모델별 리포지토리 컨텍스트로 인식합니다." 등록할 필요가 없습니다. 즉, 무시하고 있었거나 Codex의 대체 목록에서 의도적으로 제외했던 CLAUDE.md가 마이그레이션 즉시 활성화된다는 의미입니다. 첫 실행 전에 확인해 보세요.

또 다른 세부 사항은 AGENTS.override.md. Codex는 이를 두 곳에서 사용합니다. 전역적으로 AGENTS.md보다 완전히 우선하는 경우와, 디렉터리별로 가장 먼저 확인하는 경우입니다. 이는 임시 로컬 동작을 위한 유용한 탈출구입니다. OpenHands의 스킬 문서에는 이러한 종류의 재정의 파일 이름이 설명되어 있지 않으므로, 트리 내의 모든 AGENTS.override.md는 대상 도구에서 읽지 않는 파일이 됩니다. 각 파일의 콘텐츠가 루트 AGENTS.md에 속하는지, 범위가 지정된 스킬에 속하는지, 아니면 어디에도 속하지 않는지 결정하세요.

레거시 파일에 대한 한 가지 참고 사항: OpenHands 문서에 따르면 "트리거가 없는 레거시 .md 스킬은 항상 전체가 로드됩니다"라며, 의도를 명확히 하기 위해 이 경우에는 AGENTS.md를 선호할 것을 권장합니다. 흩어져 있는 마크다운 파일들을 이식하는 경우, 이 문장을 기준으로 계획을 세워야 합니다. 트리거가 없는 단순 .md 스킬은 항상 활성화된 콘텐츠처럼 작동하므로, 마이그레이션하려던 원래의 문제 상황으로 돌아가게 됩니다. 명령 파일이 원래 CLAUDE.md로 시작되었다면, converting a CLAUDE.md into an AGENTS.md에서 이름 및 콘텐츠 차이점을 더 자세히 다룹니다.

위의 모든 작업은 구조 조정 작업이며, 하위 로딩 모델이 바뀔 때마다 이 작업을 반복해야 할 것입니다. Codex는 바이트 제한이 있는 연결 방식을 사용합니다. OpenHands는 점진적 공개 방식을 사용합니다. 다음 도구는 또 다른 방식을 사용할 것입니다.

이 모든 과정에서 살아남는 것은 추론(reasoning)입니다. 즉, 왜 그 규칙이 존재하는지, 어떤 대안을 거부했는지, 어떤 사건 때문에 그 규칙이 생겼는지에 대한 내용입니다. 이는 명령 파일에 편안하게 들어맞지 않습니다. 명령 파일은 명령 목록이며 두 플랫폼 모두에서 짧게 유지되어야 하기 때문입니다.

MemoryLake는 두 런타임 외부에서 해당 레이어를 유지하고, MCP 또는 API를 통해 요청하는 에이전트에 제공합니다. Codex는 자체 로컬 메모리를 유지하고 OpenHands는 스킬 카탈로그를 있는 그대로 유지합니다.

1단계: API 키 생성

파일을 분할하기 전에 약 30초 만에 키를 생성하고 첫 번째 요청을 수행해 보세요.

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

1단계에서 각 블록을 분류할 때 "이것이 왜 여기에 있는가"를 계속 자문하게 될 것입니다. 결정 사항, 거부한 대안, 그 이면의 제약 조건 등 답을 기록해 두세요. 문서 및 기타 파일도 같은 위치에 저장됩니다.

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

Claude, Codex, OpenClaw, OpenHands에 MCP 또는 API를 통해 액세스 권한을 부여하세요. 결정 레이어를 쿼리할 수 있는 에이전트는 항상 활성화된 파일에 근거를 인라인으로 포함할 필요가 없으므로, 두 벤더가 권장하는 대로 루트 AGENTS.md를 짧게 유지할 수 있습니다.

첫 번째 변화는 32 KiB 대화 제한이 끝난다는 점입니다. Codex의 제한에 도달한 팀에게는 한도를 늘리거나 중첩된 디렉터리로 분할하는 두 가지 문서화된 옵션이 있으며, 둘 다 리소스를 관리하는 방법입니다. OpenHands 측에서는 리소스 질문이 이동합니다. 루트 파일이 짧아야 하는 이유는 바이트 제한 때문이 아니라, 항상 활성화된 콘텐츠가 첫 번째 메시지부터 컨텍스트를 차지하기 때문입니다. 온디맨드로 쿼리되는 결정 레이어를 사용하면 추론을 잃지 않으면서도 짧은 파일을 짧게 유지할 수 있습니다.

두 번째 변화는 범위 지정이 더 명확해진다는 점입니다. paths 패턴은 "이 파일은 결제 디렉터리에 있습니다"보다 더 강력한 선언이며, 세션이 시작된 위치가 아니라 에이전트가 실제로 터치하는 파일에서 실행됩니다.

세 번째 변화는 중복 기간 동안 나타납니다. 대부분의 팀은 몇 주 동안 두 도구를 동시에 실행합니다. 두 개의 로딩 모델이 있는 두 개의 명령 트리는 한 에이전트가 다른 에이전트가 하지 않았을 행동을 하기 전까지는 아무도 눈치채지 못하는 방식으로 분기됩니다. 하나의 공유 결정 레이어를 사용하면 파일 레이아웃이 다르더라도 이유는 동일하게 유지됩니다.

복사하기 전에 루트 파일의 크기를 측정하세요. Codex 체인이 바이트 제한에 도달했다면, 그 중 얼마나 보편적으로 적용되는 내용이었는지 솔직하게 질문해 보아야 합니다. 대부분의 답은 "생각보다 적다"일 것입니다.

디렉터리 중첩을 선언된 패턴으로 변환하세요. OpenHands에서 Codex 디렉터리 레이아웃을 그대로 재현하고 동일한 동작을 기대하지 마세요. 중첩은 한쪽의 범위 지정 메커니즘이었고, paths 선언은 다른 쪽의 범위 지정 메커니즘입니다.

첫 실행 전에 CLAUDE.md 및 GEMINI.md가 있는지 감사(audit)하세요. 이 파일들은 등록이 필요한 상태에서 자동으로 인식되는 상태로 바뀝니다. 이는 대개 환영할 만한 일이지만 때로는 놀라운 일이 될 수도 있습니다.

모든 스킬에 적용 시점을 명시하는 설명을 부여하세요. 탐색 시에는 이름과 설명만 공개됩니다. 스킬이 무엇을 하는지 설명하지만 언제 사용해야 하는지 설명하지 않으면 적절한 시점에 호출되지 않습니다.

항상 활성화된 파일에 추론을 넣지 마세요. 두 벤더 모두 간결하게 유지하라고 조언합니다. 근거는 에이전트가 쿼리하는 저장소에 속해야 하며, 모든 메시지에서 로드되는 블록에 속해서는 안 됩니다.

긴 세션에서는 요약이 발생할 수 있음을 예상하세요. OpenHands는 최근 메시지를 그대로 유지하고 기록이 구성된 크기를 초과하면 이전 콘텐츠를 요약하는 컨텍스트 응축기(context condenser)를 문서화하고 있습니다. 이는 긴 대화를 관리하는 합리적인 방법이며, 대화를 기록 보관소로 취급해서는 안 되는 좋은 이유이기도 합니다.

Codex와 OpenHands는 이름이 같은 파일을 읽고 거의 정반대의 방식으로 처리합니다. Codex는 프로젝트 루트에서 작업 디렉터리까지 디렉터리당 하나의 파일씩 정렬된 체인을 바이트 제한에 도달할 때까지 연결합니다. OpenHands는 루트 파일을 전체 로드하고 다른 모든 것은 설명, 키워드 트리거 또는 경로 패턴 뒤에 보류합니다.

이 차이가 바로 마이그레이션의 핵심입니다. 콘텐츠는 그대로 이식되지만, 구조는 짧은 항상 활성화된 파일과 무제한의 온디맨드 세부 정보를 장려하는 로딩 모델을 중심으로 재구축되어야 합니다. 이 과정에서 서로 반대 방향을 가리키는 두 가지 파일 이름 문제와, 문서화된 상응물이 없는 하나의 탈출구인 AGENTS.override.md를 만나게 됩니다.

각 부분이 적용되는 빈도에 따라 체인을 분할하고, 중첩을 선언된 패턴으로 변환하며, 두 런타임 모두 소유하지 않는 곳에 추론을 보관하세요. 그러면 다음 로딩 모델은 고고학 프로젝트가 아니라 단순한 구조 조정 작업이 될 것입니다.