8개 마이크로서비스를 가로지르는 버그를 찾는 데 평균 45분이 걸렸다. 수정하고 나면 다운스트림 서비스 계약을 깨뜨리고, 그걸 금요일 오후에 발견한다. 익숙한 풍경이다. dev.to에 공개된 한 사례는 이 문제를 Claude Code 기반 멀티 에이전트 시스템으로 20분 이내 해결로 줄였다고 보고한다. 쿠버네티스 운영 자동화를 다룬 요즘IT의 사례는 1인 DevOps/SRE가 DEV와 PROD를 동시에 구축하면서 AI를 동료로 삼는 4계층 문서 체계를 만들어냈다. 두 사례는 결론이 다르지 않다. 에이전트를 그냥 풀어놓으면 망한다. 에이전트가 올바르게 행동하도록 구조를 먼저 설계해야 한다.
에이전트는 맥락 없이 움직이지 않는다
멀티 에이전트 버그 수정 사례에서 가장 인상적인 부분은 AI에게 코드베이스를 직접 탐색하게 두지 않았다는 점이다. 대신 각 서비스마다 '코드베이스 맵'을 만들었다. 200~500줄짜리 문서로, 핵심 파일 위치·통합 지점·인증 메커니즘·그리고 '증상별 파일 경로 매핑 테이블'을 담는다. 로그인 실패가 나오면 auth/strategies/를 보라, 결제 미완료면 contexts/payment.tsx를 보라는 식으로. 이 문서들은 코드에서 자동 생성된 게 아니다. 코드에 없는 지식—'이 웹훅 엔드포인트는 외부 결제 게이트웨이가 호출하기 때문에 의도적으로 인증이 없다', '이 서비스는 센트 단위지만 레거시 API는 원 단위다'—같은 운영 지식을 담는다. 시니어 개발자가 몇 달 만에 쌓는 그 맥락을.
쿠버네티스 운영 자동화 사례는 같은 원리를 인프라 영역으로 확장한다. 4계층이다. 사람이 의사결정을 위해 읽는 한국어 상세 계획서(Layer 1), AI가 즉시 현재 상태를 파악하는 영어 요약 대시보드(Layer 2), 단계별 실행 가이드인 Command Guardrails(Layer 3), 버전과 값을 파일로 고정하는 Helm Values(Layer 4). 위에서 아래로 갈수록 추상에서 구체로, 자유도는 감소하되 재현성은 증가하는 구조다. Layer 2를 영어로 쓰는 이유가 흥미롭다. 토큰 효율성 때문만이 아니다. 한국어 설명에서 영어 명령어로 전환하는 과정에서 오류가 발생한다. '누가 읽느냐'에 따라 언어를 구분한 것이다.
에이전트의 실패는 모델 문제가 아니라 설계 문제다
두 사례 모두 실패담을 숨기지 않는다. 버그 수정 사례에서는 AI가 원인을 파악하지 않고 optional chaining을 남발하는 패턴이 나왔다. 그래서 Bug Hunter 에이전트를 read-only로 제한했다. 진단만 하고 코드는 절대 건드리지 않는다. 구현은 Dev Front와 Dev Back이 각각 담당하고, QA Reviewer가 검증한다. 분석과 구현과 검증을 명시적으로 분리했다. 에이전트에게 '역할'을 부여한 게 아니라 '역할 경계'를 설계한 것이다.
쿠버네티스 사례는 더 직접적이다. 실제 사고가 2건 있었다. Guardrail 문서에 helm upgrade mimir만 적고 --version을 지정하지 않았더니 AI가 5.8.0 환경에서 최신 6.0.5로 자동 업그레이드했다. Breaking change 세 가지가 동시에 터지면서 ingester와 distributor 파드가 전부 CrashLoopBackOff에 빠졌다. 알림 규칙 사고에서는 AI가 합리적으로 보이는 파라미터 값을 만들어냈는데, 그게 운영 환경에서는 배포마다 새벽에 오경보를 울리는 설정이었다. 교훈은 단순하다. AI에게 해석의 여지를 주면 AI는 반드시 해석한다. 해석이 틀릴 수 있다. 버전도, 값도, 네임스페이스도, 타임아웃도—파일로 고정해서 해석할 것 자체를 없애야 한다.
이 원리는 CLAUDE.md로 이어진다. kubectl get/describe/logs만 허용하고 apply/delete/patch는 차단한다. 중요한 건 CLAUDE.md가 자연어 규칙이고, .claude/settings.local.json이 이를 실제 명령어 수준에서 강제한다는 점이다. 자연어 안내만으로는 충분하지 않다. 도구 레벨에서 막아야 프로덕션이 안전하다.
그렇다면 개발자는 무엇을 하나
velog의 한 글은 이 질문을 현장 감각으로 짚는다. AI는 '동작하는 코드'를 만드는 데 강하다. 외부 API 붙이는 작업을 시키면 http client 만들고 호출하고 응답 받는다. 끝. 근데 프로젝트에 이미 있는 컨벤션을 무시하고 자기 방식으로 만들고, 실패 케이스를 하나도 고려하지 않는다. 6개월 뒤에도 문제없는지, 트래픽을 견딜 수 있는지, 어디서 터지는지—이걸 의심하고 검증하는 건 사람이다. 요약하면 AI는 '이렇게 하면 됩니다'에 강하고, '이렇게 하면 나중에 터집니다'에 약하다.
세 사례를 겹쳐 보면 역할 분리가 보인다. 에이전트가 흡수하는 것들—반복적 탐색, 패턴이 명확한 구현, 정해진 순서의 실행. 사람이 설계해야 하는 것들—에이전트가 탐색할 맥락 문서, 에이전트가 실행할 범위의 경계, 에이전트가 생성한 결과의 구조적 검증 기준. 버그 수정 사례의 코드베이스 맵, 쿠버네티스 사례의 4계층 문서와 Command Guardrails—이것들은 AI를 위해 만든 문서지만 동시에 팀 전체의 운영 표준이 된다. AI를 위한 문서화가 팀의 지식 체계를 강제로 정비하는 효과를 낳는다.
설계 없는 자동화는 부채다
당장 내일 팀에 적용할 수 있는 기준으로 정리하면 이렇다. 첫째, 에이전트에게 코드베이스를 탐색하게 두기 전에 '어디를 보라'는 맥락 문서를 먼저 만들어라. 코드에서 생성 가능한 것들이 아니라, 코드에 없는 운영 지식을 담아야 한다. 둘째, 에이전트의 역할을 분리하되 경계를 명시적으로 설계하라. 분석 에이전트가 코드를 건드리지 않도록 read-only를 강제하는 것처럼, 경계는 자연어 가이드가 아니라 도구 레벨에서 강제해야 한다. 셋째, AI에게 해석의 여지를 최소화하라. 버전, 값, 파라미터—변수가 될 수 있는 모든 것을 파일로 고정해야 재현 가능한 운영이 된다.
에이전트가 DevOps를 흡수하는 속도는 예상보다 빠르다. 하지만 그 흡수가 안정적으로 작동하려면 에이전트를 위한 구조가 먼저 있어야 한다. 구조 없이 에이전트를 풀어놓으면 빠르게 망가진다. 반복 업무가 자동화될수록, 그 자동화가 실패하지 않도록 경계와 맥락과 검증을 설계하는 역할이 더 중요해진다. 코더가 줄어드는 게 아니라, 설계하는 사람이 더 필요해지는 구조다.