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

모든 CLAUDE.md 파일이 변경 없이 그대로 이전됩니다. Augment의 규칙 문서에는 Auggie가 로드하는 파일이 "다음 우선순위 순서대로" 나열되어 있습니다:

1. 커스텀 규칙 파일 (--rules 플래그 사용), 2. CLAUDE.md, 3. AGENTS.md, 4. 워크스페이스 가이드라인 (.augment-guidelines), 5. 워크스페이스 규칙 폴더 (<workspace_root>/.augment/rules/), 6. 사용자 규칙 폴더 (~/.augment/rules/)

두 가지가 눈에 띕니다. CLAUDE.md가 AGENTS.md보다 높은 순위를 차지하는데, 이는 다른 여러 에이전트가 사용하는 순서와 반대입니다. 또한 두 외부 파일 이름 모두 Augment의 기본 규칙 디렉터리보다 높은 순위를 차지하며, 사용자 수준 디렉터리가 가장 마지막에 위치합니다.

중첩된 CLAUDE.md 파일이 이전되며 범위 지정도 유지됩니다. Claude Code는 트리 아래의 CLAUDE.md 파일을 탐색하고 "발견된 모든 파일은 서로를 덮어쓰는 대신 컨텍스트에 병합된다"고 명시하며, "파일 시스템 루트부터 작업 디렉터리까지" 정렬되므로 "Claude를 실행한 위치와 가까운 지침이 가장 마지막에 읽힙니다."

Augment도 구조적으로 유사하지만 다르게 트리거되는 방식을 사용합니다. 문서에서는 계층적 규칙을 다음과 같이 설명합니다. "파일 작업을 할 때 Augment는 해당 파일의 디렉터리에서 AGENTS.md 및 CLAUDE.md를 찾습니다." 그런 다음 "디렉터리 트리를 거슬러 올라가며 각 상위 디렉터리에서 이 파일들을 확인"하고, "발견된 모든 규칙은 해당 작업 세션의 컨텍스트에 포함됩니다." 이 탐색은 "워크스페이스 루트에서 멈춥니다." 또한 규칙은 "중복 포함을 방지하기 위해 대화 세션별로 캐싱됩니다."

따라서 src/frontend/CLAUDE.md와 src/backend/CLAUDE.md가 있는 모노레포는 예상대로 작동합니다. src/frontend/에서 작업이 발생하면 해당 파일과 상위 파일들이 로드되고, 백엔드 파일은 로드되지 않습니다.

임포트(Imports)는 이전되지 않습니다. Claude Code는 CLAUDE.md 내부에서 @path 임포트를 지원하며, 문서에는 다음과 같은 미묘한 차이가 명시되어 있습니다. "임포트 파싱은 마크다운 코드 스팬 및 펜스 코드 블록을 건너뜁니다." 따라서 백틱으로 감싸진 @README는 문자 그대로 유지됩니다. 반면 Augment의 규칙 문서는 선택적 YAML 프론트매터(frontmatter)가 포함된 일반 마크다운 파일을 설명하며 임포트 구문을 지원하지 않습니다. 마이그레이션된 CLAUDE.md 내의 모든 @path 라인은 텍스트로 처리되어야 하므로, 이를 사용하기 전에 임포트된 콘텐츠를 파일 내에 직접 병합(flatten)해야 합니다.

한 가지 규칙 유형은 CLI에서 지원되지 않습니다. Augment의 워크스페이스 규칙은 문서에 명시된 두 가지 값인 always_apply 및 agent_requested를 type 필드로 가지며, IDE 익스텐션은 세 번째 값을 노출합니다. CLI 페이지에서는 이 차이를 명확히 설명합니다:

"수동(Manual) 규칙은 CLI에서 지원되지 않습니다. <workspace_root>/.augment/rules/에 있는 type: manual 규칙은 CLI에서 건너뜁니다. 필요할 때 첨부할 수 있는 @-멘션 메커니즘이 없기 때문입니다."

IDE 측 페이지에서도 이를 반복합니다. Manual은 "IDE 전용이며, @ 멘션을 통해 필요할 때 첨부되고 CLI에서는 건너뜁니다." 팀이 두 환경을 모두 사용하는 경우, 수동 규칙은 에디터에서는 활성화되지만 터미널에서는 누락됩니다.

사용자 수준 규칙은 프론트매터를 잃게 됩니다. Augment 문서에 따르면 "~/.augment/rules/에 있는 사용자 규칙은 항상 always_apply로 처리되며 다른 프론트매터 유형을 지원하지 않습니다." 홈 디렉터리에 넣는 모든 것은 프론트매터의 내용과 관계없이 모든 프로젝트의 모든 세션에서 활성화됩니다.

