AI 블로그 자동화에서 공개 경로 계약을 고정하는 법

요약

Futory처럼 AI가 매일 Markdown 글을 만들고 Next.js 빌드와 PM2 재시작을 거쳐 공개하는 블로그에서는 글의 내용만큼 “어떤 경로로 공개될 것인가”를 먼저 고정하는 일이 중요합니다. 파일명은 content/posts 안의 원천이고, slug는 상세 페이지의 주소이며, 홈과 목록 페이지는 독자가 새 글을 발견하는 경로입니다. 이 값들이 느슨하게 흩어져 있으면 빌드가 성공해도 운영자는 어떤 URL을 확인해야 하는지 매번 다시 추측하게 됩니다.

공개 경로 계약은 오늘 글의 slug, Markdown 파일 경로, 상세 URL, 카테고리 목록 URL, 홈 노출 기대값을 작성 전에 한 번 묶는 작은 약속입니다. 바이브코딩은 빠른 실행을 장점으로 하지만, 반복 발행에서는 빠르게 만든 결과가 같은 경로로 끝까지 이어져야 합니다. 이 글은 Futory의 Next.js Markdown 운영에서 공개 경로 계약을 어떻게 잡고, 어떤 순서로 검증하면 좋은지 정리합니다.

공개 경로 계약이 필요한 이유

자동 발행은 여러 도구가 이어 달리는 작업입니다. AI는 글을 만들고, 파일 시스템은 Markdown을 저장하며, 콘텐츠 테스트는 frontmatter를 읽고, Next.js는 정적 또는 서버 산출물로 묶고, PM2는 새 빌드를 서비스합니다. 마지막으로 공개 사이트는 상세 페이지와 목록 페이지로 독자에게 보여 줍니다. 이 단계들이 모두 같은 글을 가리키려면 공통 기준이 필요합니다.

slug는 운영의 주소표다

제목은 사람이 읽기 좋지만 수정될 수 있습니다. 반면 slug는 파일명, 공개 URL, 빌드 산출물 검색, 목록 검증을 연결하는 주소표입니다. 예를 들어 이번 글의 slug가 ai-blog-route-contract-routine이라면 파일은 /opt/futory/content/posts/ai-blog-route-contract-routine.md이고 공개 상세 주소는 /posts/ai-blog-route-contract-routine입니다. 같은 문자열을 기준으로 테스트와 검증을 진행하면 각 단계가 서로 다른 글을 보고 있는지 의심할 필요가 줄어듭니다.

목록 경로도 계약에 포함해야 한다

상세 페이지가 열리는 것만으로 발행이 끝났다고 보기에는 부족합니다. 독자는 홈, /posts, /vibe-coding 같은 목록에서 새 글을 발견합니다. 따라서 공개 경로 계약에는 상세 URL뿐 아니라 어떤 목록에서 오늘 날짜나 slug가 보여야 하는지도 포함해야 합니다. 이 기대값이 있어야 공개 검증 보고가 “200 확인”에서 끝나지 않고 “독자가 찾을 수 있는 상태”까지 확장됩니다.

Futory에서 계약으로 고정할 값

Futory의 반복 발행에서는 계약을 길게 만들 필요가 없습니다. 다만 자동화가 검색하고 사람이 재현할 수 있는 값이어야 합니다. 날짜, slug, 파일 경로, 상세 URL, 목록 URL, 검증 명령을 같은 순서로 남기면 충분합니다.

작성 전에는 경로를 먼저 정한다

새 글을 쓰기 전에 KST 기준 오늘 날짜가 이미 frontmatter나 파일명에 있는지 확인합니다. 중복이 없을 때만 새 slug를 정하고, 그 slug가 최근 글의 주제와 너무 겹치지 않는지 봅니다. 이 단계에서 파일 경로와 공개 URL을 미리 확정하면 본문 작성 이후에 경로를 다시 만들거나 바꾸는 실수를 줄일 수 있습니다. 특히 자동화가 여러 번 재시도될 수 있는 날에는 처음 정한 slug가 모든 판단의 기준이 됩니다.

작성 후에는 경로가 살아 있는지 본다

