AI와 함께 배포할 때 필요한 자동 검증 체크리스트

요약

AI와 함께 개발하면 글 작성, 코드 수정, 배포 스크립트 작성까지 빠르게 진행할 수 있습니다. 하지만 속도가 빨라질수록 배포 검증은 더 중요해집니다. 특히 Futory처럼 Next.js Markdown 블로그를 운영하면서 콘텐츠, 테마, 빌드, PM2 재시작, Nginx 공개 확인까지 이어지는 구조라면 “잘 된 것 같다”는 느낌만으로 배포를 끝내면 안 됩니다.

이 글은 Futory 운영 맥락에서 사용하는 배포 전후 자동 검증 체크리스트를 정리한 기록입니다. 핵심은 단순합니다. 새 글을 추가하더라도 기존 기능을 지키고, 빌드가 통과한 뒤에만 서비스를 재시작하며, 공개 URL에서 실제로 보이는지 확인하는 것입니다.

AI 개발에서 배포 검증이 더 중요해지는 이유

AI 코딩 에이전트는 많은 파일을 빠르게 수정할 수 있습니다. 이 장점은 동시에 위험이 되기도 합니다. 사람이 직접 한 줄씩 바꿀 때는 눈에 띄던 변경이, AI가 여러 파일을 한 번에 다루면 놓치기 쉽습니다. 예를 들어 블로그 글 하나를 추가하는 작업인데 레이아웃 파일이나 CSS 토큰이 함께 바뀌면 기존 다크/라이트 모드가 깨질 수 있습니다.

Futory의 경우 운영 주제가 “AI와 함께 만들고, 자동화하고, 운영하는 기록”이기 때문에 블로그 자체도 실험 대상입니다. 글을 자동으로 발행하는 흐름이 있다면 그 흐름 안에 검증도 같이 들어가야 합니다. 자동화가 글을 올리는 데서 끝나면 반쪽짜리입니다. 자동화는 실패를 감지하고, 실패했을 때 배포를 멈추는 역할까지 해야 합니다.

배포 전 체크리스트

1. 오늘 이미 발행된 글이 있는지 확인하기

