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

Copilot은 세 가지 유형의 리포지토리 커스텀 지시사항과 그 위아래로 두 개의 레이어를 더 문서화하고 있습니다.

리포지토리 수준의 세 가지:

"리포지토리 전체 커스텀 지시사항: 리포지토리 컨텍스트 내에서 이루어지는 모든 요청에 적용됩니다. 이는 리포지토리의 .github 디렉토리에 있는 copilot-instructions.md 파일에 지정됩니다."

"경로 특정 커스텀 지시사항: 지정된 경로와 일치하는 파일의 컨텍스트에서 이루어지는 요청에 적용됩니다. 이는 리포지토리의 .github/instructions 디렉토리 내부 또는 하위에 있는 하나 이상의 NAME.instructions.md 파일에 지정됩니다."

"에이전트 지시사항: 리포지토리 전체 커스텀 지시사항과 유사하지만, 현재 모든 Copilot 기능에서 지원되지는 않습니다. 이는 AGENTS.md, CLAUDE.md 또는 GEMINI.md라는 파일에 지정됩니다."

그 위에는 "GitHub.com의 Copilot Chat 페이지 팝업에서" 설정하며 "Copilot이 본인에게만 적용하는" 개인 지시사항이 있습니다. 그 아래에는 "Copilot Business 또는 Copilot Enterprise 구독을 보유한 조직의 조직 소유자만 설정할 수 있는" 조직 커스텀 지시사항이 있습니다.

우선순위 체인은 위에서 아래 순서로 문서화되어 있습니다: 개인 지시사항, 경로 특정 지시사항, 리포지토리 전체 지시사항, 에이전트 지시사항, 그리고 조직 지시사항 순입니다. 그리고 이 섹션에는 마이그레이션 계획 방식을 바꾸는 조항이 있습니다:

"여러 유형의 커스텀 지시사항이 Copilot에 전송되는 요청에 적용될 수 있습니다. 개인 지시사항이 가장 높은 우선순위를 가집니다. 그 다음은 리포지토리 지시사항이며, 조직 지시사항이 마지막으로 우선순위를 가집니다. 그러나 관련된 모든 지시사항 세트가 Copilot에 제공됩니다."

마지막 문장을 주의 깊게 읽어보세요. 우선순위는 충돌을 해결할 뿐, 어떤 것도 제외하지 않습니다. 관련된 모든 내용이 반영됩니다.

Factory의 모델은 의도적으로 더 좁은 범위를 가집니다. Factory의 AGENTS.md 문서는 특정 작업을 수행하는 하나의 파일을 설명합니다:

"AGENTS.md는 Droid가 모든 세션에 가져가야 할 프로젝트 브리핑을 제공합니다: 설치, 실행, 테스트, 편집, 검증 방법 및 리포지토리의 경계를 벗어나지 않는 방법 등입니다."

그리고 구조와 범위에 대해 명확히 규정하고 있습니다:

"리포지토리 루트에 AGENTS.md를 추가하세요. 하나의 파일로 시작한 다음, 패키지, 앱 또는 서비스에 다른 규칙이 필요한 경우에만 중첩된 파일을 추가하세요."

"Droid가 코드를 작성하기 전에 로드해야 하는 가이드라인으로 사용하세요. 짧고 구체적이며 검증하기 쉽게 유지하세요."

따라서 실제로 이전되는 것은 다음과 같습니다. 리포지토리 전체 파일은 거의 그대로 이전됩니다. Copilot의 에이전트 지시사항용으로 이미 AGENTS.md를 사용하고 있었다면, 이는 그대로 이전되어 이제 가장 낮은 우선순위가 아닌 가장 핵심적인 영역이 됩니다. 경로 특정 지시사항은 내용은 이전되지만 메커니즘이 변경됩니다. 그리고 개인 및 조직 지시사항은 복사할 대상이 없기 때문에 전혀 이전되지 않습니다. 하나는 본인에게 한정된 웹 팝업에 있고, 다른 하나는 회사에 한정된 조직 설정에 있기 때문입니다.

1단계: 파일이 아닌 두 개의 레이어를 수집하고 배치할 위치 결정하기

이 단계는 누락되기 쉬우므로 가장 먼저 수행해야 합니다.

개인 지시사항. GitHub.com의 Copilot Chat 페이지를 열고 팝업에 무엇이 있는지 확인하세요. 대부분의 팀에서 이 팝업은 두 가지 종류의 내용을 담고 있습니다: 순수한 개인적 선호도("한 줄에 하나의 개념만 설명하기", "항상 포르투갈어로 응답하기" — 문서의 실제 예시)와 프로젝트의 작동 방식을 설명하여 모든 팀원에게 필요하므로 애초에 개인 설정에 있어서는 안 되었을 규칙들입니다.

