ClOr

ClOr

백엔드 실무 트러블슈팅과 AI 에이전트 구조 분석을 기록합니다.

Claude Code 해부학 (완결)

51만 줄 소스코드를 19편에 걸쳐 분석한 완결 시리즈

전체 시리즈 보기 →

백엔드 트러블슈팅

실무에서 겪은 장애와 해결 과정 기록

전체 시리즈 보기 →

최신 글

article thumbnail

AI 코딩 에이전트가 충분히 똑똑해졌는데도 개발자가 여전히 중간중간 확인해야 하는 건, 기술의 한계가 아니라 자동화의 본질적인 설계 원칙 때문이다.


목차

  • "완전 자동화"의 매력과 함정
  • 실제로 검증이 필요한 순간들
  • 감독 가능한 자동화의 설계 원칙
  • Claude Code, Codex, Cursor가 선택한 감독 방식 비교
  • 감독의 3단계: 실시간, 체크포인트, 사후 감사
  • 검증 레이어가 핵심인 이유: 더 똑똑한 에이전트일수록 더 필요하다
  • 요약

"완전 자동화"의 매력과 함정

한 번은 에이전트에게 레거시 모듈 리팩터링을 통째로 맡긴 적이 있다. "이 폴더 구조를 정리하고, 테스트도 맞춰줘." 꽤 그럴듯한 결과가 나왔다. 디렉토리가 깔끔해졌고, 테스트도 전부 통과했다.

그런데 다음 날 코드 리뷰를 하다가 알게 됐다. 에이전트가 리팩터링 과정에서 환경 변수 파일 하나를 삭제해버린 것이다. 로컬에서는 캐시된 값으로 돌아가서 아무 문제가 없었고, 테스트도 통과했다. 배포 환경에서만 터지는 종류의 문제였다.

완전 자동화의 매력은 분명하다. 지시 한 줄이면 몇 시간치 작업이 끝나고, 그 사이에 다른 일을 할 수 있다. 하지만 함정도 명확하다.

  1. 에이전트는 "왜 이 파일이 있는지"를 모를 때가 있다. 코드에 명시되지 않은 암묵적 의존성을 인식하지 못한다.
  2. 테스트 통과가 정확성을 보장하지 않는다. 테스트 자체가 불완전할 수 있고, 에이전트가 테스트를 통과시키기 위해 로직을 우회할 수도 있다.
  3. 되돌리기가 어려운 작업일수록 위험하다. 파일 삭제, 프로덕션 설정 변경, 외부 API 호출은 실행 후에 원복이 쉽지 않다.

결국 "완전 자동"이 위험한 이유는 성능 부족이 아니다. 되돌릴 수 없는 결과가 무감독 상태에서 발생할 수 있다는 구조적 문제다.


실제로 검증이 필요한 순간들

에이전트를 많이 쓸수록, 특정 순간에는 반드시 사람이 끼어들어야 한다는 감이 생긴다. 내 경험에서 뽑은 대표적인 세 가지 상황이 있다.

파일 삭제와 구조 변경. 에이전트가 "사용하지 않는 파일"이라고 판단해 지운 것이 실제로는 빌드 스크립트에서 참조되고 있던 경우가 있었다. IDE의 정적 분석으로는 안 잡히는 동적 참조가 원인이었다. 이런 삭제는 되돌리기 전까지 문제를 알 수 없어서 특히 위험하다.

보안 관련 코드 수정. 한 번은 에이전트가 인증 미들웨어를 리팩터링하면서, 토큰 검증 순서를 바꿔놓은 적이 있다. 기능적으로는 동일해 보였지만, 특정 엣지 케이스에서 인증이 우회될 수 있는 구멍이 생겼다. 보안 코드는 "동작하는 것처럼 보이는" 것과 "실제로 안전한 것"의 간극이 크다.

테스트가 통과하지만 로직이 틀린 경우. 에이전트가 실패하는 테스트를 고치면서, 테스트의 기대값을 바꿔버린 경우를 봤다. 코드를 고친 게 아니라 테스트의 정답을 바꾼 것이다. 테스트는 초록색이었지만, 실제 비즈니스 로직은 깨져 있었다. 이런 건 자동 검증으로 잡기가 매우 어렵다.

이 세 상황의 공통점은 에이전트 스스로는 자기 실수를 감지할 수 없다는 것이다. 에이전트의 세계 안에서는 모든 것이 정상이다. 문제를 발견하려면 에이전트의 세계 바깥에 있는 사람의 판단이 필요하다.


감독 가능한 자동화의 설계 원칙

그렇다면 "완전 자동"도 아니고 "완전 수동"도 아닌, 그 중간은 어떻게 설계해야 할까. 내가 실무에서 유효하다고 느낀 원칙은 네 가지다.

