AI 에이전트 자동화는 성공했을 때보다 실패했을 때 기록이 더 중요하다. 실패 원인을 모르면 같은 문제가 반복되고, 어떤 작업이 실제로 실행됐는지 모르면 자동화를 신뢰하기 어렵다.
감사 로그는 거창한 시스템이 아니어도 된다. 개인 자동화라면 JSON 히스토리, outbox 폴더, PR URL, preview URL만으로도 충분한 출발점이 된다.
기본으로 남길 항목
AI 에이전트가 외부 작업을 수행한다면 최소한 실행 날짜, 선택된 입력 데이터, 생성 파일, 외부 요청 대상, 브랜치, PR URL, 빌드 결과, 실패 사유를 남기는 것이 좋다. 이 정보가 있어야 자동화가 실제로 무엇을 했는지 나중에 확인할 수 있다.
상태값을 단순하게 유지하기
상태값은 복잡할 필요가 없다. enqueued, pr_created, merged, failed, blocked 정도면 충분하다. 상태값이 명확하면 다음 자동화가 같은 작업을 중복 처리하지 않는다. 또한 사람이 대시보드를 볼 때 어디서 막혔는지 바로 알 수 있다.
outbox 폴더도 로그다
Slack outbox와 GitHub outbox는 단순 큐이지만 동시에 로그 역할도 한다. sent 폴더는 성공한 작업, failed 폴더는 실패한 작업, warnings 폴더는 핵심 작업은 성공했지만 부가 기록이 실패한 작업을 보여준다.
이런 폴더 구조는 데이터베이스 없이도 운영 상태를 확인하게 해준다. 특히 macOS 권한이나 네트워크 제한처럼 예측하기 어려운 오류를 추적할 때 유용하다.
PR과 preview URL을 남기는 이유
블로그 자동화에서는 GitHub PR과 Cloudflare preview URL이 가장 좋은 감사 로그다. PR에는 어떤 파일이 바뀌었는지 남고, preview에는 빌드가 성공했는지 남는다.
AI가 글을 만들더라도 main 브랜치에 바로 넣지 않고 PR을 거치면 문제가 생겼을 때 되돌리기 쉽다. 자동화가 만든 결과물을 사람이 검토하기도 좋다.
체크리스트
- 성공 로그와 실패 로그를 같은 수준으로 남긴다.
- 외부 토큰과 웹훅 URL은 로그에 저장하지 않는다.
- 큐 파일에는 실행에 필요한 최소 정보만 둔다.
- PR URL, preview URL, merge SHA를 히스토리에 저장한다.
- 실패한 작업은 자동으로 사라지지 않게 failed 폴더로 이동한다.
- 히스토리 업데이트 실패는 발행 실패와 분리한다.
감사 로그는 자동화를 느리게 만드는 장치가 아니다. 자동화가 더 오래 굴러가게 만드는 안전망이다.