AI 블로그 자동화에서 실패 보고서를 복구 지도로 쓰는 법

요약

Futory처럼 Next.js Markdown 블로그를 무인 크론으로 발행할 때 실패 보고서는 단순한 알림이 아니라 복구 지도여야 합니다. “빌드 실패”라고만 남기면 운영자는 다시 접속해서 명령을 찾고, 로그를 뒤지고, 어떤 단계까지 안전했는지 추측해야 합니다. 반대로 실패한 명령, 작업 디렉터리, 새로 만든 파일, 백업 경로, 중단 지점을 함께 남기면 보고서 자체가 다음 조치 목록이 됩니다.

AI 블로그 자동화의 좋은 실패 보고서는 짧지만 구체적입니다. 오늘 날짜 중복 검사는 통과했는지, 백업은 만들어졌는지, Markdown 파일은 어느 slug로 생성됐는지, npm run test:content, npm run test:theme, npm run build 중 어디서 멈췄는지, PM2 재시작과 공개 URL 검증은 실행됐는지 또는 실행하지 않았는지를 분명히 구분합니다. 이 글은 Futory의 평일 발행 루틴에서 실패 보고를 어떻게 복구 가능한 운영 자료로 만드는지 정리합니다.

실패 보고서는 왜 운영 자산인가

자동화가 매일 같은 일을 반복할수록 성공 로그는 짧아도 됩니다. 하지만 실패 로그는 다음 사람이 바로 이어받을 수 있을 만큼 정돈되어야 합니다. 특히 무인 발행에서는 실패가 발생한 순간 사용자가 옆에 있지 않습니다. 보고서가 모호하면 장애 대응은 다음 확인 작업부터 다시 시작되고, 그 사이 공개 사이트는 오래된 상태로 남을 수 있습니다.

성공한 단계와 실패한 단계를 분리한다

가장 중요한 원칙은 “무엇이 됐고 무엇이 안 됐는지”를 한 문장에 섞지 않는 것입니다. 예를 들어 콘텐츠 테스트는 통과했지만 빌드가 실패했다면, Markdown 구조 자체는 대체로 괜찮고 Next.js 빌드 단계에서 확인해야 한다는 뜻입니다. 반대로 test:content에서 멈췄다면 frontmatter, 필수 섹션, 날짜 형식을 먼저 봐야 합니다.

이 분리가 없으면 운영자는 PM2를 재시작해야 하는지, 새 파일을 되돌려야 하는지, 아니면 단순히 본문 문법을 고치면 되는지 판단하기 어렵습니다. Futory의 보고서는 각 단계에 PASS, FAIL, SKIP 같은 고정 단어를 붙이면 읽기 쉬워집니다.

중단 지점은 안전장치다

빌드가 실패했는데 PM2를 재시작하면 공개 런타임에 불완전한 상태를 반영할 수 있습니다. 그래서 실패 보고에는 “PM2 재시작 미실행”처럼 하지 않은 일도 적어야 합니다. 이 문구는 변명이 아니라 안전장치입니다. 자동화가 어디서 멈춰야 하는지 알고 있었다는 증거이기 때문입니다.

Futory 발행 루틴의 실패 지도

Futory의 발행 루틴은 크게 시간 게이트, 중복 게이트, 백업, 파일 생성, 로컬 검증, 빌드 산출물 확인, PM2 재시작, 공개 검증으로 나뉩니다. 실패 보고서는 이 순서를 그대로 따라가면 됩니다.

시간과 중복 단계

KST 기준 평일인지, 오늘의 결정적 선택 시간이 맞는지, 오늘 날짜 글이 이미 있는지를 먼저 기록합니다. 이 단계에서 SKIP되면 아무 파일도 만들지 않았다는 점이 핵심 증거입니다. 사용자는 왜 글이 없느냐고 묻기보다 “오늘은 선택 시간이 아니었구나” 또는 “이미 오늘 글이 있구나”를 바로 이해할 수 있습니다.

백업과 파일 생성 단계

선택 시간이고 중복도 없다면 백업 경로와 크기를 남깁니다. 백업은 실패 후 복구의 기준점입니다. 그다음 새 Markdown 파일의 절대 경로, slug, 제목, 날짜를 기록합니다. 이 정보가 있어야 운영자가 필요할 때 파일 하나만 열어 수정하거나 제거할 수 있습니다.

테스트와 빌드 단계