자동 메모리(Auto memory)는 이전되지 않습니다. Claude Code에는 두 가지 지속성 시스템이 있으며, 문서에서는 이를 상호 보완적인 것으로 설명합니다. 사용자가 작성하는 CLAUDE.md 파일과, 프로젝트별로 ~/.claude/projects/<project>/memory/에 저장되어 "매 세션마다 주입되는(첫 200행 또는 25KB) 사용자의 수정 사항 및 선호도를 바탕으로 Claude가 직접 작성하는 노트"인 자동 메모리입니다. Augment에도 메모리 시스템이 있지만 다른 방식입니다. Cosmos Experts는 "공유 가상 파일 시스템(VFS)에 범위가 지정된 지식을 저장"하며, Expert의 메모리는 "해당 팀에 속합니다." 그리고 단순(simple) 모델과 노이즈(noisy) 모델 두 가지가 문서화되어 있습니다. 두 시스템은 서로의 파일을 읽지 못합니다. Cosmos 측면은 steering what Augment's Experts remember에서 별도로 다루었으며, 이 가이드는 수명 주기가 다른 별도의 메커니즘인 지침(instruction) 레이어에 관한 것입니다.

1단계: CLAUDE.md를 신뢰할 수 있는 단일 소스(authoritative)로 유지할지 결정하고 이를 준수하기

두 가지 일관된 옵션이 있으며, 실패하는 경우는 둘 다 선택하지 않는 것입니다.

옵션 A: CLAUDE.md 유지하기. 이 파일은 우선순위 2위이며 잘 작동하고, 아직 전환하지 않은 사람들을 위해 Claude Code가 리포지토리를 계속 읽을 수 있도록 유지합니다. 단점은 단일 CLAUDE.md 파일에는 프론트매터나 파일 경계가 없기 때문에, 규칙별 type 프론트매터나 독립적으로 검토할 수 있는 규칙별 파일과 같은 Augment의 기본 기능을 사용할 수 없다는 점입니다.

옵션 B: .augment/rules/로 변환하기. 규칙당 하나의 파일을 갖게 되며 각 파일은 자체 type을 가집니다. 이는 두 도구 모두에서 조건부 로드에 가장 가까운 방식입니다. 단점은 아무도 예상하지 못한 부분에서 발생하며, 이는 별도의 단락으로 다룰 가치가 있습니다.

Augment의 계층적 탐색은 정확히 두 개의 파일 이름만 지원합니다. 문서에는 다음과 같이 명시되어 있습니다. "오직 AGENTS.md 및 CLAUDE.md 파일만 계층적으로 탐색됩니다." 그리고 바로 뒤이어 ".augment/rules/에 있는 파일은 하위 디렉터리가 아닌 워크스페이스 루트에서만 로드됩니다"라고 설명합니다.

따라서 Augment 자체 형식으로 변환하면 디렉터리 범위 지정을 잃게 됩니다. 기존 src/frontend/CLAUDE.md는 프론트엔드에서 작업이 일어날 때만 로드되었습니다. 동일한 콘텐츠를 .augment/rules/frontend.md로 이동하면 워크스페이스 루트에서 모든 작업에 대해 로드됩니다. 이 한 가지 축에서 보면, 해당 벤더의 기본 형식은 지원하는 세 가지 형식 중 범위 지정이 가장 제한적입니다.

대부분의 팀에 실용적인 해결책은 분할하는 것입니다. 디렉터리 범위 지정이 실제로 작동하는 곳에는 중첩된 CLAUDE.md 파일을 유지하고, 항상 켜져 있는 것 외에 다른 type이 필요한 리포지토리 전체 규칙에만 .augment/rules/를 사용하는 것입니다. 단순히 트리 구조를 깔끔하게 만들기 위해 중첩된 파일을 변환하지 마십시오.

어떤 것을 선택하든 추측하지 말고 검증하십시오. Claude Code의 일관성 관련 노트는 이를 확인해야 하는 좋은 이유가 됩니다. "두 규칙이 서로 모순되는 경우, Claude는 임의로 하나를 선택할 수 있습니다." 두 개의 규칙 트리가 동시에 로드되면 작성하지 않은 모순이 발생할 수 있으며, 그 해결 메커니즘은 사용자가 검사할 수 없습니다. Claude Code 측에서 이 상황을 감사하는 방법은 reconciling conflicting CLAUDE.md layers에서 다루었습니다.

2단계: 조건부 규칙 재선언 및 글자 수 제한 확인하기

Claude Code의 조건부 로드 메커니즘은 paths 프론트매터가 포함된 .claude/rules/이며, paths가 없는 규칙은 "시작 시 .claude/CLAUDE.md와 동일한 우선순위로 로드된다"는 자체 노트가 있습니다. Augment의 메커니즘은 type 필드입니다.

