운영과 최적화: 비용·성능·장애 대응·트러블슈팅 체크리스트

Claude Code를 꾸준히 쓰다 보면 "잘 되게 하는 법"만큼 "안 되면 고치는 법"이 생산성을 좌우합니다. 이 장은 운영 관점에서 가장 자주 터지는 문제를 빠르게 진단하고, 비용과 성능을 꾸준히 관리하며, 장애가 났을 때 안전하게 복구하는 방법을 한 번에 정리합니다.

운영의 단위: 토큰·턴·도구 호출

운영에서 체감되는 비용과 지연은 대체로 세 가지에서 발생합니다.

• 토큰: 입력과 출력의 길이

• 턴: 한 작업을 끝내기까지 오가는 왕복 횟수

• 도구 호출: 테스트, 빌드, Bash, MCP, 네트워크 요청

이 세 가지를 나눠 보면 최적화 방향이 훨씬 선명해집니다. 예를 들어 응답이 느릴 때 원인이 모델 자체가 아니라 "불필요하게 긴 출력"일 수 있고, 비용이 많이 나갈 때 원인이 대화 길이보다 "도구 호출 실패 후 재시도"일 수도 있습니다.

그래서 운영 최적화의 핵심은 복잡하지 않습니다.

• 출력은 짧고 목적 중심으로 만들고

• 턴은 적게 끝나도록 요청을 구조화하고

• 도구 호출은 첫 시도 성공률을 높이는 쪽으로 안정화합니다.

비용 관리: 상한선이 없으면 좋은 날만 기억하게 된다

운영은 평균이 아니라 최악의 날을 견뎌야 합니다. 그래서 비용 관리는 "아껴 쓰자"보다 상한선을 먼저 정하는 습관에서 시작합니다.

1) 세션 예산을 먼저 정한다

작업 시작 전에 대략적인 상한을 잡아두면 runaway 세션을 줄이기 쉽습니다.

예:

• 오늘 이 작업은 30분 이내

• 세션은 20~25턴 이내

• 긴 조사 작업은 Plan Mode나 별도 세션으로 분리

이 기준이 있으면, 대화가 길어졌을 때 "더 설명할까?"보다 "세션을 끊고 정리할까?"를 먼저 판단하게 됩니다.

2) 출력 상한이 가장 큰 레버다

비용과 체감 지연을 동시에 줄이는 가장 쉬운 방법은 출력을 짧게 제한하는 것입니다.

예:

• "설명은 5줄 이내"

• "원인 후보 3개와 확인 커맨드만"

• "변경 파일 목록 + 검증 결과만 요약"

• "긴 배경 설명 없이 다음 행동만 제안"

Claude Code는 일을 수행하는 도구이므로, 장문의 설명보다 다음 단계가 중요할 때가 많습니다. 운영 관점에서는 특히 그렇습니다.

3) 반복 지침은 프롬프트가 아니라 파일로 뺀다

매번 같은 장문 지침을 입력하면 토큰과 주의력이 함께 낭비됩니다. 팀 규칙, 테스트 명령, 금지 사항 같은 반복 설명은 CLAUDE.md나 스킬로 옮겨 영속화하는 편이 훨씬 효율적입니다.

이 원칙 하나만 지켜도, 같은 작업을 반복할 때 비용과 왕복 횟수가 크게 줄어듭니다.

성능 관리: 느린 이유를 세 갈래로 나눠 본다

Claude Code가 느리다고 느껴질 때는 대개 아래 셋 중 하나입니다.

1. 출력이 너무 길다

2. 컨텍스트가 너무 무겁다

3. 도구 호출이 느리거나 자주 실패한다

출력이 길어서 느린 경우

가장 흔합니다. "짧게 요약해 달라"보다 산출물 형식 자체를 짧게 제한해야 합니다.

나쁜 예:

이 문제를 자세히 설명하고 가능한 모든 원인을 길게 분석해줘.

좋은 예:

가능한 원인 3개만 제시하고, 각 원인별 확인 커맨드 1개씩 적어줘.

컨텍스트가 무거워서 느린 경우

세션이 길어지면 히스토리, 로그, 검색 결과, 파일 내용이 계속 누적됩니다. 이때는 더 설명하는 것이 아니라, 정리하거나 나누는 것이 정답입니다.

운영 팁:

• 다른 목표로 넘어가면 /clear

• 같은 목표를 이어가되 무거워졌으면 /compact

• 긴 로그는 전부 붙이지 말고 핵심 구간만 잘라 붙이기

• 조사와 구현, 구현과 리뷰를 세션으로 분리

도구 호출이 느린 경우

테스트, 빌드, MCP 호출은 한 번 실패하면 재시도까지 이어져 전체 체감 속도를 크게 떨어뜨립니다. 그래서 성능을 올릴 때도 속도 최적화보다 먼저 실패율 감소가 중요합니다.

점검 항목:

• PATH와 런타임 버전이 맞는가

• 필요한 도구가 실제로 설치되어 있는가

• 인증 토큰이나 네트워크가 안정적인가