npm run test:content, npm run test:theme, npm run build는 순서대로 기록해야 합니다. 앞 명령이 실패하면 뒤 명령은 실행하지 않습니다. 보고서에는 실패한 정확한 명령과 핵심 오류를 붙입니다. 긴 로그 전체를 붙일 필요는 없지만, YAML 파싱 오류인지, 누락된 필수 섹션인지, Next.js 컴파일 오류인지 구분할 수 있는 첫 단서는 반드시 포함해야 합니다.

공개 검증 실패를 다루는 법

빌드가 성공해도 공개 사이트가 곧바로 새 글을 보여 준다고 가정하면 안 됩니다. Futory는 PM2 런타임 재시작과 no-cache 공개 확인을 통해 실제 반영 여부를 봅니다.

상세 페이지와 목록 페이지를 따로 본다

/posts/<slug>가 200을 반환하면 상세 라우트는 살아 있다는 뜻입니다. 그러나 /, /posts, /vibe-coding 목록에 오늘 날짜나 slug가 보이지 않으면 독자가 새 글을 찾기 어렵습니다. 따라서 공개 검증 실패 보고는 어느 표면이 실패했는지 나눠야 합니다. 상세은 성공, 목록은 실패처럼 나누어 쓰면 다음 조치가 캐시 문제인지 목록 생성 문제인지 좁혀집니다.

캐시를 의심하되 증거를 남긴다

검증 요청에는 cache-busting query와 Cache-Control: no-cache를 붙이는 편이 좋습니다. 그래도 새 글이 보이지 않으면 단순 브라우저 캐시가 아니라 런타임, 프록시, 빌드 산출물, 배포 경로 문제를 확인해야 합니다. 이때 보고서에 검증 URL과 HTTP 상태를 남기면 같은 조건으로 재현할 수 있습니다.

좋은 실패 보고서 템플릿

실무에서는 아래 항목만 있어도 충분합니다.

최소 항목

• 실행 조건: KST 날짜, 현재 시간, 선택 시간, weekday 여부
• 중복 방어: 오늘 날짜 frontmatter 또는 파일명 발견 여부
• 백업: 경로와 크기
• 생성 파일: 제목, slug, 절대 경로
• 검증 명령: 각 명령의 PASS 또는 FAIL
• 중단 정책: 실패 시 PM2 재시작을 실행하지 않았는지
• 공개 확인: 상세 URL과 목록 URL의 상태

문장보다 표식이 중요하다

보고서는 멋진 문장보다 빠른 판독성이 중요합니다. PASS build, FAIL public /posts, SKIP duplicate처럼 고정된 표식을 쓰면 모바일 알림에서도 핵심이 보입니다. 한국어 설명은 그 뒤에 짧게 붙이면 됩니다.

자주 묻는 질문

실패하면 새 Markdown 파일을 바로 지워야 하나요?

항상 그렇지는 않습니다. 콘텐츠 테스트에서 실패한 경우에는 파일을 열어 frontmatter나 본문 구조를 고치면 됩니다. 빌드 실패가 환경 문제라면 파일을 지우는 것보다 의존성이나 빌드 로그를 확인하는 편이 낫습니다. 다만 자동화가 기존 글을 수정하지 않았고 백업이 있다는 사실은 반드시 보고되어야 합니다.

PM2 재시작 실패와 공개 검증 실패는 같은 문제인가요?

다릅니다. PM2 재시작 실패는 새 빌드를 런타임에 반영하지 못했을 가능성이 큰 상태입니다. 공개 검증 실패는 재시작 이후에도 상세 페이지나 목록 페이지에서 새 글이 확인되지 않는 상태입니다. 보고서에서 두 단계를 분리해야 원인을 좁힐 수 있습니다.

성공 보고에도 실패 지도가 필요한가요?

필요합니다. 성공 보고에 각 단계의 PASS가 남아 있으면 다음 실패 때 비교 기준이 됩니다. 어제는 .next 산출물에 slug가 있었고 오늘은 없다면 빌드 입력을 보면 됩니다. 어제는 목록 세 곳이 모두 통과했는데 오늘은 /vibe-coding만 빠졌다면 카테고리나 목록 렌더링을 의심할 수 있습니다.

결론

AI 블로그 자동화에서 실패 보고서는 “무언가 잘못됐다”는 알림이 아니라 “여기까지는 안전했고, 여기서 멈췄으며, 다음에는 이것을 보라”는 복구 지도입니다. Futory의 Next.js Markdown 운영에서는 시간 게이트, 중복 검사, 백업, 단일 파일 생성, 테스트, 빌드, PM2 재시작, 공개 검증을 같은 순서로 보고하면 됩니다. 이 구조가 있으면 무인 발행도 예측 가능해지고, 실패가 나더라도 다음 조치가 짧아집니다.