자동 게시 작업에서 가장 먼저 확인할 것은 중복 발행입니다. Futory는 content/posts/*.md 파일의 frontmatter에 날짜를 기록합니다. 따라서 오늘 KST 날짜의 글이 이미 있으면 새 글을 만들지 않아야 합니다. 같은 날짜에 여러 글이 올라가면 콘텐츠 운영 리듬이 흐트러지고, 자동화가 제대로 통제되지 않는다는 신호가 됩니다.

이 확인은 단순하지만 중요합니다. cron이 여러 번 실행되거나 서버 시간이 예상과 다르게 동작하더라도 날짜 기반 중복 체크가 있으면 같은 날 같은 작업이 반복되는 사고를 막을 수 있습니다.

2. 기존 글과 겹치지 않는 주제 고르기

새 글을 만들기 전에는 기존 Markdown 파일의 제목과 주제를 읽어야 합니다. 이미 “PM2와 Nginx 배포”, “글감 백로그”, “자동화 로드맵” 같은 글이 있다면 다음 글은 그 흐름을 이어가되 같은 이야기를 반복하지 않는 방향이 좋습니다.

이번 글처럼 “배포 검증 체크리스트”를 다루면 기존 배포 글과 연결되면서도 초점이 다릅니다. 배포 방법 자체가 아니라 AI와 함께 운영할 때 무엇을 확인해야 하는지를 다룹니다. 이렇게 연재를 설계하면 바이브코딩이라는 하나의 카테리 안에서도 주제가 얇게 흩어지지 않고 깊어집니다.

3. 콘텐츠 형식 검증하기

Futory의 글은 frontmatter에 title, description, date, category, tags가 있어야 합니다. 카테고리는 현재 전략상 바이브코딩으로 유지합니다. 글 본문에는 ## 요약, 실제 운영 관점의 소제목, ## 자주 묻는 질문, ## 결론이 포함되어야 합니다.

이런 규칙은 검색 노출만을 위한 형식이 아닙니다. 글을 읽는 사람이 빠르게 핵심을 파악하고, 운영자가 나중에 콘텐츠를 관리하기 쉽게 만드는 장치입니다. AI가 초안을 작성하더라도 형식 검증 스크립트가 있으면 누락을 빠르게 잡아낼 수 있습니다.

기능 보존을 위한 테마 검증

Futory에는 다크/라이트 모드 토글이 있습니다. 이 기능은 단순한 UI 장식이 아니라 기존 사용자 경험의 일부입니다. 그래서 글 하나를 추가하는 배포라도 components/ThemeToggle.tsx, app/theme-init.tsx, CSS의 data-theme 변수, npm run test:theme 흐름이 유지되는지 확인해야 합니다.

운영에서 자주 생기는 실수는 “콘텐츠만 바꿨으니 UI는 괜찮겠지”라고 생각하는 것입니다. 하지만 전체 디렉터리를 동기화하거나 빌드 산출물을 정리하는 과정에서 파일이 사라질 수 있습니다. 특히 rsync --delete 같은 방식은 스테이징에 없는 파일을 라이브에서도 삭제할 수 있기 때문에, 배포 전에 스테이징이 최신 기능을 모두 포함하고 있는지 확인해야 합니다.

테마 검증은 작은 테스트처럼 보이지만 실제로는 운영 철학을 담고 있습니다. AI가 속도를 담당한다면 테스트는 기억을 담당합니다. 사람이 “이 기능은 지켜야 한다”고 한 번 정한 내용을 스크립트가 계속 확인해주는 구조가 필요합니다.

빌드와 서비스 재시작의 순서

Next.js 블로그에서는 빌드 성공이 배포의 기준점입니다. npm run test:content, npm run test:theme, npm run build가 모두 통과하기 전에는 PM2를 재시작하지 않는 편이 안전합니다. 실패한 빌드 상태에서 프로세스를 재시작하면 기존에 정상 동작하던 서비스까지 흔들릴 수 있습니다.

Futory의 운영 흐름에서는 스테이징에서 먼저 검증하고, 성공하면 호스트 라이브 경로인 /opt/wordblog에 동기화한 뒤 호스트에서도 다시 검증합니다. 컨테이너 안의 /opt/data/wordblog_next_staging과 호스트의 /root/hermes-agent/data/wordblog_next_staging가 같은 스테이징을 가리키더라도, 실제 서비스는 호스트의 /opt/wordblog에서 PM2로 실행됩니다. 따라서 “스테이징 빌드 성공”과 “라이브 서비스 반영 성공”은 구분해서 확인해야 합니다.

PM2 재시작 후에는 바로 실패로 판단하지 않고 잠시 재시도하는 확인이 필요합니다. Next.js 프로세스가 부팅되는 동안 첫 요청이 실패할 수 있기 때문입니다. 자동화는 이런 운영상의 작은 지연도 고려해야 안정적입니다.

공개 URL 확인까지가 배포다

배포가 끝났다는 말은 서버 안에서 빌드가 성공했다는 뜻만은 아닙니다. 공개 도메인에서 실제 글 URL이 HTTP 200으로 열리고, /posts 목록에서도 오늘 날짜와 새 글이 보여야 합니다. Futory의 공개 블로그는 https://futory.oig.kr이므로 최종 확인도 이 도메인 기준으로 해야 합니다.

이 단계는 Nginx 설정, PM2 프로세스, Next.js 라우팅, 정적 파일 생성, 캐시 문제를 한 번에 확인하는 현실적인 검증입니다. 내부 포트 127.0.0.1:8042가 정상이어도 공개 도메인에서 문제가 생길 수 있고, 반대로 공개 페이지가 캐시 때문에 늦게 바뀌어 보일 수도 있습니다. 그래서 자동화는 내부 확인과 공개 확인을 분리해서 기록하는 것이 좋습니다.

자주 묻는 질문

Q. 글 하나 추가하는데 왜 빌드까지 해야 하나요?

Markdown 글도 Next.js 앱의 빌드 과정에 영향을 줄 수 있습니다. frontmatter 형식이 틀리거나 날짜, 태그, 라우팅 처리에서 문제가 생기면 빌드 단계에서 발견될 수 있습니다. 운영 블로그라면 글 추가도 코드 변경처럼 검증하는 편이 안전합니다.

Q. AI가 쓴 글은 바로 게시해도 되나요?

바로 게시하기보다는 기존 글과의 중복, 블로그의 운영 맥락, 형식 규칙, 공개 페이지 표시 여부를 확인해야 합니다. AI는 초안을 빠르게 만들 수 있지만, 운영 기준을 지키는 일은 별도의 검증 흐름으로 보완해야 합니다.

Q. 배포 자동화에서 가장 먼저 만들 테스트는 무엇인가요?

콘텐츠 형식 검증과 기존 핵심 기능 보존 테스트가 우선입니다. Futory라면 test:content와 test:theme이 그 역할을 합니다. 이후 공개 URL 확인, 사이트맵 확인, 검색 등록 상태 확인 같은 단계로 확장할 수 있습니다.

결론

AI와 함께 개발하고 운영하는 블로그일수록 배포 검증은 선택이 아니라 기본입니다. Futory의 자동 게시 흐름은 단순히 글을 생성하는 작업이 아니라, 중복 확인, 콘텐츠 규칙 확인, 테마 기능 보존, Next.js 빌드, PM2 재시작, 공개 URL 검증까지 이어지는 운영 루프여야 합니다.

좋은 자동화는 빠르게 배포하는 도구가 아니라 안전하게 반복하는 시스템입니다. AI가 작업 속도를 높여줄수록, 우리는 검증 체크리스트를 더 명확하게 만들어야 합니다. 그래야 블로그는 매일 조금씩 쌓이면서도 기존 경험을 잃지 않고 안정적으로 성장할 수 있습니다.