이 둘을 분리하세요. 개인적 선호도는 macOS 및 Linux의 ~/.factory/settings.json에 위치하는 Factory의 사용자 수준 설정(선택 사항인 settings.local.json과 함께)으로 가야 합니다. 개인 팝업에 숨겨져 있던 프로젝트 규칙은 리포지토리의 AGENTS.md로 이동하여 마침내 다른 팀원들과 공유되어야 합니다. 이는 보통 전체 마이그레이션에서 가장 가치 있는 결과물이며, 파일만 마이그레이션할 경우 놓치기 쉬운 부분입니다.

조직 지시사항. 이 지시사항은 관리자가 확인해 주어야 하며, Factory의 지시사항 영역에는 조직별로 대응되는 레이어가 문서화되어 있지 않더라도 캡처해 둘 가치가 있습니다. Copilot 자체 문서에 따르면 이들의 적용 범위가 제한되어 있습니다. 즉, "현재 GitHub.com의 Copilot Chat, GitHub.com의 Copilot 코드 리뷰, GitHub.com의 Copilot 클라우드 에이전트에서만 지원"됩니다. 따라서 조직 지시사항이 애초에 IDE 세션에 전혀 영향을 미치지 않았을 가능성도 큽니다. 이월할 분량을 결정하기 전에 이를 먼저 확인하세요.

모든 리포지토리에 진정으로 적용되는 내용은 사용자 수준 또는 프로젝트 수준의 .factory/ 구성 및 리포지토리 AGENTS.md로 이동합니다. IDE에 도달하지 않았던 단순 컴플라이언스 상투적 문구는 그 이유를 적어두고 제외해도 좋습니다.

2단계: Copilot이 미루게 했던 충돌을 해결하고 스코핑 재구성하기

Copilot은 관련된 모든 지시사항 세트를 제공하고 의견 불일치를 해결할 때만 우선순위를 사용하기 때문에, 팀은 서로 모순되는 두 개의 레이어를 가진 채로 1년 동안 운영하면서도 이를 전혀 알아차리지 못할 수 있습니다. 우선순위가 높은 레이어가 적용되고 낮은 레이어는 그냥 방치되기 때문입니다.

Factory의 가이드는 반대 방향으로 작동합니다. Factory의 AGENTS.md 문서는 "짧고 구체적이며 검증하기 쉬운" 규칙을 요구하며, 정확한 설치, 개발, 테스트, 타입 검사, 린트 및 빌드 명령을 가장 먼저 배치할 것을 권장하고, 무엇이 어디에 속해야 하는지 명확한 선을 긋습니다:

"사람을 위한 온보딩, 스크린샷, 기여자 배경 지식은 README.md에 보관하세요. Droid 전용 명령, 가드레일, 완료 기준은 AGENTS.md에 작성하세요."

또한 Copilot 형식에서는 요구하지 않는 것, 즉 Droid가 작업을 완료했다고 판단하기 전에 필요한 증명을 명시하는 검증(verification) 섹션을 요구합니다. 문서는 Droid의 작동 방식을 바꾸는 구체적인 규칙과 "확인할 수 없는 모호한 규칙"을 대조합니다. 만약 여러분의 copilot-instructions.md에 "좋은 코드 작성하기"와 같은 줄이 포함되어 있다면, 이 단계는 이를 포팅하는 대신 삭제해야 하는 시점입니다.

따라서 명령어를 가장 먼저 작성한 다음, 리포지토리 맵, 컨벤션, 테스트 규칙, 생성 파일 규칙, 보안 경계, 검증 단계를 포함하는 하나의 루트 AGENTS.md를 작성하세요. 두 개의 기존 레이어가 충돌하는 경우 하나를 선택해야 합니다. 이 결정은 실제 작업이며, Copilot의 우선순위 체인이 대신 흡수해 주던 작업입니다. 이미 Copilot 파일과 함께 CLAUDE.md를 유지하고 있다면, CLAUDE.md를 Copilot의 지시사항 형식으로 변환하기 글에서 이러한 통합 과정에서 살아남는 경향이 있는 것과 그렇지 않은 것을 다룹니다. 그리고 새 파일의 길이를 결정하기 전에 코딩 에이전트가 실제로 읽는 것 글을 한 번 읽어볼 가치가 있습니다.

