Let Your AI Fix Its Own Broken Automation: Building an Unattended Watchdog

개요

기술 블로거 Lily는 자동화 스크립트의 고장을 AI가 감지, 복구, 검증하고 검증 통과 시 승인 없이 프로덕션에 푸시하는 '무인 감시자(unattended watchdog)' 설계 및 구현 방법을 설명합니다.

주요 내용

* 무인 감시자의 필요성: 대량의 사이드 프로젝트를 생산할 때 자동화 스크립트 수가 증가하고, 이들의 고장을 수동으로 모니터링하고 수정하는 데 한계가 있어 AI 기반 자가 복구가 필요합니다.
* 자가 복구 메커니즘: self-repair.sh 스크립트는 자동화 스크립트의 고장을 감지(detect)하고, Claude AI가 원인을 파악하여 수정(repair)하며, 감시자가 독립적으로 검증(verify)합니다. 검증이 성공하면 변경 사항을 커밋하고 푸시하며, 실패 시 롤백하고 인간에게 알립니다. Claude의 자체 보고를 신뢰하지 않고 감시자 자체 검증을 수행하는 것이 핵심입니다.
* 구조: 감시자는 registry.tsv에 모니터링할 프로젝트 목록을 등록하고, 각 프로젝트별 health.sh(건강 상태 점검)와 verify.sh(수리 후 검증) 스크립트를 사용합니다.
* registry.tsv 형식: slug, dir, mode 세 개의 열로 구성됩니다. mode는 full(감지+수리) 또는 detect(감지+알림)로 설정 가능합니다.
* health.sh 및 verify.sh 작성: health.sh는 현재 고장 상태를 결정하고, verify.sh는 수리 후 실제 작동 여부를 판단합니다. verify.sh는 health.sh보다 더 엄격하거나 동일할 수 있으며, Claude 수리 프로세스와 독립적으로 실행되어야 합니다.
* 7가지 가드레일(Guardrails): AI의 무인 수리가 안전하게 작동하도록 하는 안전 장치입니다.
1. 독립적 검증: Claude의 자체 보고를 신뢰하지 않고 감시자 자체적으로 verify.sh를 실행합니다.
2. 실패 시 즉시 롤백: verify.sh 실패 시 git reset --hard를 통해 이전 상태로 복구하고, 추가된 파일을 git clean으로 제거하며, 스테이싱된 내용을 삭제합니다.
3. 비밀번호 스캔: 커밋 전에 git diff --cached를 통해 API 키, 비밀 키 등을 포함한 민감한 정보가 포함되었는지 정규 표현식으로 스캔합니다. .env 파일이 추적 대상에 포함되면 즉시 실패 처리됩니다.
4. 시도 횟수 제한 (Attempt Cap): 하루에 동일한 슬러그에 대해 최대 시도 횟수(기본 2회)를 초과하면 수리를 건너뛰고 인간에게 알립니다.
5. 비용 제한 (Cost Cap): 특정 시간 동안의 Claude Code 출력 토큰이 예산 임계값을 초과하면 전체 실행 주기를 건너뜁니다.
6. 범위 제한 (allowedTools): Claude가 사용할 수 있는 도구를 Read, Write, Edit, Bash, Grep, Glob 등으로 제한하고, 작업 범위를 프로젝트 디렉토리로 명시합니다.
7. 푸시 대상 소유자 검증: GitHub 원격 저장소가 자신의 계정 소유인지 확인한 후 푸시하여 제3자 포크에 실수로 쓰기 방지합니다.
* AI 복구 요청 프롬프트: health.sh 출력 및 최근 로그를 문맥으로 제공하고, .env 및 민감 정보 접근 금지, verify.sh 실행 확인, 수정 불가 시 UNFIXABLE: 응답 등의 제약을 명시합니다.
* 기본 라인 기록 및 스테이싱: 수리 전에 현재 HEAD를 기본 라인으로 기록하고, 커밋되지 않은 변경 사항은 git stash -u로 스테이싱하여 롤백 시 깨끗하게 복구되도록 합니다.
* "감지 전용" 모드: mode=detect 설정 시 Claude를 호출하지 않고 고장 사실만 감지하여 알림을 보냅니다. Git으로 관리되지 않거나 자동 복구가 위험한 프로젝트에 사용됩니다. verify.sh가 없는 경우에도 자동으로 이 모드로 전환됩니다.
* launchd를 통한 실행: launchd plist를 통해 주기적으로 실행되며, PATH 설정 등 launchd 환경에서의 잠재적 문제를 고려해야 합니다.
* 주의 사항: git stash -u 누락으로 인한 롤백 오류, health.sh와 verify.sh를 동일하게 사용하는 것의 무의미함, 직접 비밀번호 스캔 로직 구축의 중요성, gtimeout 부재 시 타임아웃 기능 문제, 스크립트 범위 외부의 문제(예: .env 파일 만료, DB 스키마 오류)는 감시자 범위 밖이라는 점 등을 언급합니다.
* 요약: registry.tsv에 등록된 프로젝트에 대해 자동 감지, AI 기반 복구, 독립적인 검증, 비밀번호 스캔, 롤백 등 7가지 가드레일을 통해 안전한 무인 자동 복구를 수행합니다. Git 외부 문제 등은 "감지 전용" 모드로 처리하며, AI 프롬프트에 "UNFIXABLE:" 응답 옵션을 제공하여 범위를 벗어나는 수정 시도를 방지합니다.

시사점

이 무인 감시자 시스템은 자동화 스크립트의 복잡성과 빈도 증가에 따라 발생하는 고장 대응 비용을 절감하고, 수동 개입 없이도 안정적인 서비스 운영을 가능하게 하는 실용적인 해결책을 제시합니다. health.sh와 verify.sh 스크립트 개발이라는 초기 투자 비용은 있지만, 장기적으로 운영 안정성과 비용 효율성을 크게 향상시킬 수 있습니다.