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

콘텐츠는 전송되지만, 구조는 전송되지 않습니다. Kiro의 워크스페이스 steering은 .kiro/steering/에, 글로벌 steering은 ~/.kiro/steering/에 일반 .md 파일로 저장됩니다. Codex는 AGENTS.md 파일을 읽습니다. 텍스트 본문은 수정 없이 그대로 이동하지만, 어디에 배치할지가 핵심 질문입니다.

디렉터리당 하나의 파일이라는 제약 조건이 지배적입니다. Codex의 탐색 방식은 다음과 같습니다. "프로젝트 루트(일반적으로 Git 루트)에서 시작하여 현재 작업 디렉터리까지 내려가며 탐색합니다... 경로상의 각 디렉터리에서 AGENTS.override.md를 확인한 다음 AGENTS.md를 확인하고, 그 다음 project_doc_fallback_filenames에 지정된 대체 이름을 확인합니다. Codex는 디렉터리당 최대 하나의 파일만 포함합니다."

하나의 경로에 있는 6개의 steering 파일은 최대 하나의 파일이 됩니다. 이를 단일 루트 AGENTS.md로 병합하거나, 해당 지침이 적용되는 코드가 있는 디렉터리로 분산시켜야 합니다. 그리고 후자가 바로 Codex 모델이 설계된 방식입니다.

글로벌 steering은 첫 번째 파일 규칙에 따라 매핑됩니다. Codex의 홈 디렉터리에서 "Codex는 AGENTS.override.md가 존재하면 이를 읽습니다. 그렇지 않으면 AGENTS.md를 읽습니다. Codex는 이 수준에서 비어 있지 않은 첫 번째 파일만 사용합니다." 따라서 개인적인 규칙을 담은 ~/.kiro/steering/ 디렉터리는 정확히 ~/.codex/AGENTS.md라는 하나의 파일이 됩니다. override 파일은 임시 전환 시 유용합니다. "기본 파일을 삭제하지 않고 임시로 글로벌 재정의가 필요할 때 ~/.codex/AGENTS.override.md를 사용하세요."

병합 순서가 명시되어 있으며, 이는 일부 사람들이 생각하는 것과 반대입니다. "Codex는 루트에서부터 아래로 파일을 연결하며, 빈 줄로 구분하여 결합합니다. 현재 디렉터리에 더 가까운 파일은 결합된 프롬프트에서 더 나중에 나타나기 때문에 이전의 지침을 재정의합니다." 나중에 나오는 것이 이깁니다. 이는 구체적인 것이 일반적인 것을 이긴다는 Kiro의 직관과 깔끔하게 일치하지만, 우선순위 규칙이 아니라 결합된 프롬프트에서의 위치를 통해 달성됩니다.

Kiro의 4가지 inclusion 모드 중 어느 것도 Codex와 호환되는 기능이 없습니다. 이는 실질적인 손실이므로, 무엇을 포기하게 되는지 나열해 볼 가치가 있습니다.

inclusion: always는 기본값이며 직접 매핑됩니다. 이 파일들은 Kiro에서 무조건적이었고 Codex에서도 무조건적으로 유지됩니다.

inclusion: fileMatch와 fileMatchPattern은 "지정된 패턴과 일치하는 파일로 작업할 때만" 파일을 로드하며, 문서에서는 그 이유를 명확히 설명합니다. "이는 필요한 경우에만 전문화된 가이드를 로드하여 컨텍스트의 관련성을 유지하고 노이즈를 줄입니다." Codex에는 패턴 트리거 로딩 기능이 없습니다. fileMatch 파일은 항상 로드되거나 전혀 로드되지 않는 파일이 됩니다.

inclusion: manual 파일은 "채팅 메시지에서 #steering-file-name으로 참조하여 온디맨드로 사용할 수 있으며", "슬래시 명령어로도 표시됩니다." Codex에는 온디맨드 지침 첨부 기능이 없습니다.

이름과 설명을 사용하는 관련성 기반 모드인 inclusion: auto 역시 제공되지 않습니다.

Kiro는 이러한 모드가 존재하는 이유를 명확히 밝히고 있습니다. 즉, "성능을 최적화하고 필요할 때 관련 컨텍스트를 사용할 수 있도록" 돕기 위함입니다. 이를 제거한다는 것은 유지하는 모든 지침에 대해 매 실행마다 비용(컨텍스트)을 지불해야 함을 의미합니다.

