가장 흔한 AI 코딩 에이전트의 실패를 막는 10가지 한 줄 규칙

여러 AI 에이전트 사용 경험을 통해 배운 실패 패턴과 규칙 10가지

저는 Claude Code, Cursor, Codex, Grok 에이전트를 실제 프로젝트에 나란히 두고 실행해 왔으며, 종종 밤새도록 방치하기도 했습니다. 수백 번의 세션 이후, 실패가 무작위적으로 보이지 않게 되었습니다. 항상 같은 몇 가지 패턴만 반복해서 나타나며, 이들 대부분은 규칙 파일(rules file)에 단 한 줄을 추가하는 것만으로도 해결할 수 있었습니다.

제가 가장 많은 비용을 치렀던 10가지 사례와 현재 CLAUDE.md / AGENTS.md에 유지하고 있는 규칙을 소개합니다.

1. 의도가 결과로 보고되는 경우 (Intent reported as result)

발견할 수 있는 상황: "설정을 업데이트했습니다."라고만 표시되고 실제 파일은 변경되지 않은 상태입니다.

규칙: 파일을 다시 읽고 변경된 줄을 인용(quoting)한 후에만 변경 사항을 보고하라.

2. 테스트를 주장했으나 실행하지 않은 경우 (Tests claimed, never run)

발견할 수 있는 상황: "모든 테스트가 통과했습니다"라는 메시지만 있고, 트랜스크립트 어디에도 명령어 출력(command output)이 없습니다.

규칙: 정확한 명령어와 그 출력이 없으면 절대 테스트가 통과했다고 주장하지 마라.

3. 부분적 성공을 전체로 간주하는 경우 (Partial success rounded up)

발견할 수 있는 상황: 5개 항목 중 3개만 완료되었는데, 요약이 "완료!"라고 되어 있습니다.

규칙: 모든 작업은 다음 중 하나로 끝내라: Done (증거와 함께) / Not done / Unverified.

4. 도구 오류를 무시하는 경우 (Swallowed tool error)

발견할 수 있는 상황: 종료 코드(Exit code)가 1로 표시된 후, "좋아, 작동했군."이라는 식의 해석이 이어집니다.

규칙: 모든 명령어 실행 후에는 결과를 해석하기 전에 반드시 종료 코드를 명시하라.

5. 실패하는 테스트가 조용히 사라지는 경우 (The failing test quietly disappears)

발견할 수 있는 상황: @skip 태그를 사용하거나 검증(assertion)을 느슨하게 만들고, CI 파이프라인이 녹색으로 변합니다.

규칙: 승인을 받지 않고 테스트를 건너뛰거나(skip), 삭제하거나, 완화하여 통과하게 만들지 마라.

6. 조작된 경로 및 링크 (Fabricated paths and links)

발견할 수 있는 상황: 존재하지 않는 파일이나 URL을 자신감 있게 참조합니다.

규칙: 이번 세션에서 열었던 경로와 URL만 인용하라.

7. 충돌하는 규칙 파일 (Conflicting rule files)

발견할 수 있는 상황: CLAUDE.md는 한 가지를 말하고, .cursorrules는 다른 것을 말하는데, 에이전트가 둘 중 하나를 선택하고 사용자에게 알리지 않습니다.

규칙: 두 개의 지침 파일(instruction files)이 충돌하는 경우, 두 내용을 모두 인용하여 질문하라.

8. 사과 루프 (The apology loop)

발견할 수 있는 상황: "당신 말이 전적으로 맞습니다, 죄송합니다!"라는 말을 듣고 난 후, 동일한 명령어를 다시 실행합니다.

규칙: 수정 지시를 받았을 때는 행동을 변경하고 그 교훈을 이 파일에 기록하라.

9. 너무 많이 요구했다가 충분하지 않은 경우 (Asking too much, then not enough)

확인할 내용: 매 2단계마다 권한 요청이 나타나고, 그 후 예상치 못한 git push --force가 실행됩니다.

규칙: 파괴적(destructive), 외부적 또는 유료 행동을 하기 전에는 반드시 질문하고; 되돌릴 수 있는 행동에 대해서만 진행합니다.

10. 다음 세션이 당신의 작업을 취소함

확인할 내용: 내일의 에이전트가 오늘 당신이 의도적으로 변경한 내용을 "정리"합니다.

규칙: 각 세션을 '목표, 상태, 다음 단계, 열린 위험'을 담은 인계 노트(handoff note)로 마무리해야 합니다.

복사-붙여넣기 블록 (The copy-paste block)

- 파일을 다시 읽고 변경된 줄을 인용하여 변화를 보고합니다.
- 정확한 명령어와 그 출력이 없으면 테스트가 통과했다고 절대 주장하지 마십시오.
- 모든 작업은 '완료 (증거 제시)' / '미완료' / '검증되지 않음'으로 끝내야 합니다.
...

이 내용은 GitHub에서도 무료로 이용 가능합니다: agent-ops-samples/top-10-agent-rules.md.

나머지 30가지

이 열 가지는 제가 가지고 있는 목록의 4분의 1에 불과합니다. 나머지는 대기 명령(hung watch commands), 잘못된 작업 디렉터리, 로그에 노출되는 비밀 정보(secrets echoed into logs), 숨겨진 macOS 권한 프롬프트, 조작된 라이브러리 API, 버그를 숨기는 오류 처리 방식, diff와 모순되는 요약, 그리고 장기 실행 드리프트(long-run drift) 등을 다룹니다. 저는 증상과 한 줄 수정 방안을 모두 포함하여 총 40가지 패턴을 인쇄 가능한 3페이지 치트 시트에 담았습니다: 40 AI 코딩 에이전트 실패 패턴 및 한 줄 수정 방안 ($3).

만약 직접 만든 규칙 파일에 검토를 받고 싶으시다면, 저는 CLAUDE.md / AGENTS.md / .cursorrules 중 하나에 대해 $9 빠른 검토를 진행합니다. 이 검토에는 충돌하는 내용, 모호한 규칙, 누락된 가드 레일(guard rails), 그리고 바로 붙여넣을 수 있는 5가지 수정 방안이 포함됩니다.

어떤 실패가 가장 큰 비용을 발생시키나요? 저는 다음 버전을 위해 더 많은 사례를 수집하고 있습니다.