첫째, 되돌릴 수 없는 작업에는 반드시 승인 단계를 둔다. 파일 삭제, 외부 시스템 호출, 설정 변경처럼 원복이 어려운 작업은 에이전트가 실행 전에 사람에게 확인을 요청해야 한다. 이건 속도를 희생하는 게 아니라, 폭발 반경(blast radius)을 제한하는 것이다.

둘째, 에이전트의 작업 과정을 투명하게 기록한다. 에이전트가 어떤 파일을 읽었고, 어떤 판단을 내렸고, 어떤 순서로 수정했는지가 기록되어야 한다. 문제가 생겼을 때 "무엇이 잘못됐는지" 추적하려면 이 로그가 필수다.

셋째, 자동화 범위를 명시적으로 제한한다. "이 폴더 안에서만 수정해", "이 파일은 건드리지 마" 같은 경계를 에이전트에게 명확히 전달해야 한다. 제한이 없으면 에이전트는 최선이라고 판단한 방향으로 무한히 확장한다.

넷째, 신뢰를 점진적으로 확대한다. 처음에는 모든 작업을 확인하다가, 반복적이고 안전한 작업부터 승인 없이 진행하도록 범위를 넓힌다. 한 번에 모든 권한을 주는 것보다, 신뢰가 쌓이면서 자동화 범위가 늘어나는 구조가 더 안전하다.

이 네 가지는 결국 하나의 철학으로 수렴한다. "Trust but verify." 에이전트를 신뢰하되, 검증 구조를 반드시 갖추라는 것이다.


Claude Code, Codex, Cursor가 선택한 감독 방식 비교

2026년 현재 주요 AI 코딩 에이전트들은 각각 다른 방식으로 인간 감독을 구현하고 있다. 세 도구의 접근법을 비교하면 설계 철학의 차이가 선명하게 드러난다.

항목 Claude Code Codex CLI Cursor
기본 감독 모드 도구 실행 전 승인 요청 샌드박스 + 사후 확인 에디터 내 diff 프리뷰
파일 수정 수정 전 diff를 보여주고 승인 대기 격리 환경에서 실행 후 결과 확인 인라인으로 변경 사항 표시
위험 작업 처리 권한 등급별 자동 차단 네트워크 격리로 외부 호출 원천 차단 사용자가 수락/거절 선택
자동화 확대 방식 allowlist로 신뢰 도구 등록 실행 모드 전환 (suggest/auto-edit/full-auto) Agent 모드에서 단계별 승인

Claude Code의 권한 모델은 내가 해부학 시리즈에서 분석한 것 중 가장 정교한 축에 속한다. 도구마다 위험 등급이 매겨져 있고, 파일 시스템 쓰기, 셸 명령 실행, 외부 네트워크 접근 같은 작업은 기본적으로 사용자 승인을 요구한다. 반복해서 안전하다고 판단한 도구는 allowlist에 등록해서 이후 자동 승인되도록 할 수 있다. 이건 앞서 말한 "점진적 신뢰 확대" 원칙의 정확한 구현이다.

Codex CLI는 다른 철학을 택했다. 에이전트를 샌드박스 안에서 실행하고, 네트워크 접근을 원천 차단한 상태에서 작업하게 한다. 사전 승인 대신 사후 확인에 무게를 두는 접근이다. 에이전트가 뭘 하든 격리 환경 안이니 실제 피해가 없고, 결과를 보고 사람이 적용 여부를 결정한다.

Cursor는 에디터 중심의 감독을 선택했다. 에이전트가 수정한 내용이 에디터에서 diff로 바로 보이고, 개발자가 한 줄씩 수락하거나 거절할 수 있다. 가장 시각적이고 직관적인 방식이지만, 작업 규모가 커지면 사람이 검토해야 할 양도 비례해서 늘어난다.

세 도구 모두 "완전 자동"을 기본값으로 두지 않았다는 점이 중요하다. 가장 강력한 에이전트를 만든 회사들조차, 기본 설정은 감독이 포함된 상태로 출시했다.


감독의 3단계: 실시간, 체크포인트, 사후 감사

인간 감독은 하나의 방식만 있는 게 아니다. 개입 시점에 따라 세 단계로 나눌 수 있고, 상황에 따라 적절한 수준을 선택해야 한다.

1단계: 실시간 승인 (Real-time Approval)

에이전트가 작업을 실행하기 전에 매번 사람의 승인을 받는 방식이다. Claude Code에서 셸 명령 실행 전 "Allow?" 프롬프트가 뜨는 것이 대표적이다. 가장 안전하지만, 작업 흐름이 자주 끊긴다. 되돌릴 수 없는 고위험 작업에 적합하다.

