3계층으로 좁히고 4단으로 분해한다 — 공통 문제 10선과 현장 장애 5건

앞 편에서 하루가 사람 손 없이 도는 데까지 만들었다. 잘 만들어도 장애는 난다. 그리고 자동화의 장애는 수동 작업의 장애와 성격이 다르다 — 아무도 보고 있지 않을 때 나고, 조용히 나며, 나는 동안에도 계속 돈다.

이 글은 그때 무엇을 어떤 순서로 보는가를 다룬다. 핵심은 두 가지 틀이다. 하나는 어디가 깨졌는지를 세 계층으로 좁히는 것이고, 다른 하나는 하나의 장애를 네 칸으로 분해해 마지막 칸을 비워 두지 않는 것이다.

앞 편이 하루 사이클 표 안에 자리만 잡아 둔 「주간 15분 · 월간 30분」 점검이 무엇을 보는 시간인지도 이 글에서 목록으로 펼친다.

이 글이 옮긴 원 자료의 작성 기준일은 2026-07-26이다. 도구 동작·임계값·에러 코드 성격은 그 시점의 것이며 버전에 따라 바뀐다.

아래 「현장 장애 사례 5건」의 수치는 원 자료가 장애 기록에서 옮긴 것이며 이 글이 관측한 값이 아니다.

용어 정리

첫 편의 용어표에서 이 글이 쓰는 행만 추렸다.

진단 프레임 — 4단 분해 + 3계층 분류

모든 장애를 증상 → 원인 → 해결 → 예방 4단으로 분해한다. 처음 보는 문제도 이 틀에 넣으면 체계적으로 다룰 수 있다.

동시에 어느 레이어가 깨졌는지 3계층으로 좁힌다. 복구 속도는 이 좁히기에서 결정된다.

세 계층은 원인이 있는 자리가 우리 통제 밖인지, 우리가 쓴 양인지, 우리가 쓴 글자인지로 갈린다. 갈린 자리가 다르면 손에 잡히는 조치의 성격도 달라진다 — 아래 「진단 순서」 표의 「즉시 조치」 열이 그 차이를 그대로 보여준다. 외부 의존은 상태를 되살리거나 흘려보내는 쪽(재인증, 영구 실패 코드면 즉시 중단·큐 저장)이고, 자원 한도는 먼저 멈추는 쪽(실행 중단 → 대화 압축 또는 세션 초기화, 즉시 중단 후 훅 코드 점검)이며, 내부 설정은 쓴 것을 고치는 쪽(화이트리스트 재구성, 절대 경로 치환, 커밋 되돌리기)이다. 세 계층에 각각 조치가 있고 그 성격이 다르다는 것이지 어느 하나만 손댈 수 있다는 뜻은 아니다 — 이렇게 갈라 읽는 것은 이 글의 정리다.

그리고 원 자료는 내부 설정 계층 장애가 대부분 테스트 없이 운영에 반영한 결과라는 지적이 특히 실무적이라고 적었다. 위 표가 이 계층의 원인 위치를 「우리가 쓴 설정」으로 적어 둔 것과 이어 읽으면, 반영 전에 한 번 돌려 보는 절차가 이 계층에서 특히 값을 한다는 말이 된다.

공통 문제 10선

열 행을 앞 절의 3계층에 전수 배정하면 분포가 한쪽으로 쏠린다. 외부 의존이 둘(연동 접속 실패, 인증 충돌), 자원 한도가 셋(컨텍스트 초과, 무한 루프, 비용 폭주), 내부 설정이 다섯(권한 거부, 경로 오류, 자동 커밋, 검토 없는 배포, 품질 저하)이다 — 이 배정은 이 글의 정리다. 마지막 행(품질 저하)은 원인이 컨텍스트 오염(자원 한도)과 규칙 문서 과부하(내부 설정) 양쪽에 걸쳐 있어, 아래 「진단 순서」 표가 「규칙 문서 줄 수와 모순 여부」를 내부 설정 행에 둔 것을 따랐다.

쏠린 방향이 말하는 것은 하나다. 열 행 중 다섯이 우리가 쓴 설정에서 나온다 — 원인이 우리 통제 밖도 우리가 쓴 양도 아니라 우리가 쓴 글자에 있는 항목이 가장 많다.

「해결」 열도 한 방향으로 모인다. 열 행 중 넷(무한 루프, 버전관리 충돌, 비용 폭주, 검토 없는 자동 커밋)이 즉시 중단 또는 되돌리기를 포함한다. 원인을 찾기 전에 출혈을 먼저 막는 순서다.

위 표의 수치는 전부 원 자료가 제시한 기준선·관측 범위이며 이 글이 측정한 값이 아니다 — 토큰 만료 30~60일, 파일당 10~20K 토큰, 동일 에러 3회, 규칙 문서 200줄, 예시 3~5개. 권한 4계층의 이름과 우선순위 역시 원 자료 작성 기준일(2026-07-26) 시점의 도구 사양이다.

