AI 코딩 에이전트(Claude Code·Codex·Gemini CLI) 세팅이 실패하는 15가지 패턴과 해결법

코딩 에이전트를 몇 주 쓰다 보면 "일은 많이 했는데 실제로 반영된 건 없는" 상태가 돼요. 원인은 대부분 모델 성능이 아니라 운영 설정이에요.

증거 없는 "완료": 완료 기준에 "실행한 명령과 실제 결과"를 꼭 넣게 해요. "테스트 통과"가 아니라 "make test → 42 passed in 6.1s"처럼요. 고치는 시도는 3번까지만 하고, 넘으면 멈추고 보고하게 해요. 실패하는 테스트를 지워버리는 일이 이걸로 사라져요.

도구마다 다른 지침: 규칙은 AGENTS.md 하나에 두고, CLAUDE.md는 @AGENTS.md로 불러오고, Gemini는 context.fileName으로 읽게 해요. 지침이 서로 달라지면 CI에서 걸리게 해둬요.

sandbox와 approval 혼동: sandbox는 접근할 수 있는 경계이고, approval은 경계를 넘으려 할 때 어떻게 처리할지예요. Codex의 approval_policy = "never"는 권한을 넓히는 설정이 아니라, 경계를 넘는 작업을 묻지 않고 실패시키는 설정이에요. 새벽 배치가 아무것도 안 한 이유가 보통 이거예요. 참고로 untrusted는 이제 지원되지 않아요.

프롬프트 속 "하지 마": 이런 규칙은 PreToolUse 훅으로 옮겨요. exit 2로 끝나면 실행이 막히고, 이유가 에이전트에게 전달돼요. 정규식 20줄 정도로 rm -rf, 강제 push, curl | sh, .env 읽기를 막을 수 있어요.

리뷰어가 코드를 고쳐버림: 리뷰어 서브에이전트에는 Edit 권한을 주지 않아요. 아니면 다른 CLI를 read-only 프로필로 돌려서 교차 리뷰를 해요.

기억이 서로 모순됨: 기억을 세 층으로 나눠요. 턴 로그, 하루 요약(40줄 이하), 장기 기억(120줄 이하)이에요. 매주 반복해서 나온 것만 장기 기억으로 올리고, 오래된 건 지워요.

타임아웃 뒤 중복 실행: 외부로 나가는 작업에는 멱등성 키를 붙이고, 응답을 못 받으면 unknown 상태로 둬요. 다시 보내기 전에 상대 시스템에서 실제로 처리됐는지부터 확인해요.

15가지 전체와 설정 예시는 링크한 글에 있고, 4쪽짜리 무료 PDF도 있어요. 빠진 실패 패턴이 있으면 알려주세요.