• 테스트 명령이 너무 넓지 않은가

즉, "빠르게"보다 "한 번에 제대로"가 먼저입니다.

디버그와 로그: 추측 대신 증거를 남긴다

운영에서 가장 비싼 행동은 추측입니다. 로그와 디버그 정보가 없으면 같은 문제를 반복해서 만납니다.

최소한 남겨야 할 것

장애나 실패를 재현할 때는 최소한 다음 정보가 필요합니다.

• 시간

• 현재 브랜치 또는 세션 식별자

• 실패한 명령

• 종료 코드

• 관련 파일 경로

• 외부 도구(MCP, API, DB)의 이름

이 정도만 있어도 "언제부터, 무엇이, 어떤 변경 직후에" 문제가 시작됐는지 빠르게 좁힐 수 있습니다.

로그는 구조화할수록 다시 쓰기 쉽다

자유 형식 로그보다 아래처럼 일정한 형식이 낫습니다.

• time=

• session=

• command=

• exit_code=

• tool=

• note=

꼭 정교한 로깅 시스템이 없어도 됩니다. 중요한 건 다음 번에 같은 문제를 추적할 수 있게 남기는 것입니다.

흔한 오류 1: 권한 문제

Claude Code에서 가장 자주 헷갈리는 오류 중 하나는 "허용한 것 같은데 여전히 안 되는" 상황입니다.

대표 증상

• 같은 권한 요청이 계속 반복된다

• 특정 Bash 명령만 자꾸 막힌다

• 파일 읽기/수정은 되는데 외부 연결이 실패한다

• MCP 도구는 보이는데 실행 시 401/403이 난다

해결 순서

첫째, 무엇이 막혔는지 분리합니다.

• 파일 읽기인가?

• 파일 수정인가?

• Bash 실행인가?

• 네트워크 호출인가?

• 외부 서비스 인증인가?

둘째, 허용 범위를 좁혀 다시 봅니다. 운영에서는 "전부 열자"보다 "이번 작업에 필요한 것만 열자"가 더 안전하고 원인도 빨리 좁혀집니다.

셋째, MCP라면 토큰과 스코프를 점검합니다.

• 401: 토큰 없음, 만료, 인증 방식 오류

• 403: 권한 부족, 조직 정책 제한, 리소스 범위 문제

권한 문제는 대개 "도구는 맞는데 정책 계층이 다르다"에서 발생합니다. 그래서 user/project/local 설정, managed 정책, 네트워크 제한을 함께 봐야 합니다.

흔한 오류 2: 설치/실행 문제

실제로는 Claude Code 자체보다 주변 실행 환경이 더 자주 문제를 만듭니다.

대표 증상

• command not found

• npx not found

• MODULE_NOT_FOUND

• node-gyp 실패

• 설정을 바꿨는데 반영되지 않음

해결 순서

1) 먼저 터미널에서 단독 실행

MCP 서버든 포맷터든 테스트 러너든, Claude Code 밖의 일반 터미널에서 먼저 실행해 봅니다. 여기서 안 되면 Claude Code 문제가 아니라 환경 문제일 가능성이 큽니다.

2) 버전 조건 확인

Node, Python, Java 같은 런타임 버전이 서버나 도구의 최소 요구 조건과 맞는지 확인합니다.

3) 캐시와 재시작

설정을 바꿨는데 반영이 안 되는 경우는 IDE/앱 캐시나 세션 재시작 문제일 때가 많습니다.

• 창 리로드

• Claude Code 재실행

• IDE 재시작

• 패키지 캐시 정리

4) 회사 네트워크 의심

프록시, 방화벽, 인증서 정책 때문에 설치/호출이 실패하는 경우도 흔합니다. 이때는 코드가 아니라 네트워크 정책 문제일 가능성이 큽니다.

흔한 오류 3: MCP 문제

MCP 문제는 크게 세 가지로 나뉩니다.

• 설정이 안 읽힌다

• 서버는 떠 있지만 도구가 안 보인다

• 도구는 보이지만 실행이 죽는다

서버가 목록에 안 보일 때

가장 먼저 확인할 것은 설정 파일의 위치와 스코프입니다.

• user에 넣었는가

• local에 넣었는가

• project의 .mcp.json에 넣었는가

• 같은 이름이 다른 스코프에 중복 정의되어 있지 않은가

이름 충돌은 생각보다 흔한 원인입니다.

도구가 안 뜨거나 실행 시 죽을 때

보통은 서버 시작 단계에서 실패했거나, 인증/의존성 문제입니다.

• stdio 서버라면 실행 커맨드가 단독으로 동작하는지

• HTTP 서버라면 URL과 인증 헤더가 맞는지

• 환경 변수 치환이 실제로 되었는지

• 서버 측 로그를 올려 원인이 드러나는지

도구가 너무 많을 때

도구 수가 많아질수록 선택 오류와 컨텍스트 부담이 커집니다. 해결책은 단순합니다.

• 도메인별로 서버를 나눈다

• read-only / write를 분리한다

