뮤즈 코드 장시간 작업 중단 복구 가이드

터미널 연결이 끊긴 뒤 뮤즈 코드가 같은 파일을 다시 고치고 외부 작업까지 두 번 실행했다면, 복구 버튼부터 누르면 안 됩니다.

가장 빠른 해결책은 마지막 사건 로그, 현재 작업 공간, 외부 부작용을 먼저 대조하는 것입니다. 세 상태가 맞을 때만 계속 진행하고, 하나라도 입증되지 않으면 되돌리거나 검사 지점에서 새 작업으로 재구성해야 합니다.

적합합니다: 대형 저장소와 백그라운드 작업을 뮤즈 코드에 맡기되, 중단 뒤에도 변경 이력을 직접 검증할 수 있는 개발자와 플랫폼 팀에 적합합니다.
부적합합니다: 파일과 원격 시스템을 자동으로 계속 바꾸게 두고 실행 결과를 확인하지 않는 운영 방식에는 적합하지 않습니다.

마지막 업데이트: 2026년 8월 12일
내용은 메타의 공식 모델 안내와 깃·관측성 문서를 대조했으며, 뮤즈 코드의 복구 정확도와 버전별 로그 형식은 별도 재현 시험이 필요합니다. 메타는 뮤즈 계열 모델이 도구 사용과 여러 에이전트 작업을 지원한다고 설명하지만, 모델의 장시간 작업 능력과 복구 보장은 같은 의미가 아닙니다. 메타의 공식 뮤즈 스파크 안내와 공식 모델 개발자 안내를 기준으로 판단해야 합니다.

중단 유형과 복구 범위

뮤즈 코드 장시간 작업 중단은 한 가지 장애가 아닙니다. 아래 세 가지를 먼저 나눠야 합니다.

• 터미널 연결만 끊긴 경우
  원격 셸이나 화면 연결이 끊겼지만 뮤즈 코드 프로세스가 계속 실행 중일 수 있습니다. 이때 다시 실행하면 기존 작업과 새 작업이 같은 파일을 동시에 건드릴 위험이 있습니다.

• 프로세스가 종료된 경우
  메모리 부족, 예외, 운영체제 종료, 세션 정리 때문에 작업 자체가 끝났을 수 있습니다. 사건 로그의 마지막 기록과 프로세스 종료 시각을 확인해야 합니다.

• 모델 요청만 실패한 경우
  모델 응답은 실패했지만 이전 파일 수정이나 도구 호출은 이미 끝났을 수 있습니다. 모델 요청 실패를 전체 작업 실패로 보면 같은 수정이 반복될 수 있습니다.

사건 로그는 복구 판단에 필요한 기록이지, 데이터베이스 트랜잭션과 같은 보증 장치가 아닙니다. 일반적인 로그는 시각과 부가 정보를 가진 사건 기록이며, 기록 시점과 실제 외부 시스템 반영 시점이 다를 수 있습니다. 오픈텔레메트리의 로그와 사건 설명도 로그를 사건 기록으로 설명할 뿐, 외부 작업의 원자적 완료를 보장한다고 말하지 않습니다.

중복 실행과 외부 부작용

복구 뒤 문제가 가장 크게 터지는 지점은 파일 수정보다 외부 작업입니다.

파일 수정은 깃 차이로 비교할 수 있습니다. 반면 아래 작업은 이미 실행됐는지 확인하기 어렵습니다.

• 커밋 생성 또는 원격 저장소 전송
• 배포 요청과 작업 큐 등록
• 메시지 발송
• 데이터베이스 변경
• 외부 API 호출
• 테스트용 계정이나 자원 생성

복구 전에 사건 로그에서 다음 항목을 찾습니다.

1. 도구 호출 식별자
2. 호출 시작과 종료 시각
3. 도구가 반환한 결과
4. 결과가 로그에 기록된 시점
5. 외부 대상에서 확인한 실제 상태
6. 같은 요청을 다시 보내도 한 번만 반영되는지 여부

멱등 처리가 없는 작업은 자동으로 다시 실행하지 않습니다. 같은 요청을 여러 번 보내도 결과가 한 번만 반영되도록 설계하는 방식이 일반적인 안전 원칙입니다. 아마존 웹 서비스의 변경 작업 멱등성 지침도 변경 작업을 멱등적으로 만들 것을 권고합니다.

예를 들어 사건 로그에 성공 기록이 없더라도 원격 저장소에 커밋이 존재할 수 있습니다. 반대로 로그에는 성공이 남았지만 연결이 끊겨 실제 요청이 반영되지 않았을 수도 있습니다. 따라서 로그만 보고 재실행하면 안 됩니다.

코드 상태와 사건 로그의 불일치

복구 후 현재 파일이 로그와 다르면 세 가지 원인을 의심합니다.

• 사람이 중간에 파일을 수정한 경우
• 다른 백그라운드 에이전트가 같은 작업 공간을 사용한 경우
• 뮤즈 코드가 임시 파일이나 생성 파일을 남긴 경우

