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

원문(hashnode)은 Cloudflare 봇 검증에 막혀 읽지 못했어요. 아래는 GeekNews 소개글에 공개된 내용만 옮긴 것이고, 15가지 전체 목록과 설정 예시는 원문에 있어요.

코딩 에이전트(Claude Code·Codex·Gemini CLI)를 몇 주 쓰다 보면 "일은 많이 했는데 실제로 반영된 건 없는" 상태가 되기 쉬워요. 글쓴이는 그 원인이 대부분 모델 성능이 아니라 운영 설정에 있다고 보고, 실제 저장소에서 반복되는 실패 패턴과 가드레일을 정리했어요.

소개된 패턴과 해결법

• 증거 없는 "완료": 완료 기준에 "실행한 명령과 실제 결과"를 반드시 넣게 해요. "테스트 통과"가 아니라 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도 함께 제공된다고 해요.