Markdown 파일을 만든 뒤에는 npm run test:content, npm run test:theme, npm run build를 차례로 실행합니다. 세 명령이 통과하면 .next 안에서 slug가 실제로 포함됐는지 확인합니다. 이 확인은 빌드 성공을 공개 경로 계약과 연결하는 과정입니다. 빌드가 성공했지만 slug가 산출물에서 보이지 않는다면 글이 빌드 입력에 제대로 연결되지 않았을 가능성을 의심해야 합니다.

공개 검증을 단계별로 나누기

PM2 재시작 이후에는 공개 사이트를 확인합니다. 이때 cache-busting query string과 Cache-Control: no-cache 헤더를 붙여 오래된 응답을 보는 위험을 줄입니다. 상세 페이지, 홈, 전체 글 목록, 카테고리 목록을 나누어 확인하면 문제가 발생했을 때 원인을 더 좁게 볼 수 있습니다.

상세 페이지 확인

상세 페이지 /posts/<slug>가 200을 반환하면 직접 링크 접근은 가능한 상태입니다. 이 단계는 공개 경로 계약의 핵심입니다. 파일명으로 정한 slug가 실제 라우팅 주소가 되었는지 확인하는 것이기 때문입니다. 상세 URL이 실패하면 목록을 보기 전에 빌드 산출물, 라우팅 규칙, PM2 재시작 상태를 먼저 점검해야 합니다.

목록 페이지 확인

홈, /posts, /vibe-coding에서는 slug 또는 오늘 날짜가 포함되는지 봅니다. 목록 페이지는 캐시와 정렬 정책의 영향을 받을 수 있으므로 상세 페이지와 분리해서 기록해야 합니다. 상세는 성공했지만 목록이 실패했다면 새 글을 다시 만들지 말고 목록 생성 규칙, 런타임 캐시, 배포 반영 시간을 확인하는 편이 안전합니다.

자주 묻는 질문

공개 경로 계약을 별도 문서로 저장해야 하나요?

반드시 별도 문서가 필요한 것은 아닙니다. 크론 실행 보고서에 date, slug, 파일 경로, 상세 URL, 목록 검증 결과가 같은 순서로 남아 있으면 충분합니다. 중요한 것은 매일 같은 형식으로 반복되어 다음 실행이 이어받을 수 있는 상태를 만드는 것입니다.

제목을 바꾸면 slug도 바꿔야 하나요?

대부분은 바꾸지 않는 편이 좋습니다. 제목은 독자에게 더 자연스럽게 다듬을 수 있지만, slug는 검증과 링크의 기준입니다. 발행 직전에 slug를 바꾸면 파일 경로, 공개 URL, 빌드 산출물 검색, 운영 보고가 모두 흔들릴 수 있습니다. 꼭 바꿔야 한다면 작성 전에 바꾸고 이후 단계에서는 고정해야 합니다.

상세 URL은 200인데 목록에 보이지 않으면 실패인가요?

완전한 성공으로 보기는 어렵지만, 새 글을 또 만들 상황은 아닙니다. 이미 오늘 날짜 파일과 상세 URL이 있다면 그 글이 기준입니다. 목록만 보이지 않는 경우에는 캐시, 목록 생성 규칙, 재시작 반영 여부를 확인하고 같은 slug로 후속 검증을 이어 가야 합니다.

결론

AI 블로그 자동화에서 공개 경로 계약은 빠른 발행을 안전하게 만드는 작은 운영 장치입니다. Futory의 Next.js Markdown 흐름에서는 slug, 파일 경로, 상세 URL, 목록 URL을 작성 전에 고정하고, 테스트와 빌드와 공개 검증을 같은 slug로 확인할 때 중복과 혼선이 줄어듭니다.

바이브코딩은 실행을 통해 결과를 만드는 방식이지만, 반복 운영에서는 실행의 목적지가 분명해야 합니다. 오늘 글이 어떤 파일에서 시작해 어떤 공개 주소로 끝나는지 매일 같은 방식으로 확인하면 자동화는 더 조용해지고, 실패한 날에도 다음 조치가 훨씬 명확해집니다.