먼저 다음 명령으로 작업 공간을 고정합니다.

git status --short
git diff --stat
git diff --name-only
git log -1 --oneline
find . -maxdepth 2 -type f -name "*.tmp" -o -name "*.bak"

출력은 다음처럼 분리해서 기록합니다.

기준 커밋: 8d21c4f
추적 파일 변경: 7개
추적되지 않은 파일: 2개
임시 파일: 1개
마지막 사건 로그의 편집 대상: 5개

여기서 로그의 편집 대상과 실제 변경 파일이 다르면 즉시 작업을 멈춥니다. 차이가 단순한 자동 생성 파일인지, 사람이 추가한 수정인지 확인하기 전에는 검사나 커밋을 진행하지 않습니다.

기준 커밋을 증명할 수 없다면 새 작업 공간을 만듭니다.

git worktree add --detach ../복구-검증 HEAD
cd ../복구-검증
git status --short

깃 작업 공간은 하나의 저장소에서 서로 다른 작업 트리를 분리해 사용할 수 있게 합니다. 각 작업 트리는 파일과 인덱스를 분리해 관리할 수 있으므로, 오염된 공간을 그대로 이어 쓰는 것보다 복구 검증에 적합합니다. 깃 작업 공간 공식 문서를 참고하면 분리 작업 공간 생성과 잠금, 상태 확인 방법을 확인할 수 있습니다.

복구 결정 체크리스트

아래 항목을 위에서부터 확인합니다. 하나라도 확인할 수 없다면 같은 목표를 바로 재실행하지 않습니다.

계속 진행

• [ ] 사건 로그의 마지막 확정 작업을 찾았습니다.
• [ ] 현재 파일 변경이 해당 작업과 일치합니다.
• [ ] 외부 도구의 실제 반영 결과를 별도로 확인했습니다.
• [ ] 기준 커밋과 시험 조건이 바뀌지 않았습니다.
• [ ] 다음 작업이 읽기 중심이거나 되돌릴 수 있습니다.

모든 항목에 표시할 수 있을 때만 현재 작업 공간에서 계속 진행합니다.

되돌리기

다음 조건이면 기준 커밋으로 되돌리는 편이 낫습니다.

• 파일 변경은 확인되지만 일부 도구 결과가 불명확합니다.
• 외부 시스템에 영향을 주기 전 단계입니다.
• 기준 커밋으로 돌아가도 사건 로그와 차이를 보존할 수 있습니다.
• 되돌린 뒤 작은 시험으로 상태를 다시 확인할 수 있습니다.

종료 또는 새로 재구성

다음 중 하나라도 해당하면 자동 복구를 중단합니다.

• 외부 작업이 중복 실행됐을 가능성이 있습니다.
• 로그와 작업 공간의 시점이 맞지 않습니다.
• 사람이 수정한 파일과 에이전트 수정 파일을 분리할 수 없습니다.
• 여러 에이전트가 같은 작업 공간을 사용했습니다.
• 보안 토큰, 배포 권한, 고객 데이터가 관련돼 있습니다.

이 경우 증거를 먼저 복사한 뒤 기존 작업을 종료합니다. 기준 커밋을 새 작업 공간에 고정하고, 필요한 파일만 선별해 작업을 재구성합니다.

백그라운드 에이전트 결과

백그라운드 에이전트가 응답하지 않았거나 늦게 결과를 반환한 경우에는 결과 내용보다 기준 시점을 먼저 봅니다.

확인할 항목은 다음과 같습니다.

• 에이전트 작업 식별자
• 작업을 시작한 기준 커밋
• 참조한 파일의 마지막 수정 시각
• 결과가 생성된 시각
• 현재 작업 공간의 기준 커밋
• 에이전트가 실행한 시험 조건

결과가 오래된 기준 커밋을 참조한다면 코드에 바로 합치지 않습니다. 특히 뮤즈 스파크 1.2처럼 새 모델을 시험하는 환경에서는 모델 버전만 바뀌어도 도구 호출 순서와 결과 설명 방식이 달라질 수 있습니다. 모델이 더 긴 문맥을 유지한다고 해도, 작업 공간의 파일과 외부 시스템 상태까지 자동으로 일치시키는 것은 아닙니다. 실제 복구 결과는 사용 중인 실행기와 도구 연결 상태에 따라 검증해야 합니다.

장시간 작업 검사 지점

뮤즈 코드 장시간 작업을 안정적으로 운영하려면 작업을 짧은 검사 지점으로 나눠야 합니다.

1. 작업 시작 전
   기준 커밋과 작업 목적을 기록합니다.

2. 계획 완료 후
   수정 대상 파일, 예상 시험, 외부 도구 목록을 저장합니다.

3. 핵심 수정 후
   작은 단위로 차이를 확인하고 임시 커밋을 만듭니다.