품질 저하 판정에 대한 지적이 실무적으로 유용하다. "모델이 나빠진 것 같다"는 느낌의 대부분은 컨텍스트 오염이며, 새 세션 테스트로 진짜 회귀와 구분할 수 있다.

수치 기준이 명확한 세 항목

세 행이 전부 한도에 닿기 전에 손을 쓰는 기준이라는 점이 공통점이다. 첫 행이 특히 그렇다 — 압축 시점을 50~60%로 잡는 이유가 한도 초과를 막기 위해서가 아니라 70%에서 이미 품질이 떨어지기 때문이다. 에러가 나는 선과 품질이 떨어지는 선이 다르고, 관리해야 할 것은 뒤쪽이다.

위 표의 수치(50~60% 압축 시점, 70% 품질 저하선, 파일당 10~20K 토큰, 규칙 문서 200줄)는 원 자료가 제시한 기준선이며 이 글이 측정한 값이 아니다. 실제 임계는 모델의 컨텍스트 한도와 작업 성격에 따라 달라진다. 원 자료 작성 기준일은 2026-07-26이다.

마지막 행의 200줄은 규칙 문서(CLAUDE.md)의 크기 한도다. 같은 원 자료가 설계 절에서는 같은 파일에 60줄이라는 다른 값을 쓰는데, 그쪽은 10항목 체크리스트에서 역산한 설계 산식이고 이쪽은 컨텍스트 잠식을 막는 장애 예방 한도다 — 두 값이 어떻게 갈리는지는 첫 편이 서로 다른 값이 붙는 여섯 자리를 모아 정리했다.

권한 설계는 문제 유형에 따라 갈린다

권한 설계에서 문제 유형에 따라 전략이 달라진다는 점도 짚어둘 만하다. 잘못된 자동 커밋 문제는 "커밋은 허용, 푸시는 거부"로 막지만, 검토 없는 커밋 자체가 문제라면 "커밋 명령 자체를 거부"해야 한다. 커밋 훅은 우회 옵션으로 무력화될 수 있으므로, 근본 통제는 권한 계층에서 한다.

같은 증상(원치 않은 커밋)에 두 개의 다른 처방이 붙는 이유는 막으려는 것이 다르기 때문이다. 앞은 영향 범위를 막고(원격에 나가지 않게), 뒤는 행위 자체를 막는다(사람이 보기 전에는 기록되지 않게).

현장 장애 사례 5건

앞의 10선이 일반론이라면, 아래는 실제 장애 기록에서 뽑은 것이다.

다섯 건 전부 「예방」 열에 규칙 문서 명시 또는 필수 절차 지정이 들어 있다. 코드나 설정을 고치는 조치가 함께 붙은 것은 셋이다 — 안전 마진 체크 함수, 훅 3체크, push 계열 거부 등록. 나머지 둘은 문서와 절차만으로 끝난다. 즉 다음 사람이 같은 판단을 못 하게 만드는 쪽이 기본이고 코드는 보조다.

장애가 이어진 시간도 표에 남아 있는데, 세 수치가 각각 다른 것을 잰다. 물결 경로 건의 7일은 스크립트가 조용히 실패한 기간이고, 행 단위 보안 건의 30분은 전체 행이 노출된 채로 지속된 시간이며, 종료 훅 무한 루프 건의 5분은 컨텍스트 80%를 태우는 데 걸린 시간이다. 발견 시점이 아니라 문제가 굴러간 시간이라는 점이 셋의 공통점이다 — 이렇게 갈라 읽는 것은 이 글의 정리다. 앞 편이 운영 전환 목록에 알림과 로그를 넣은 이유가 여기 있다.

위 다섯 건의 수치는 원 자료가 장애 기록에서 옮긴 것이며 이 글이 관측한 값이 아니다 — 100통·450통·50통, 30분간 노출, 7일간, 5분 만에 80%, 결제 오류 30건, 디버그 출력 12줄·미구현 3개, 안전 마진 80%, 재발송 24시간. 원 자료 작성 기준일은 2026-07-26이다.

이 다섯 건에서 뽑아낼 수 있는 문장은 하나다. 에이전트가 말하는 "완료"는 기술적 실행 가능을 뜻하지, 코드 품질이나 비즈니스 안전성을 뜻하지 않는다. 모호한 지시는 모호한 결과를 낳는다.

점검 루틴 — 지식을 습관으로

세 주기의 항목이 점검 대상의 변화 속도에 맞춰 배치돼 있다 — 이렇게 읽는 것은 이 글의 정리다. 일일은 어제 하루 사이에 바뀔 수 있는 것(인증·사용량·커밋)을 보고, 주간은 며칠에 걸쳐 추세로 드러나는 것(사용량 추세·한도 여유)을 보며, 월간은 한 달은 지나야 부채가 쌓이는 것(예산·토큰 만료·문서 분량)을 본다. 점검 항목은 세 주기가 각각 다섯 개씩, 합쳐 열다섯 개이고 시간은 하루 5분·주 15분·월 30분이다.