이를 신중하게 매핑하십시오. 경로 범위가 지정된 Claude Code 규칙은 적용되는 디렉터리의 중첩된 CLAUDE.md가 되어 범위 지정을 유지하거나, 적용 시점을 명시하는 description을 가진 agent_requested 규칙이 됩니다. 좋은 설명을 작성할 수 있다면 Augment의 가이드는 후자를 권장합니다. "컨텍스트 사용량을 최적화하려면 always_apply 대신 agent_requested를 사용하십시오. 이 규칙들의 경우, 에디터가 현재 작업과 관련이 있다고 판단할 때 규칙을 적용합니다." agent_requested에는 description이 필수이며, 이 설명이 모든 선택 작업을 수행한다는 점에 유의하십시오.

그 다음 제한 용량을 확인하십시오. Augment는 엄격한 제한을 게시하고 Claude Code는 권장 사항을 게시하기 때문입니다. Claude Code는 "CLAUDE.md 파일당 200행 미만을 목표로 하라"고 조언하는데, 이는 제한이 아닌 가이드라인입니다. 반면 Augment의 제한 섹션은 한계치이며, 초과 시 다음과 같이 작동하도록 문서화되어 있습니다.

"사용자 가이드라인(User Guidelines)은 현재 최대 24,576자로 제한됩니다. 워크스페이스 가이드라인(Workspace Guidelines) + 규칙(Rules)은 합산 최대 49,512자로 제한됩니다. 이 제한을 초과하면 앱 내에서 사용자에게 알림이 전송되며, (수동 규칙, always + auto 규칙, .augment-guidelines) 순서대로 적용됩니다."

마지막 절의 순서를 읽어보십시오. 용량이 초과되면 수동 규칙이 가장 먼저 적용되고 .augment-guidelines가 가장 마지막에 적용됩니다. .augment-guidelines를 표준 파일로 취급해 온 팀은 용량 압박이 있을 때 가장 우선순위가 낮은 항목을 표준으로 취급하고 있는 셈입니다.

팀원 중 일부가 CLI 대신 익스텐션을 사용하는 경우의 또 다른 IDE 전용 세부 정보는 다음과 같습니다. "VSCode에서 정의된 가이드라인은 JetBrains IDE로 전파되지 않으며 그 반대도 마찬가지입니다." 사용자 가이드라인은 로컬 IDE 저장소에 저장되므로 공유되거나 버전 관리되지 않습니다. 두 명 이상에게 중요한 모든 것은 리포지토리에 보관되어야 합니다.

두 도구 모두 파일의 순위를 매기지만, 규칙이 존재하는 이유는 저장하지 않습니다.

이것이 바로 단순한 파일 이동과는 달리 이 마이그레이션을 위험하게 만드는 공백입니다. 중첩된 CLAUDE.md를 agent_requested 규칙으로 변환하기로 결정할 때, 해당 규칙의 description에 들어갈 내용도 결정하게 되며, 이 설명에 따라 규칙이 다시 로드될지 여부가 결정됩니다. 원래 제약 조건이 "결제 모듈은 특정 실패 경로에서 이중 청구가 발생하므로 공유 재시도 헬퍼를 사용해서는 안 된다"였다면, 규칙은 이동 후에도 살아남지만 그 이유는 사라집니다. 그리고 정당한 이유 없이 간결하게 작성된 규칙을 읽은 다음 사람은 이를 삭제해 버릴 것입니다.

MemoryLake는 결정 사항, 시도했던 것, 거부된 이유 및 시점 등 정당한 근거를 보관합니다. 이는 두 지침 시스템의 외부에 존재하므로 우선순위 변경이나 형식 변환으로 인해 재정렬될 수 없습니다. 여기서 시작하세요.

1단계: API 키 생성하기

리포지토리를 위한 워크스페이스를 생성하고 API 키를 생성합니다. 이 키의 목적은 두 도구보다 오래 지속되는 것이므로 Claude Code나 Augment가 아닌 리포지토리 자체로 범위를 지정하십시오.

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

변환을 시작하기 전에 CLAUDE.md 트리를 훑어보고 명확하지 않은 각 규칙이 왜 존재하는지 기록하십시오. Claude Code에 반복해서 제공했던 수정 사항들을 추가하십시오. 이는 로컬에 누적되어 이전되지 않는 자동 메모리의 수정 사항과 동일합니다. 그런 다음 마이그레이션 자체 중에 내린 결정 사항(유지한 파일, 변환한 파일, 의도적으로 남겨둔 파일)을 추가하십시오.

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

Auggie를 연결하고, 전환 기간 동안 Claude Code도 연결 상태를 유지하십시오. 두 도구 모두 동일한 세트를 읽으므로, 아직 포팅하지 않은 규칙이라도 누군가 사용 중인 에이전트에서 그 추론 근거를 계속 사용할 수 있습니다.