4. 시험 통과 후
   실행 명령, 결과, 사용한 환경 변수를 기록합니다.

5. 외부 작업 직전
   커밋, 배포, 메시지 발송처럼 되돌리기 어려운 작업은 별도 승인을 받습니다.

6. 작업 종료 후
   사건 로그, 깃 차이, 도구 반환값, 최종 시험 결과를 하나의 보관 폴더에 남깁니다.

예시는 다음과 같이 단순하게 시작할 수 있습니다.

mkdir -p .복구증거
git status --short > .복구증거/작업상태.txt
git diff > .복구증거/변경내용.diff
git log -1 --format=fuller > .복구증거/기준커밋.txt

이 자료를 남기면 뮤즈 코드가 충돌했을 때 작업을 처음부터 다시 추측할 필요가 줄어듭니다. 다만 검사 지점은 복구를 보장하는 기능이 아니라, 복구 가능한 증거를 만드는 운영 절차입니다.

실패 뒤 증거 보존

복구에 실패했을 때 바로 임시 폴더와 로그를 삭제하면 원인 분석이 어려워집니다. 최소한 다음 자료는 보존합니다.

• 사건 로그 원본
• 마지막 정상 상태의 깃 차이
• 도구 입력과 반환 결과
• 오류가 발생한 시각
• 현재 작업 공간의 파일 목록
• 백그라운드 에이전트 식별자
• 사용한 모델과 실행기 버전

정리 작업은 증거를 복사한 뒤 진행합니다. 로그 형식이 바뀌었거나 실행기 버전이 업데이트됐다면 같은 중단 시험을 다시 실행해야 합니다. 뮤즈 스파크의 코딩과 도구 사용 능력이 업데이트돼도, 실제 복구 동작은 모델, 실행기, 터미널 연결, 작업 공간 구성의 조합으로 결정됩니다.

기존 환경이 개인 맥에서만 간헐적으로 끊긴다면 장시간 백그라운드 작업의 재현도 어렵습니다. 현재 환경의 단점은 세 가지입니다. 화면 잠금이나 네트워크 변화가 세션에 영향을 줄 수 있고, 여러 작업이 같은 파일을 공유하기 쉽고, 장애 시 로그와 실행 프로세스를 함께 보존하기 어렵습니다. 이런 조건에서는 먼저 격리된 단기 환경에서 한 번 중단 복구를 재현한 뒤, 장시간 작업을 운영할 원격 맥 환경을 따로 구성하는 편이 낫습니다. 임시 계산량과 테스트 노드가 필요하다면 leapmac의 원격 맥 대여를 검토할 수 있지만, 물리 장비 접근이 필수이거나 장기간 고정 부하를 계속 처리해야 한다면 직접 구매가 더 적합합니다.

자주 묻는 질문

뮤즈 코드가 갑자기 종료된 뒤에는 무엇부터 확인해야 하나요?

먼저 같은 작업을 다시 시작하지 말고 마지막 사건 로그를 보존해야 합니다. 그다음 현재 파일의 변경 내용, 깃 상태, 임시 파일, 도구 실행 결과를 함께 확인합니다. 터미널 연결만 끊긴 것인지, 프로세스가 종료된 것인지, 모델 요청만 실패한 것인지 구분해야 안전한 복구 경로를 선택할 수 있습니다.

뮤즈 코드가 복구 뒤 같은 도구를 다시 실행하는 이유는 무엇인가요?

이전 도구 호출의 성공 여부가 작업 상태와 연결되지 않았거나, 도구 결과가 로그에 기록되기 전에 연결이 끊겼을 가능성이 있습니다. 특히 커밋, 메시지 발송, 원격 호출처럼 외부 상태를 바꾸는 작업은 반환 기록과 실제 대상 상태를 따로 확인해야 합니다. 멱등 처리가 없다면 자동 재실행을 막아야 합니다.

복구한 뒤 코드 상태와 사건 로그가 다르면 어떻게 해야 하나요?

로그와 현재 파일이 일치한다고 추정하지 말고 변경 원인을 분리해야 합니다. 사람이 중간에 수정했는지, 다른 에이전트가 같은 작업 공간을 건드렸는지, 임시 파일이 남았는지 확인합니다. 기준 커밋을 입증할 수 없다면 기존 공간에서 계속하지 말고 새 깃 작업 공간을 만들어 검증된 기준에서 다시 시작하는 편이 안전합니다.

뮤즈 코드 장시간 작업에는 어떤 검사 지점을 만들어야 하나요?

큰 기능 하나를 한 번에 맡기지 말고 계획 수립, 핵심 파일 수정, 시험 통과, 외부 작업 전후처럼 되돌릴 수 있는 단위로 나눠야 합니다. 각 지점에는 기준 커밋, 변경 파일 목록, 실행한 시험, 미완료 작업, 외부 도구 결과를 남깁니다. 다음 복구 때 이 정보가 없으면 작업 재개보다 재구성이 더 안전합니다.