세 행 중 주간·월간 두 행이 앞 편의 하루 사이클 표에서 「운영 점검 15분」·「월간 점검 30분」으로 자리만 잡혀 있던 두 행의 내용이다. 일일 행은 그 표에 대응 행이 없다 — 앞 편의 표가 점검으로 잡아 둔 자리는 주간·월간 둘뿐이고, 세션을 열기 전에 무엇을 훑을지는 이 표에서 처음 나온다.

DO / DON'T

원 자료가 강조하는 DO / DON'T를 한 표로 압축하면 다음과 같다.

왼쪽 열은 사고가 나기 전에 하는 것이고 오른쪽 열은 사고를 만든 실제 행동이다. 오른쪽 다섯 항목 중 셋이 바로 앞의 현장 5건에 직접 등장한다 — 재진입 체크 없이 종료 훅에서 차단 코드 반환(4번 사례), 물결 경로 사용(3번 사례), 보안 정책 조건식을 항상 참으로 둠(2번 사례)이다. 나머지 둘의 자리는 서로 다르다. 와일드카드 허용은 앞의 공통 문제 10선에 대응 행이 있고(「버전관리 명령 전체 허용으로 add-commit-push 체인이 즉시 실행」), 권한 확인 건너뛰기는 10선이 아니라 아래 「진단 순서」 표의 내부 설정 행 — 2순위 확인 「실행 인자에 위험 옵션이 남았는지」 — 에 걸린다. 이렇게 대응을 찾아 붙이는 것은 이 글의 정리다.

원 자료는 이번 주 안에 실천할 것 세 가지로 압축한다. 종료 훅 플래그 체크, push 거부 등록, 물결 경로 제거다. 셋 다 한 줄짜리 조치이면서, 각각 장애 5건 중 하나씩을 막는다.

진단 순서 — 계층별로 무엇을 먼저 보는가

장애 시 손이 가야 할 순서를 계층별로 정리한다. 도구 이름이 아니라 확인 대상으로 적어두면 다른 스택에도 그대로 옮겨 쓸 수 있다.

일곱 행이 세 계층에 2·2·3으로 배분되고, 내부 설정에 가장 많은 진입점이 붙는다. 공통 문제 10선의 분포와 같은 방향이다.

「즉시 조치」 열도 계층마다 성격이 갈린다. 외부 의존은 상태를 되살리는 것(재인증·큐 저장), 자원 한도는 먼저 멈추는 것(중단·초기화, 그리고 중단 후 훅 코드 점검), 내부 설정은 고치는 것(재구성·치환·되돌리기)이다 — 첫 절에서 예고한 그 차이가 여기서 표로 확인된다. 세 계층에서 손에 잡히는 조치의 성격이 처음부터 다르므로, 계층을 먼저 좁히는 것이 곧 복구 속도가 된다. 이렇게 갈라 읽는 것은 이 글의 정리다.

4단 프레임워크의 마지막 칸(예방)을 비워두지 않는 것이 이 절의 핵심이다. 해결에서 멈추면 같은 장애가 다른 얼굴로 돌아온다. 예방 항목은 반드시 설정 파일이나 규칙 문서에 반영해 다음 사람이 같은 실수를 못 하게 만든다. 위 도식의 마지막 화살표가 해결이 아니라 문서 반영으로 끝나는 이유다.

다음 편으로

이 글은 하나의 장애를 어떻게 다루는가를 다뤘다. 3계층으로 좁히고(어디가 깨졌는가), 4단으로 분해하고(무엇을 남길 것인가), 자주 나오는 것 10선과 실제 5건을 같은 틀에 넣고, 점검 루틴으로 습관화하는 데까지다.

전체를 관통하는 것은 하나다. 장애 대응의 산출물은 복구가 아니라 문서 한 줄이다. 복구는 그 장애를 끝낼 뿐이고, 규칙 문서나 권한 설정에 반영된 한 줄만이 다음 장애를 막는다. 공통 문제 10선의 「예방」 열도, 현장 5건의 「예방」 열도, 진단 순서 도식의 마지막 화살표도 전부 같은 곳을 가리킨다.

여기까지는 에이전트가 열 개 안쪽일 때의 이야기다. 이어지는 마지막 편은 개수가 늘 때 무엇이 먼저 깨지는지를 다룬다 — 잠재 경로가 개수의 제곱으로 늘어나는 라우팅 붕괴, 개수보다 빨리 오르는 비용 구조, 그리고 그 모든 것을 하고 나서 "그래서 효과가 얼마였나"에 답하는 방법이다.