그 다음 경로 특정 파일을 처리합니다. Copilot의 .github/instructions/NAME.instructions.md 파일은 파일 패턴을 대상으로 하며, 문서는 이 파일들이 존재하는 이유를 다음과 같이 설명합니다: "경로 특정 지시사항을 사용하면 특정 유형의 파일이나 특정 디렉토리에만 적용되는 정보로 리포지토리 전체 지시사항이 과부하되는 것을 방지할 수 있습니다."

그 목적은 유지되지만 메커니즘이 변경됩니다. Factory는 중첩된 AGENTS.md 파일의 범위를 디렉토리별로 제한합니다. 즉, "패키지, 앱 또는 서비스에 다른 규칙이 필요한 경우에만 중첩된 파일을 추가"합니다. 디렉토리 범위의 규칙은 깔끔하게 포팅됩니다. 해당 디렉토리에 AGENTS.md를 배치하면 됩니다. 전체 트리에서 특정 파일 유형으로 범위가 지정된 규칙은 상주할 디렉토리가 없으므로 두 가지 솔직한 옵션이 있습니다. 해당 파일 유형이 특정 영역에 집중되어 있다면 그곳에 배치하세요. 리포지토리 전체에 걸쳐 있다면 규칙의 첫 번째 문장에 범위를 명시하고, 이제 매칭 방식이 아닌 명시 방식으로 처리됨을 수용하세요.

리포지토리에 있는 동안 확인해야 할 사항이 하나 더 있습니다. .droid.yaml을 발견했다면 이는 더 이상 사용되지 않는(deprecated) 영역입니다. Factory의 설정 문서에 따르면 대신 현재의 .factory/ 파일을 사용하고, "리포지토리 지시사항, 컨벤션 및 검증 명령에는 AGENTS.md를 사용"하라고 명시되어 있습니다."

위의 두 단계는 번역 작업과 일련의 결정들로 이루어집니다. 결정은 비용이 많이 드는 부분이며, 현재로서는 마이그레이션 중에 이를 결정한 사람의 머릿속에만 존재합니다.

이것이 바로 영구적인 곳에 보관할 가치가 있는 레이어입니다. 개인 지시사항과 리포지토리 지시사항 간의 충돌을 해결할 때, 여러분은 프로젝트가 실제로 어떤 컨벤션을 따르는지 결정했습니다. "좋은 코드 작성하기"를 삭제했을 때, 그것이 검증 불가능하다고 판단한 것입니다. 지금으로부터 6개월 후, 누군가는 살아남은 규칙을 발견하고 왜 그렇게 작성되었는지 의문을 가질 것입니다.

MemoryLake는 이러한 결정을 두 제품 외부에서 유지하고, MCP 또는 API를 통해 요청하는 모든 에이전트에 제공합니다. Copilot 자체 메모리 기능과 Factory 자체 구성은 있는 그대로 유지되며 벤더가 문서화한 방식대로 계속 작동합니다.

1단계: API 키 생성하기

키를 생성하고 약 30초 만에 첫 번째 요청을 완료하세요. 위의 2단계를 시작하기 전에 이 작업을 수행하여 결정을 내릴 때마다 기록할 공간을 마련해 두세요.

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

해결한 모든 충돌은 보관할 가치가 있는 메모리입니다: 어떤 규칙이 채택되었고, 어떤 규칙이 탈락했으며, 그 이유는 무엇인지 기록하세요. 특정 장애 상황에서 도출된 규칙이나 의도적으로 사용하지 않는 라이브러리 또는 패턴을 추가하세요. 문서 및 기타 지원 파일도 동일한 위치에 저장됩니다.

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

Claude, Codex, OpenClaw 및 Droid에 MCP 또는 API를 통해 액세스 권한을 부여하세요. 연결이 완료되면 "왜 이것이 컨벤션인가"라는 질문에 그 이유가 함께 답변되므로, 루트 AGENTS.md를 Factory가 권장하는 만큼 짧게 유지할 수 있습니다.

첫 번째 변화는 개인 지시사항 문제가 더 이상 재발하지 않는다는 점입니다. 한 사람의 팝업에 숨겨져 있던 프로젝트 규칙이 리포지토리에 반영되고 추론 과정이 공유 저장소에 보관되면, 팀의 규칙보다 조용히 우선시되는 비공개 레이어가 더 이상 존재하지 않게 됩니다.