AGENTS.md는 Kiro 내부에서도 이미 Codex처럼 작동합니다. Kiro는 이 표준을 지원하며, 문서화된 한 가지 차이점이 있습니다. "AGENTS.md 파일은 inclusion 모드를 지원하지 않으며 항상 포함됩니다." Kiro 설정의 일부가 이미 AGENTS.md에 있다면, 그 부분은 그대로 복사하면 되며 이미 무조건적인 로딩 방식을 경험하고 계신 것입니다.

바이트 제한은 아무도 예상하지 못하는 실패 모드입니다. "Codex는 빈 파일을 건너뛰고, 결합된 크기가 project_doc_max_bytes(기본값 32 KiB)로 정의된 제한에 도달하면 파일 추가를 중단합니다." 그냥 중단됩니다. 경고도 없습니다. 문서에 명시된 해결책은 두 가지 모두 사용 가능합니다. "제한을 늘리거나, 제한에 도달했을 때 중첩된 디렉터리에 지침을 분할하세요."

이제 이 두 가지 사실을 결합해 보십시오. Kiro 사용자는 일반적으로 유사한 Codex 설정보다 전체 steering 텍스트가 더 많습니다. inclusion 모드 덕분에 많은 양을 저렴하게 유지할 수 있었기 때문입니다. 이를 무조건 로드되는 파일로 평탄화하면 32 KiB 제한은 생각보다 훨씬 빨리 찾아옵니다. 이는 Codex가 AGENTS.md 규칙을 건너뛰는 이유의 이면에 있는 것과 동일한 종류의 소리 없는 누락 현상입니다.

Spec은 전송되지 않습니다. Kiro의 spec은 구조화된 산출물입니다. 모든 spec은 .kiro/specs/<name>/ 아래에 requirements.md, design.md, tasks.md를 생성하여 사용자 스토리, 아키텍처 및 개별 구현 태스크를 추적합니다. Codex에는 이를 수용할 spec 시스템이 없습니다. 파일은 마크다운 형식이므로 원하는 경우 리포지토리에 유지할 수 있지만, 에이전트가 진행 상황을 추적하는 활성 산출물의 역할은 중단됩니다.

클라우드 steering에는 알아둘 만한 제한이 있습니다. 웹에서 Kiro를 사용한 경우, "'글로벌 steering'은 클라우드 샌드박스가 읽을 수 없는 로컬 ~/.kiro/steering/ 디렉터리를 가리킵니다." 이것이 Kiro가 클라우드 세션을 위해 Configuration Sync를 제공하는 이유입니다. Codex의 글로벌 파일은 Codex를 실행하는 머신에 존재하므로, 실행하는 위치에 따라 동일한 종류의 문제가 적용됩니다.

1단계: 주제가 아닌 위치별로 구조 재구성하기

모든 것을 하나의 루트 AGENTS.md로 병합하려는 본능을 억제하십시오. 그것은 가장 빠른 방법이지만 바이트 제한으로 직행하는 길입니다.

대신, 지침이 적용되는 위치에 따라 steering 파일을 분류한 다음, 각 파일을 해당 지침이 제어하는 디렉터리에 배치하십시오. fileMatchPattern이 "app/api/**/*"였던 steering 파일은 app/api/AGENTS.md가 됩니다. "src/components/**/*" 범위로 지정된 파일은 src/components/AGENTS.md가 됩니다. Codex의 자체 권장 사항도 이와 일치합니다. "Codex는 현재 디렉터리에 도달하면 검색을 중단하므로, 재정의 파일을 전문 작업에 최대한 가까운 곳에 배치하십시오."

이렇게 하면 fileMatch가 수행하던 역할의 상당 부분을 복구할 수 있습니다. 전부는 아닙니다. Codex는 에이전트가 읽는 파일이 아니라 작업 디렉터리를 기준으로 트리거되기 때문입니다. 하지만 app/api에서 작업하는 개발자는 컴포넌트 가이드가 아닌 API 가이드를 받게 되며, 이것이 바로 핵심 목적이었습니다.

진정으로 범용적인 콘텐츠의 경우, 하나의 루트 AGENTS.md를 유지하고 짧게 작성하십시오. 기술 스택, 코딩 규칙, 빌드 및 테스트 명령 등이 이에 해당합니다. inclusion: always 파일만 여기로 이동하고 다른 것은 제외하십시오.

중첩된 디렉터리가 상위 지침을 확장하는 대신 대체해야 하는 경우, 해당 디렉터리에서 AGENTS.override.md를 사용하십시오. Codex는 이를 먼저 확인하고 형제 AGENTS.md 대신 채택합니다.

