Claude Code 2.1.205 운영 체크리스트: 백그라운드 에이전트와 MCP 장애 줄이는 법

요약: Claude Code 2.1.205와 직전 2.1.203 릴리즈에는 백그라운드 에이전트, MCP, auto mode, worktree, 원격 제어, 업데이트 안정성 관련 수정이 많다. 겉으로는 CLI 패치처럼 보이지만, 실제로는 AI 코딩 에이전트를 팀 워크플로우에 넣을 때 자주 터지는 운영 장애 목록에 가깝다. 이 글은 릴리즈 항목을 기능 소개가 아니라 운영 체크리스트로 해석한다.

왜 CLI 릴리즈 노트를 운영 문서처럼 봐야 하나

AI 코딩 에이전트는 이제 단순 자동완성 도구가 아니다. 백그라운드 세션을 만들고, worktree를 생성하고, PR을 열고, MCP 서버를 붙이고, 원격 패널에서 상태를 보여준다. 이 정도가 되면 CLI 버그 하나가 개발자 경험뿐 아니라 코드 변경 안정성, 보안, 감사 가능성에 영향을 준다. 특히 여러 에이전트가 동시에 돌아가는 팀에서는 ‘가끔 멈춤’이나 ‘상태가 stale’ 같은 문제가 곧 생산성 손실로 이어진다.

Claude Code 2.1.205는 session transcript 파일 변조를 막는 auto mode rule, invalid json schema 처리 개선, max-turns 경계에서 메시지 유실 수정, Windows worktree 삭제 안전성, background agent 상태 표시 문제, attach 안정성, MCP import 오류 처리, auto-update 메모리 사용량 감소 등을 포함한다. 2.1.203에는 MCP roots/list 갱신, macOS background session stall 수정, daemon token stale recovery, subagent carry-over, PATH 상속, ANTHROPIC_BASE_URL 유지, worktree 격리 수정 등이 들어 있다. 대부분 ‘데모에서는 잘 안 보이지만 운영에서는 아픈’ 문제다.

백그라운드 에이전트 상태를 믿을 수 있게 만들기

백그라운드 에이전트 운영에서 가장 위험한 것은 실제 상태와 UI 상태가 달라지는 것이다. 완료됐다고 보이는데 사실 resumed 상태이거나, needs input이 아닌데 질문을 기다리고 있거나, attach가 실패해 내부 진행을 볼 수 없는 경우다. 2.1.205와 2.1.203의 여러 수정은 이 영역을 다룬다. background agents가 resume 후에도 failed/completed로 남는 문제, readable text가 없을 때 working으로 되돌아가는 문제, mid-upgrade restart 중 attach 실패, stale Running status forwarding 등이 대표적이다.

팀에서 해야 할 일은 CLI 업데이트만이 아니다. 작업 관리 규칙을 정해야 한다. 각 background session은 작업 ID, repo, branch, PR 링크, human input 필요 여부를 외부 이슈나 스레드에 남겨야 한다. CLI 화면만 신뢰하면 장애 때 복구가 어렵다. 상태가 바뀔 때마다 알림을 받는 구조를 만들고, needs input 상태가 일정 시간 이상 지속되면 담당자에게 알려야 한다.

MCP와 작업 디렉터리 문제

MCP는 코딩 에이전트의 능력을 크게 늘리지만, 설정이 어긋나면 실패 원인을 찾기 어렵다. 2.1.203에서 추가 working directory가 MCP roots/list에 포함되고 roots/list_changed notification이 보내지는 변경은 다중 repo 작업에 중요하다. 에이전트가 부모 checkout에서 명령을 실행하거나, worktree-isolated subagent가 자기 worktree 밖에서 파일을 읽고 쓰면 결과가 위험해진다. 관련 수정이 들어갔다는 것은 이 문제가 실제로 충분히 자주 발생했다는 뜻이다.

운영 기준은 명확해야 한다. MCP server는 어떤 root에 접근 가능한지 로그로 남긴다. worktree를 사용하는 agent는 시작 시 현재 cwd, git root, branch, worktree path를 출력하게 한다. MCP 서버 이름에 unsupported character가 있을 때 import가 멈추던 문제도 수정됐지만, 팀 차원에서는 서버 이름 규칙을 제한하는 편이 낫다. 예를 들어 lowercase kebab-case만 허용하면 자동화 스크립트가 단순해진다.

auto mode와 destructive command

