작성 시점 2026-10-01 기준직접 경험읽기 5분

AI의 실수는 막을 수 있다: 사고가 규칙이 되기까지 — 낚시어때 개발기 3편

AI는 같은 실수를 반복한다. 낚시어때를 만들며 사고를 규칙으로 적고, 세 번 반복되면 검사 스크립트로 막은 과정과 네 가지 사례를 기록한다.

AI는 실수를 한다. 사람보다 자주 하지는 않지만, 같은 실수를 반복한다. 어제 한 실수를 오늘의 AI는 기억하지 못하기 때문이다. 낚시어때를 만들며 얻은 가장 큰 교훈은 이것이었다. 실수를 기억에 맡기지 말고 장치로 막는다. 과정은 세 단계로 흘렀다. 사고가 나고, 규칙을 적고, 규칙을 기계가 검사하게 했다. 6주 사이 CLAUDE.md(Claude Code가 프로젝트를 열 때 자동으로 읽는 규칙 파일)는 32개 조항이 됐다(9월 28일 기준).

사례 1: 끝난 브랜치에 여섯 번 더 올렸다

Claude Code는 작업을 브랜치에 올리고, 사람이 병합하면 끝난다. 그런데 AI가 병합이 끝난 브랜치에 추가 작업을 또 올리는 일이 반복됐다. 그 작업은 어디에도 병합되지 않고 떠돌았다. 규칙으로 「올리기 전에 병합 여부를 확인하라」고 적었지만 같은 일이 또 생겼다. 한 번은 AI가 상태를 조회해 「병합됨」을 화면에 찍어 놓고도 그대로 올렸다. 확인은 했는데 멈추지 않았다.

해결은 규칙이 아니라 도구였다. 올리기 전에 상태를 검사하고, 병합된 브랜치면 아예 올라가지 않게 막는 스크립트를 만들었다(9월 25일). 스크립트를 쓰는 것을 잊는 경우까지 막으려고 그냥 push도 가로채게 했다. 그 뒤로는 push 전에 스크립트가 PR 상태를 먼저 본다. 이 장치는 끝난 작업 브랜치를 막는 쪽이고, main에 직접 push하는 것을 저장소 설정으로 막는 방법은 GitHub Ruleset으로 main 보호하고 본인 PR만 병합하기에 정리했다.

장치도 처음엔 틀렸다. 도입 이틀 사이 스크립트를 두 번 고쳤다. 회차 태그를 올리는 것까지 막아서 태그는 따로 판정하게 했고, 문서만 바뀐 push는 허용했다. 막는 장치는 한 번 만들고 끝이 아니라, 오탐을 보며 다듬는 물건이었다.

사례 2: 초록불인데 죽어 있던 단계

배포가 끝나면 이슈에 자동으로 라벨을 붙이는 단계를 넣었다. 배포는 성공했고 화면에는 초록불이 켜져 있었다. 그런데 라벨은 하나도 붙지 않았다. 로그를 열어 보니 실행 환경에 필요한 프로그램이 없어 첫 줄에서 죽어 있었다. 그 단계는 「실패해도 배포는 계속한다」로 설정돼 있어서 실패가 초록불에 가려졌다.

고치고 나서 또 죽었다. 이번에는 권한 하나가 빠졌다. 같은 기능에서 9월 25일 하루에 같은 부류의 실수가 세 번 연속 나오자, 워크플로 파일을 읽어 이런 실수를 미리 찾는 검사를 만들었다. 도구를 먼저 준비했는지, 권한이 있는지, 실패를 요약에 남기는지를 본다. 실패해도 계속 가는 단계는 반드시 실패를 화면에 드러내도록 했다.

그 검사를 만든 다음 날, 검사 자체가 러너에서 죽었다. 응답을 꺼내는 데 쓴 도구가 러너에 없었다. 「도구가 있는지 먼저 보라」는 검사가 도구가 없어서 멈춘 것이다. 외부 도구 없이 돌게 고쳤다.

사례 3: 넣지도 않은 권한 때문에 심사 전에 멈췄다

iOS 심사 전 자동 검사에서 「마이크 사용 목적 문구가 부족하다」며 멈췄다. 낚시어때는 마이크를 쓰지 않는다. 원인은 사진 첨부용 라이브러리가 기본값으로 마이크·카메라 권한 문구를 앱 설정에 몰래 넣어 둔 것이었다. 라이브러리들이 넣은 기본 영어 문구가 여섯 개였다. 우리 설정 파일에는 그 줄이 없었으니, 설정 파일을 들여다보는 방식으로는 찾을 수 없었다.

그래서 검사를 바꿨다. 설정 파일이 아니라 실제로 만들어진 앱 설정을 생성해서 읽는 검사다. 그런데 다음 빌드는 이 검사를 통과하고도 업로드에서 막혔다. 이번에는 위치 라이브러리가 동작 감지 문구를 요구했다. 검사가 이 문구를 「있어야 할 문구」가 아니라 「없어야 할 문구」로 잘못 알고 있었다. 앱이 부르지 않아도 라이브러리 코드에 참조가 남아 있으면 문구가 필요했다. 우리 의도가 아니라 바이너리가 실제로 참조하는 것을 검사해야 한다.

사례 4: 되돌리는 명령이 기획서를 지웠다

9월 20일, AI가 브랜치를 옮기면서 「작업 폴더를 원래대로 되돌리는」 명령을 다른 명령과 한 줄로 이어 붙였다. 그 한 줄이 막 넣어 둔 기획서 수정본 세 개를 지웠다. 다행히 다운로드 폴더에 압축본이 남아 있어 복구했다.

사실 8월 23일에도 같은 일로 기획서를 날려 규칙이 있었다. 브랜치를 옮기는 명령에 섞여 있어 어기는 줄 몰랐다. 이 사고 뒤에 생긴 규칙은 짧다. 되돌리는 명령은 다른 명령과 한 줄에 엮지 않는다. 바로 앞에서 상태를 따로 확인한다. 원인은 명령 자체보다 「지금 위험한 명령을 쓰고 있다」는 자각이 없었던 데 있었다.

규칙의 무게를 나눴다

모든 규칙을 장치로 만들 필요는 없었다. 쓴 기준은 이랬다.

  • 한 번 난 실수: 규칙으로 적어 둔다
  • 두 번 난 실수: 규칙에 사례를 붙인다
  • 세 번 난 실수, 또는 한 번이라도 되돌릴 수 없는 피해: 기계가 막게 한다

원칙은 세 번이었지만, 병합된 브랜치 push는 여섯 번째에야 장치로 막았다.

사고 기록이 쌓이는 문서 체계는 2편에, 사람이 확인하는 배포 순서는 6편에 있다.

가져다 쓸 것

  • AI 규칙 파일(Claude Code라면 CLAUDE.md)을 두고, 사고가 날 때마다 한 줄씩 더한다.
  • 같은 실수가 세 번이면 검사 스크립트로 바꾼다. 규칙을 더 강하게 쓰는 것보다 효과가 크다.
  • 「실패해도 계속」 단계는 실패를 반드시 보이게 한다. 조용한 실패가 가장 찾기 어렵다.
  • 설정 파일이 아니라 실제 결과물을 검사한다. 라이브러리가 몰래 넣는 것은 결과물에만 나타난다.
  • 되돌릴 수 없는 명령(삭제, 초기화)은 따로, 확인 뒤에 실행하게 한다.

이 글은 2026-10-01 기준으로 헥사허브가 직접 겪은 일을 적었습니다.