두 가지 실용적인 참고 사항이 있습니다. 리포지토리에서 이미 다른 파일 이름을 사용하고 있다면 이름을 바꾸는 대신 등록하십시오. ~/.codex/config.toml에 project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]를 설정하면 Codex가 이를 지침 파일로 처리합니다. 문서에서는 "이 목록에 없는 파일 이름은 지침 탐색에서 무시됩니다"라고 경고합니다. 또한 GitHub에서 Codex 코드 리뷰를 사용하는 경우, 리뷰 규칙은 "규칙이 제어하는 코드에 가장 가까운 AGENTS.md"의 ## Code Review Rules 섹션에 속해야 합니다.

2단계: manual 및 auto 파일의 처리 방식을 결정하고 결과 측정하기

inclusion: manual 및 inclusion: auto 파일은 갈 곳이 없는 파일들입니다. 이 파일들은 트러블슈팅 가이드, 마이그레이션 절차, "가끔씩만 필요한 컨텍스트가 많은 문서"였습니다. 이는 manual 모드가 가장 적합한 용도에 대한 Kiro 자체의 설명이기도 합니다.

여기에는 세 가지 정직한 옵션과 한 가지 나쁜 옵션이 있습니다. 무조건 로드되도록 승격하고 매 실행마다 비용을 지불할 수 있습니다. 중첩된 디렉터리에 배치하여 누군가 해당 디렉터리에서 작업할 때만 로드되도록 할 수 있습니다. 에이전트가 요청받을 때 읽는 일반 리포지토리 문서로 남겨둘 수 있으며, 이는 원래 동작에 가장 가깝습니다. 나쁜 옵션은 이들을 루트 파일에 병합하는 것입니다. 이 경우 32 KiB 제한에 도달하여 실제로 필요한 지침을 잃기 시작하게 됩니다.

그런 다음 검증하십시오. Codex 문서에 정확한 방법이 나와 있으며, 구조 재구성 후 이 단계를 건너뛰어서는 안 됩니다.

리포지토리 루트에서 codex --ask-for-approval never "Summarize the current instructions."를 실행하여 글로벌 및 프로젝트 파일이 우선순위 순서대로 나타나는지 확인하십시오. 중첩된 재정의가 더 광범위한 규칙을 대체하는지 확인하려면 codex --cd subdir --ask-for-approval never "Show which instruction files are active."를 실행하십시오. 전체 감사를 원하시면 codex -c log_dir=./.codex-log를 사용하여 일반 텍스트 TUI 로그를 활성화하고 ./.codex-log/codex-tui.log를 확인하십시오.

이 작업이 생각보다 수월한 데는 두 가지 이유가 있습니다. 씨름해야 할 캐시가 없습니다. "Codex는 매 실행 시(그리고 각 TUI 세션이 시작될 때) 지침 체인을 다시 빌드하므로 수동으로 지워야 할 캐시가 없습니다." 또한 지침이 잘린 것처럼 보이면 문서에서 해결책을 직접 제시합니다. project_doc_max_bytes를 늘리거나 중첩된 디렉터리에 분할하십시오.

설정하는 동안 Codex 자체의 memory 레이어에 대해서도 별도로 결정하십시오. 이 레이어는 존재하며 기본적으로 비활성화되어 있고, 그 자체의 동작 방식을 이해할 가치가 있습니다. Codex의 로컬 메모리 켜기에서 보관 대상과 제어 방법을 다룹니다.

위의 모든 과정은 실제 구조 재구성 작업이며, 이로 인해 Kiro가 강요하지 않았던 절충안을 선택해야 합니다. 즉, 매 실행마다 로드할 가치가 있는 지침이 무엇인지 결정해야 합니다.

이러한 절충이 필요한 유일한 이유는 지침(instructions)과 사실 정보(facts)가 같은 장소에 저장되기 때문입니다. 지침은 짧고 행동 지향적입니다. 예를 들어 "여기서 make test-payments를 실행하십시오", "보안 부서에 알리지 않고 키를 교체하지 마십시오" 등이 있습니다. 반면 사실 정보는 길고 참조용입니다. 예를 들어 API 경로에 버전이 지정된 이유, 내부 용어의 의미, 특정 대기열을 소유한 서비스 등이 있습니다. Kiro는 inclusion 모드 덕분에 사실 정보를 저렴하게 유지할 수 있었기 때문에 steering에 두 가지 모두를 보관할 수 있게 해주었습니다. 하지만 Codex는 32 KiB 한도 내에서 매 실행마다 이에 대한 비용을 청구합니다.

이 둘을 분리하면 한도는 더 이상 중요하지 않습니다. AGENTS.md 파일은 작고 행동 지향적인 상태를 유지하며, 사실 정보는 질문이 발생할 때 에이전트가 읽는 저장소에 보관됩니다. MemoryLake는 3단계로 설정할 수 있습니다.