2.1.205에는 auto mode가 session transcript 파일 변조를 막는 rule을 추가했고, 해석할 수 없는 변수에 대해 rm -rf를 실행하기 전에 묻도록 개선됐다. 이 두 항목은 보안과 안전성 측면에서 중요하다. AI 코딩 에이전트는 종종 cleanup 명령을 제안하거나 실행한다. 변수 확장이 실패한 rm -rf는 최악의 경우 엉뚱한 경로를 지울 수 있다. transcript 파일 변조는 감사 가능성과 재현성을 무너뜨린다.

팀 정책으로는 세 가지를 권장한다. 첫째, destructive command는 항상 allowlist 또는 human approval을 요구한다. 둘째, transcript, 로그, 평가 결과처럼 감사에 필요한 파일은 에이전트가 수정하지 못하게 한다. 셋째, cleanup 작업은 rm 대신 trash나 안전한 archive 이동을 우선한다. CLI가 안전장치를 추가했더라도 조직 정책이 없으면 다른 경로에서 같은 사고가 난다.

JSON schema와 구조화 출력 검증

2.1.205는 --json-schema가 invalid schema일 때 조용히 unstructured output을 내던 문제와 format keyword reject 문제를 고쳤다. 구조화 출력은 코딩 에이전트 자동화에서 핵심이다. PR 리뷰 결과, 테스트 계획, 변경 요약, 배포 체크리스트를 JSON으로 받아 후속 시스템에 넘기기 때문이다. invalid schema가 조용히 무시되면 downstream automation은 자연어를 JSON이라고 믿고 처리하다가 깨질 수 있다.

실무에서는 schema를 실행 전에 별도 검증해야 한다. CI에서 schema lint를 돌리고, agent 호출 wrapper는 응답 content-type이나 parse 결과를 확인해야 한다. 구조화 출력 실패 시에는 재시도보다 빠른 실패가 낫다. 잘못된 JSON을 대충 보정해 계속 진행하면 배포 자동화에서 더 큰 문제가 된다.

업데이트와 원격 제어 안정성

auto-update binary 다운로드가 메모리에 버퍼링되지 않고 disk stream으로 바뀌어 peak memory를 약 400MB 줄였다는 항목도 눈에 띈다. 많은 개발자가 동시에 CLI를 업데이트하거나, 작은 VM에서 에이전트를 돌리는 환경에서는 이런 개선이 장애를 줄인다. Remote Control panels의 stale status 수정, 모바일/웹에서 보낸 이미지·파일 caption 없는 경우 drop 문제 수정도 원격 운영 품질과 관련 있다.

팀이 원격 제어를 쓴다면, ‘원격에서 보낸 명령이 실제 interactive session에서 실행됐는지’ 확인하는 acknowledgement가 필요하다. 단순 UI 버튼 클릭 로그만으로는 부족하다. 에이전트 내부 transcript, CLI event, 외부 알림을 연결해야 한다. 특히 파일 업로드나 이미지 리뷰를 쓰는 팀은 attachment 유실 여부를 테스트 케이스에 넣어야 한다.

실행 체크리스트

• Claude Code 버전을 팀 표준으로 고정하고, 업데이트 후 background agent smoke test를 실행한다.
• 모든 background session에 작업 ID, repo, branch, worktree path, PR 링크, needs-input 상태를 외부 로그로 남긴다.
• MCP server 이름 규칙과 접근 root를 제한한다. 시작 로그에 cwd, git root, MCP roots를 출력한다.
• destructive command는 approval을 요구하고, transcript·로그·평가 파일은 수정 금지 영역으로 둔다.
• JSON schema는 agent 호출 전 lint하고, 구조화 출력 parse 실패 시 빠르게 실패 처리한다.
• worktree 격리 작업은 parent checkout에서 명령이 실행되지 않는지 테스트한다.
• 원격 제어에서 보낸 메시지, 파일, 이미지가 transcript에 남는지 확인한다.
• needs input 상태가 일정 시간 이상 유지되면 담당자에게 알림을 보낸다.

Claude Code 릴리즈 노트는 단순 편의 기능 목록이 아니다. 코딩 에이전트를 실제 개발 파이프라인에 넣을 때 어디서 깨지는지 보여주는 사고 목록에 가깝다. 최신 버전을 쓰는 것만큼 중요한 것은, 그 수정 항목을 팀 운영 규칙으로 바꾸는 일이다.