Claude Code 백그라운드 에이전트 운영법: 중단·재시도·권한 모드를 안전하게 다루기

Claude Code 2.1.x 릴리스 노트를 보면 최근 업데이트의 방향이 분명합니다. 새 기능보다 백그라운드 에이전트, 재시도, 세션 복구, 권한 모드, tmux 렌더링 같은 운영 안정성 개선이 많습니다. 개발자 입장에서는 이게 더 중요합니다. AI 코딩 도구는 데모보다 장시간 작업에서 신뢰가 갈립니다.

이 글은 Claude Code를 “가끔 쓰는 CLI”가 아니라 실제 개발 워크플로우의 작업자로 운영할 때 필요한 기준을 정리합니다.

왜 백그라운드 에이전트가 자주 깨지는가

AI 코딩 작업은 생각보다 상태가 많습니다.

• 현재 브랜치와 worktree
• 진행 중인 diff
• 도구 권한 상태
• MCP 서버 연결
• API 스트리밍 상태
• 네트워크 재시도 상태
• 사용자가 중간에 취소한 turn
• 백그라운드 daemon과 세션 파일

이 중 하나만 꼬여도 “작업은 끝났는데 결과가 없다”, “취소했는데 다시 실행된다”, “세션이 멈춘 것처럼 보인다” 같은 문제가 생깁니다. 최근 Claude Code changelog에는 sleep/wake 이후 background session이 멈추는 문제, stale daemon lock, subagent rate limit 처리, tmux 3.4+ 렌더링 flicker 같은 수정이 포함됐습니다.

즉, 실무자는 “최신 버전이면 알아서 되겠지”가 아니라 운영 방식을 정해야 합니다.

권한 모드는 Manual을 기본으로 본다

Claude Code 2.1.200에서는 default permission mode가 Manual로 바뀌었다는 변경이 있습니다. 이 방향은 맞습니다. 코딩 에이전트는 파일 수정, 명령 실행, 네트워크 접근, 브랜치 생성, PR 작성까지 할 수 있습니다. 자동 허용 범위를 넓히면 속도는 빨라지지만 사고 반경도 커집니다.

실무 기준은 이렇게 잡는 편이 안전합니다.

• 읽기 작업: 자동 허용 가능
• 테스트, 타입체크, lint: 프로젝트 내에서 자동 허용 가능
• 파일 수정: 작업 범위가 명확할 때 허용
• 패키지 설치: lockfile 변경을 확인한 뒤 허용
• push, PR 생성, 배포: 별도 승인
• 삭제, 마이그레이션, 외부 발송: 사람 승인 필수

권한을 너무 엄격하게 두면 생산성이 떨어집니다. 반대로 모든 것을 자동 허용하면 에이전트가 실수했을 때 복구 비용이 큽니다. Manual 기본값은 “느리게 하자”가 아니라 “위험도를 구분하자”에 가깝습니다.

tmux와 백그라운드 작업을 같이 쓰는 법

장시간 코딩 작업은 tmux 같은 지속 세션에서 돌리는 게 좋습니다. 이유는 단순합니다. 사용자가 언제든 attach해서 상태를 볼 수 있고, 터미널이 끊겨도 작업이 유지되며, 로그를 추적하기 쉽습니다.

추천 패턴은 다음과 같습니다.

1. 프로젝트별 tmux 세션을 하나 둡니다.
2. Claude Code는 해당 세션 안에서 실행합니다.
3. 긴 빌드나 dev server도 같은 세션 또는 명확한 pane에서 실행합니다.
4. 작업 완료 후 세션을 kill하지 않고 유지합니다.
5. 최종 보고에는 브랜치, diff 요약, 테스트 결과를 남깁니다.

최근 릴리스에서 tmux 3.4+ 렌더링 flicker를 synchronized terminal output으로 개선했다는 항목도 있었습니다. 이런 수정은 CLI를 실제로 오래 켜두는 사용자에게 중요합니다.

재시도 정책을 믿되, 로그는 남겨야 한다

Claude Code는 transient network error, API overloaded, rate limit 같은 상황에서 재시도 UX를 개선하고 있습니다. 일부 릴리스에는 transient 429를 backoff로 자동 재시도하는 내용도 있습니다.

하지만 자동 재시도는 만능이 아닙니다. 재시도가 많아질수록 다음 문제가 생깁니다.

• 작업 시간이 예상보다 길어진다.
• 같은 명령이 여러 번 실행될 수 있다.
• 외부 API 비용이 늘 수 있다.
• 사용자는 멈춘 것인지 기다리는 것인지 구분하기 어렵다.

따라서 장시간 작업에서는 중간 상태 보고가 필요합니다. 최소한 “현재 단계”, “마지막 성공 작업”, “다음 시도”, “승인이 필요한 작업”을 남겨야 합니다.

subagent를 쓸 때의 기준

서브에이전트는 조사, 리뷰, 테스트 분리에 유용합니다. 하지만 모든 일을 subagent로 나누면 컨텍스트 전달 비용과 실패 지점이 늘어납니다.

좋은 분리 기준은 이렇습니다.

• 독립적으로 읽고 판단할 수 있는 작업: subagent 적합
• 동일 파일을 동시에 수정할 가능성이 높은 작업: 부적합
• 긴 리서치와 짧은 구현이 섞인 작업: 리서치만 분리
• 보안·품질 리뷰: 구현 후 별도 subagent 적합
• 배포나 외부 쓰기: parent가 최종 승인 후 실행

최근 릴리스에는 subagent가 rate limit 전에 잘리거나 API 에러를 성공처럼 보고하는 문제를 고친 내용이 있습니다. 이건 운영상 중요합니다. parent agent가 “성공”으로 착각하면 잘못된 결과를 배포할 수 있기 때문입니다.

실패 복구 루틴

Claude Code 세션이 이상해졌을 때 바로 재시작하기 전에 아래를 확인합니다.

1. 현재 git diff를 저장하거나 확인합니다.
2. 실행 중인 명령이 있는지 봅니다.
3. 마지막으로 성공한 테스트나 빌드 로그를 찾습니다.
4. 백그라운드 에이전트가 같은 작업을 재실행 중인지 확인합니다.
5. 필요하면 새 세션이 아니라 기존 세션을 resume합니다.

가장 위험한 대응은 “멈춘 것 같으니 같은 작업을 새로 시작”하는 겁니다. 파일 수정이 중복되고, 브랜치가 꼬이고, 원인 파악이 어려워집니다.

바로 적용할 체크리스트

• 프로젝트별 tmux 세션 이름을 고정
• Claude Code 권한 모드는 Manual을 기본값으로 사용
• push, PR, 배포, 삭제는 별도 승인 단계로 분리
• 장시간 작업은 현재 단계와 마지막 성공 로그를 남김
• subagent는 독립 조사·리뷰에 우선 사용하고 동시 파일 수정은 피함
• 실패 시 새 작업 시작 전 git diff와 실행 중 프로세스 확인
• Claude Code changelog에서 background agent, retry, permission 관련 변경은 주기적으로 확인

AI 코딩 도구의 생산성은 “한 번에 멋진 코드를 만들었나”보다 “중간에 깨져도 복구 가능한가”에서 갈립니다. 백그라운드 에이전트를 안전하게 운영하면, 긴 리팩터링과 반복 QA 작업을 훨씬 안정적으로 맡길 수 있습니다.