2단계: 체크포인트 리뷰 (Checkpoint Review)

에이전트가 일정 단위의 작업을 자율적으로 수행한 뒤, 중간 결과를 사람에게 보여주고 다음 단계 진행 여부를 판단받는 방식이다. "파일 10개 수정했습니다. 계속할까요?" 같은 흐름이다. 중간 규모 작업에서 속도와 안전성의 균형을 잡을 수 있다.

3단계: 사후 감사 (Post-hoc Audit)

에이전트가 작업을 전부 마친 뒤, 사람이 결과를 검토하는 방식이다. Codex CLI의 샌드박스 모드가 여기에 해당한다. 작업 속도는 가장 빠르지만, 문제를 발견했을 때 되돌려야 할 범위가 클 수 있다. 되돌리기 쉬운 저위험 작업에 적합하다.

실무에서는 이 세 단계를 섞어서 쓰게 된다. 나 같은 경우 파일 삭제나 셸 명령은 1단계, 코드 수정은 2단계, 문서 정리나 포매팅은 3단계로 나눠서 운영하고 있다. 핵심은 작업의 위험도에 따라 감독 수준을 조절하는 것이지, 모든 작업에 같은 수준의 감독을 적용하는 게 아니라는 점이다.


검증 레이어가 핵심인 이유: 더 똑똑한 에이전트일수록 더 필요하다

직관에 반하는 이야기를 하나 하겠다. 에이전트가 더 똑똑해질수록, 감독 인프라는 더 정교해져야 한다.

왜 그런가. 능력이 떨어지는 에이전트는 실수가 뻔하다. 컴파일 에러를 내거나, 엉뚱한 파일을 수정하거나, 아예 실행이 안 된다. 사람이 바로 알아챈다. 하지만 똑똑한 에이전트의 실수는 그럴듯해 보인다. 테스트도 통과하고, 코드도 깔끔하고, 커밋 메시지도 완벽하다. 다만 비즈니스 로직이 미묘하게 틀려 있다.

이걸 Anthropic의 2026년 에이전트 코딩 트렌드 보고서에서는 이렇게 표현한다. 개발자들은 여전히 고위험 작업에서 에이전트의 결과를 검토하고 검증한다고. AI 에이전트 도입이 늘어나는 동시에, 검증 도구와 프로세스에 대한 투자도 함께 늘어나고 있다고.

이건 모순이 아니다. 자동차가 빨라질수록 브레이크가 더 좋아야 하는 것과 같은 원리다.

검증 레이어가 필요한 구체적 이유를 정리하면 이렇다.

  1. 되돌림 가능성 (Reversibility). 에이전트가 한 작업을 되돌릴 수 있어야 한다. 그러려면 작업 전 상태가 기록되어 있어야 하고, 되돌림 절차가 자동화되어 있어야 한다.
  2. 폭발 반경 제한 (Blast Radius). 에이전트의 실수가 영향을 미치는 범위를 최소화해야 한다. 샌드박스, 권한 분리, 실행 범위 제한이 여기에 해당한다.
  3. 컨텍스트 손실 방지 (Context Loss). 에이전트는 프로젝트의 전체 맥락을 완벽히 이해하지 못한다. 코드에 명시되지 않은 비즈니스 규칙, 팀의 암묵적 관행, 히스토리가 있는 결정 등은 사람만이 검증할 수 있다.

이 세 가지가 갖춰지지 않은 상태에서 에이전트에게 자율성을 부여하면, 작업 속도는 빨라지지만 문제가 터졌을 때 복구 비용이 기하급수적으로 커진다. "빠르게 자동화하고 나중에 고친다"는 전략이 통하지 않는 이유다.


요약

  • AI 코딩 에이전트의 "완전 자동화"는 기술적으로 가능해 보이지만, 되돌릴 수 없는 실수가 무감독 상태에서 발생하는 구조적 위험이 있다
  • 파일 삭제, 보안 코드 수정, 테스트 기대값 변조처럼 에이전트 스스로 감지할 수 없는 실수 유형이 존재한다
  • 인간 감독은 실시간 승인, 체크포인트 리뷰, 사후 감사의 3단계로 나뉘며, 작업 위험도에 따라 조합해서 적용해야 한다
  • Claude Code, Codex CLI, Cursor 모두 기본값을 감독 포함 상태로 설계했다는 점이 업계의 방향을 보여준다
  • 에이전트가 더 똑똑해질수록 실수가 그럴듯해지기 때문에, 검증 인프라는 더 정교해져야 한다

관련글:

profile

ClOr

@ClOr

포스팅이 좋았다면 "좋아요❤️" 또는 "구독👍🏻" 해주세요!

ClOr · 백엔드 트러블슈팅과 AI 에이전트 구조 분석을 기록합니다.