• 현재 작업에 필요한 서버만 유지한다

MCP는 많이 붙이는 것보다 업무 루프를 닫을 만큼만 정확히 붙이는 것이 더 중요합니다.

흔한 오류 4: 세션 품질 저하

오류 메시지는 없는데 품질이 계속 나빠지는 경우도 있습니다. 운영에서는 이 유형도 중요합니다.

대표 증상

• 같은 제약을 자꾸 잊는다

• 이미 읽은 파일을 다시 읽는다

• 답이 점점 길어지고 흐려진다

• 작업 범위가 슬쩍 넓어진다

해결 순서

• 다른 목표라면 /clear

• 같은 목표라면 /compact

• 다음 행동 1~3개만 남기고 세션 재시작

• 기능 수정과 품질 정리를 분리

• 리뷰는 별도 세션 또는 별도 역할로 분리

이 문제는 "모델이 나빠졌다"가 아니라, 대개 세션 운영이 무거워졌다는 신호입니다.

장애 대응 루틴: 빨리, 하지만 안전하게

장애 상황에서 가장 중요한 것은 완벽한 설명이 아니라 빠른 안정화입니다. 아래 7단계를 팀 기본 루틴으로 고정해 두면, 급한 상황에서도 실수를 줄일 수 있습니다.

1) 영향 범위를 먼저 본다

전체 사용자 문제인지, 일부 기능 문제인지, 특정 브랜치/특정 환경 문제인지부터 나눕니다.

2) 즉시 완화책을 찾는다

• 기능 플래그로 비활성화

• 문제 도구/서버 일시 차단

• 마지막 정상 상태로 롤백

• 자동화 일시 중지

완화는 "근본 해결"이 아니라 "피해 확대 방지"입니다.

3) 타임라인을 만든다

무엇이 언제 바뀌었는지를 먼저 적습니다.

• 배포 시각

• 설정 변경 시각

• 의존성 업데이트 시각

• 에러 증가 시각

타임라인이 없으면 원인 후보가 쓸데없이 넓어집니다.

4) 증거 기반으로 가설을 세운다

로그, 메트릭, 에러 메시지, 최근 diff를 보고 가설을 2~3개로 좁힙니다. 추측을 길게 늘리는 것보다, 반증 가능한 가설이 중요합니다.

5) 운영 환경이 아니라 재현 환경에서 먼저 확인한다

가능하면 스테이징, 복제 환경, 샌드박스 브랜치에서 먼저 재현합니다. 운영에서 바로 실험을 반복하면 문제를 더 크게 만들 수 있습니다.

6) 수정은 가장 작은 안전한 단위로

핫픽스 상황일수록 "완벽한 리팩터링"보다 "증상 차단"이 먼저입니다. 큰 수정은 후속 작업으로 분리하세요.

7) 복구 후엔 재발 방지 자산을 남긴다

문제가 해결되면 끝이 아닙니다. 최소한 아래 하나는 남겨야 합니다.

• 테스트

• 체크리스트

• CLAUDE.md 규칙

• 훅/권한 정책

• 운영 문서

같은 장애를 같은 방식으로 다시 겪지 않게 만드는 것이 진짜 복구입니다.

운영 체크리스트: 매일 보는 10문항

아래 체크리스트는 길어 보이지만, 실제로는 세션 시작 전과 종료 전에 빠르게 훑는 용도입니다.

시작 전

• 이번 세션의 목표가 한 문장으로 말해지는가

• 검증 방법이 정해졌는가

• 작업 디렉터리와 브랜치가 맞는가

• 필요한 권한과 MCP 서버만 켰는가

• 로그/증거 수집 방법이 준비되었는가

작업 중

• 출력이 불필요하게 길어지지 않는가

• 같은 설명을 반복하고 있지 않은가

• 도구 호출 실패가 계속 재발하지 않는가

• 세션이 무거워졌다면 /clear나 /compact가 필요한가

종료 전

• 변경 파일과 이유를 설명할 수 있는가

• 검증 결과를 남겼는가

• 다음 행동이 있으면 메모나 문서로 남겼는가

• 커밋 또는 되돌리기 지점이 확보되었는가

마무리: 운영은 '잘 쓰는 법'보다 '망가지지 않게 쓰는 법'이다

Claude Code를 잘 쓰는 팀과 오래 잘 쓰는 팀은 다릅니다. 전자는 좋은 날에 빠르고, 후자는 나쁜 날에도 무너지지 않습니다.

이 장의 핵심은 단순합니다.

• 비용은 상한선을 먼저 정해 관리한다.

• 성능은 출력·컨텍스트·도구 호출로 나눠 본다.

• 장애는 추측보다 증거로 좁힌다.

• 복구는 완벽함보다 작은 안전한 단계가 우선이다.

• 같은 문제를 반복하지 않게 규칙과 체크리스트를 남긴다.

이 원칙이 자리 잡히면 Claude Code는 단순히 빠른 도구가 아니라, 지속적으로 운영 가능한 개발 시스템이 됩니다.