두 번째는 Spec Mode에 관한 것으로, 이는 Factory가 가장 가치 있는 결과물을 생성하는 곳이자 지속성 격차가 존재하는 곳이기도 합니다. Spec Mode는 승인을 요청하며 종료되는 읽기 전용 계획 단계로, 이 모드에 있는 동안 Droid는 "파일을 편집하거나, 구성을 변경하거나, 커밋을 생성하거나, 서비스를 시작하거나, 외부 시스템에 쓰기 작업을 수행해서는 안 됩니다." 이 모드가 생성하는 계획은 정확히 적절한 시점에 기록된 변경에 대한 추론입니다. 그러나 기본 저장 위치는 리포지토리 외부의 사용자별 디렉토리인 ~/.factory/specs입니다. 이는 합리적인 기본값이지만 specSaveDir을 통해 구성할 수 있습니다. 또한 훌륭한 계획이 한 사람의 노트북에만 존재하고 다른 곳에는 존재하지 않게 되는 이유이기도 합니다. specSaveDir이 커밋된 위치를 가리키도록 설정하거나, 결론을 공유 저장소로 이동하는 습관을 들이세요.

세 번째 변화는 다음 도구 마이그레이션 시점에 나타납니다. 지시사항 파일은 다시 작성될 것입니다. 이는 피할 수 없는 일이며 도구마다 형식이 조금씩 다르기 때문입니다. 하지만 그 뒤에 숨겨진 결정 사항들은 누구의 지시사항 형식에도 종속되어 있지 않았기 때문에 다시 작성할 필요가 없습니다.

파일을 건드리기 전에 개인 지시사항 팝업을 먼저 읽어보세요. 이는 가장 높은 우선순위와 가장 낮은 가시성을 가진 레이어이며, 그 안의 일부 내용은 팀 전체에 공유되어야 합니다.

관리자에게 조직 지시사항을 요청한 다음, 실제로 적용된 적이 있는지 확인하세요. Copilot 문서는 이들의 지원 범위를 특정 영역으로 제한합니다. IDE에 도달하지도 않은 규칙을 이월하는 것은 불필요한 작업입니다.

검증할 수 없는 내용은 포팅하는 대신 삭제하세요. Factory 문서는 확인할 수 있는 규칙을 요구하며, 모호한 규칙과 대조합니다. 아무도 검증할 수 없는 규칙은 Copilot에서도 아무런 역할을 하지 못했습니다.

명령어를 가장 먼저 배치하세요. 설치, 실행, 테스트, 타입 검사, 린트, 빌드 순입니다. Factory 자체 단계 순서에서도 이를 권장하며, 이는 첫 세션부터 밥값을 톡톡히 하는 지시사항 파일의 핵심 부분입니다.

검증 섹션을 작성하세요. Droid가 작업을 완료했다고 판단하기 전에 필요한 증명을 명시하세요. Copilot의 지시사항 형식에서는 이를 요구하지 않았으므로 아직 작성되어 있지 않을 가능성이 큽니다.

첫날에 스펙(specs)이 저장될 위치를 결정하세요. 기본값은 리포지토리 외부의 사용자별 디렉토리입니다. specSaveDir이 공유된 위치를 가리키도록 설정하거나, 추론 내용을 수동으로 이동하세요.

Copilot에서 Factory Droid로의 마이그레이션은 파일 복사 작업과 파일이 아닌 두 가지 요소를 처리하는 작업입니다. 개인 지시사항은 GitHub.com의 팝업에 존재하며 다른 모든 것보다 우선합니다. 조직 지시사항은 회사 설정에 존재하며, Copilot 자체 문서에 따르면 특정 영역에만 도달합니다. 둘 다 무언가를 복사하는 방식으로는 마이그레이션할 수 없으며, 첫 번째 지시사항에는 대개 비공개로 유지되어서는 안 되었을 프로젝트 규칙이 포함되어 있습니다.

작업의 나머지 절반은 Copilot의 우선순위 체인이 흡수하고 있던 충돌을 해결하는 것입니다. 관련된 모든 지시사항 세트가 제공되고 우선순위는 의견 불일치를 해결할 때만 사용되기 때문에, 모순이 오랫동안 감지되지 않은 채 방치될 수 있습니다. Factory는 구체적이고 확인 가능한 규칙이 담긴 하나의 짧은 루트 파일을 요구하므로, 누군가는 실제로 최종 규칙을 선택해야 합니다.

파일이 아닌 두 개의 레이어를 먼저 처리하고, 충돌을 신중하게 해결하며, 스펙이 저장될 위치를 결정하고, 어떤 지시사항 형식에도 얽매이지 않는 곳에 추론 과정을 보관하세요.