1단계: API 키 생성

로그인하고 대시보드에서 API 키를 생성합니다. 이는 지침 체인의 일부가 아니므로, 여기에 보관된 내용은 project_doc_max_bytes 제한에 포함되지 않으며 중첩된 디렉터리에 복제할 필요도 없습니다.

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

여기가 바로 manual 및 auto steering 파일이 있어야 할 곳입니다. 트러블슈팅 절차, 아키텍처 결정 및 그 배경 이유, 도메인 어휘, 마이그레이션 런북, 리뷰에서 계속 반복하는 답변 등이 이에 해당합니다.

행동 지침은 AGENTS.md에 유지하십시오. 명령, 규칙, 그리고 매 실행마다 적용되어야 하는 규칙들이 바로 지침 체인이 존재하는 목적입니다.

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

Codex가 저장소를 가리키도록 설정하십시오. 가끔 필요한 가이드는 상주하지 않고도 사용할 수 있게 되며, 루트 파일은 제한 이하로 여유롭게 유지되고, 항상 적용되어야 하는 가이드는 실제로 준수할 수 있을 만큼 짧아집니다. 이것이 바로 에이전트가 지침 파일을 무시하는 이유의 핵심입니다.

첫 번째 변화는 32 KiB가 더 이상 설계 제약 조건이 되지 않는다는 점입니다. 현재는 에이전트가 알기를 원하는 모든 사실 정보가 에이전트가 따르기를 원하는 모든 지침과 하나의 예산 내에서 경쟁하고 있습니다.

두 번째는 inclusion 모드를 잃는 비용이 줄어든다는 점입니다. fileMatch는 디렉터리 배치를 통해 부분적으로 복구할 수 있지만, manual 및 auto는 불가능합니다. 저장소를 사용하는 것이 항상 로드되는 파일보다 "온디맨드 사용 가능"이라는 개념에 훨씬 더 가깝습니다.

세 번째는 spec이 더 이상 쓸모없는 파일로 남지 않는다는 점입니다. Kiro의 requirements.md, design.md, tasks.md에는 실제 결정 사항과 추론 과정이 담겨 있습니다. Codex에는 이를 추적하는 기능이 없지만, 그 안의 결정 사항들은 프로젝트 문서를 AI 메모리로 전환하기에서 주장한 바와 같이 읽기 가능한 상태로 유지할 가치가 있는 지속적인 지식입니다.

• 병합하지 말고 분산시키십시오. Codex는 디렉터리당 최대 하나의 파일만 포함하므로, 지침을 해당 지침이 제어하는 디렉터리에 배치하십시오.
• 루트 파일을 짧게 유지하십시오. inclusion: always에 해당하는 내용만 여기에 속합니다.
• fileMatch를 위치로 변환하십시오. app/api/**/* 패턴은 app/api/AGENTS.md가 됩니다.
• 확장이 아닌 대체를 위해 AGENTS.override.md를 사용하십시오. Codex는 동일한 디렉터리에서 AGENTS.md보다 이를 먼저 확인합니다.
• 이름을 바꾸는 대신 대체 파일 이름을 등록하십시오. project_doc_fallback_filenames를 설정하면 Codex가 이를 읽으며, 목록에 없는 이름은 무시됩니다.
• 제한을 의식적으로 모니터링하십시오. 기본적으로 32 KiB인 project_doc_max_bytes에 도달하면 경고 없이 로드가 중단됩니다. 제한을 늘리거나 분할하십시오.
• 문서화된 명령어로 검증하십시오. codex --ask-for-approval never "Summarize the current instructions." 및 --cd subdir 변형 명령어를 사용하고, 감사를 위해 TUI 로그를 확인하십시오.
• spec을 그대로 이식하려고 하지 마십시오. 파일은 문서로 유지하고, 그 안의 결정 사항들을 에이전트가 실제로 접근할 수 있는 곳으로 추출하십시오.

Codex의 지침 모델은 의도적으로 Kiro보다 단순합니다. 트리를 탐색하고, 디렉터리당 하나의 파일을 가져와 병합하며, 32 KiB에서 멈춥니다. 단순함은 기능이며, 이는 마이그레이션이 주로 지리적 배치 문제임을 의미합니다. 즉, 각 지침을 해당 지침이 제어하는 코드가 있는 곳에 배치하면 됩니다.

유지되지 않는 것은 조건부 로딩이며, 이는 나중에 발견하기보다 미리 계획해야 하는 부분입니다. 가능한 한 분산시키고, Codex가 제공하는 명령어로 검증하며, 가끔 참조하는 자료는 매 실행마다 비용을 지불하지 않는 곳으로 이동하십시오.