"이미 잘 작동한다"는 함정 때문에 한 달을 허비하는 일이 없어집니다. 첫날부터 CLAUDE.md가 2위라는 사실을 알게 되므로, 잊고 있던 파일 아래에 새 .augment/rules/ 파일이 방치되어 있었다는 사실을 나중에 발견하는 대신, 유지할지 변환할지 신중하게 결정할 수 있습니다.

실수로 범위 지정을 잃는 변환 오류가 사라집니다. 오직 AGENTS.md와 CLAUDE.md만 계층적으로 탐색된다는 사실을 알게 되면, "모든 것을 기본 형식으로 이동"하는 것이 명백한 정리 작업처럼 보이지 않게 됩니다.

용량 초과가 보이지 않는 상태로 방치되지 않습니다. Augment의 제한 용량에는 문서화된 적용 순서가 있으므로, 49,512자에 근접한 팀은 규칙이 적용되지 않는 이유를 추측하는 대신 어떤 카테고리가 먼저 저하되는지 알 수 있습니다.

그리고 분할 환경(split-surface) 문제가 명확해집니다. VS Code에서는 작동하고 CLI에서는 건너뛰는 manual 규칙은 규칙 파일을 읽어서 찾을 수 있는 버그가 아닙니다. 이는 우회하도록 설계하거나 아니면 당황하게 될 문서화된 동작입니다.

변환하기 전에 인벤토리를 작성하십시오. 리포지토리의 모든 CLAUDE.md, AGENTS.md, .augment-guidelines, .augment/rules/ 파일을 나열하고 어떤 파일이 로드될지 예상해 보십시오. 그런 다음 각 파일에서 의도적으로 특이한 규칙을 하나씩 테스트하여 실제로 어떤 규칙이 적용되는지 확인하십시오. 이는 why agents ignore your instruction files에서 설명한 상황을 파악하는 가장 빠른 방법입니다.

중첩된 파일은 중첩된 상태로 유지하십시오. 디렉터리 범위 지정은 두 외부 형식에서는 무료로 제공되지만 기본 형식에서는 사용할 수 없습니다. 이는 이례적인 혜택이며, 트리 구조를 그대로 두는 것이 유리합니다.

description 필드를 트리거 조건으로 작성하십시오. agent_requested 규칙의 경우 설명이 전체 활성화 메커니즘입니다. Augment 자체 예시인 "React 컴포넌트 개발 패턴 및 모범 사례"가 규칙 내용의 요약보다 더 낫습니다.

~/.augment/rules/는 항상 켜져 있는 용도로만 취급하십시오. 해당 위치의 프론트매터는 무시되므로 홈 디렉터리에 넣는 모든 것은 여는 모든 프로젝트에 적용됩니다. 순수한 개인적 선호 사항을 위해서만 남겨두십시오.

모든 것을 찾기 위해 Augment의 자동 임포트에 의존하지 마십시오. 이는 "*.md 또는 *.mdx로 끝나는 파일과 같은 마크다운 파일을 찾을 것"이며, 이는 유용하지만 매니페스트와는 다릅니다. 규칙이 중요하다면 우선순위 목록에 명시된 위치에 두십시오.

두 도구 모두 강제 적용하지 않는다는 점을 기억하십시오. Claude Code는 "Claude는 이를 강제된 설정이 아닌 컨텍스트로 취급한다"고 명확히 밝히며, "Claude의 결정과 관계없이 작업을 차단하기 위해" PreToolUse 훅을 추천합니다. 규칙은 의도를 설명합니다. 강제 적용은 다른 레이어의 영역이며, 이는 이번 마이그레이션의 양측 모두에 해당됩니다. 사내 컨벤션 버전의 문제는 making Claude stick to your conventions에서 다룹니다.

이 마이그레이션에서 놀라운 점은 무언가 고장 난다는 것이 아닙니다. 한동안 아무것도 고장 나지 않는다는 점입니다. CLAUDE.md는 Augment의 우선순위 목록에서 2위이므로 지침 레이어는 계속 작동하고, 도구의 기본 형식은 그 아래에서 사용되지 않은 채 방치됩니다.

의도적으로 내려야 할 두 가지 결정은 CLAUDE.md를 신뢰할 수 있는 단일 소스로 유지할지 여부와, 중첩된 파일을 .augment/rules/로 병합할지 여부입니다. 해당 디렉터리는 워크스페이스 루트에서만 로드되기 때문입니다. 이 결정들을 올바르게 내린다면 이는 가장 비용이 적게 드는 에이전트 마이그레이션 중 하나가 될 것입니다. 잘못 내린다면, 기존 파일을 계속 읽고 있던 도구에서 애초에 로드조차 되지 않던 규칙들을 디버깅하느라 몇 주를 허비하게 될 것입니다.