Next.js Markdown 자동화에서 파일 계약을 고정하는 법

요약

AI 블로그 자동화에서 가장 먼저 안정화해야 할 대상은 거창한 배포 파이프라인이 아니라 새 글 파일 하나의 계약입니다. Futory처럼 content/posts/*.md에 Markdown 파일을 추가하고 Next.js가 이를 읽어 공개 페이지를 만드는 구조에서는 파일명, frontmatter, 본문 섹션, 태그, 날짜가 모두 운영 신호가 됩니다. 이 값들이 매번 흔들리면 콘텐츠 검증은 복잡해지고, 목록 페이지 반영 여부도 추적하기 어려워집니다.

파일 계약이란 “오늘 발행되는 글은 어떤 모양이어야 하는가”를 사람과 AI가 함께 지키는 약속입니다. 영어 kebab-case slug를 사용하고, 날짜는 Asia/Seoul 기준으로 고정하며, 카테고리와 태그 배열을 일정한 형식으로 두고, 본문에는 ## 요약, 여러 개의 H2/H3 섹션, ## 자주 묻는 질문, ## 결론을 포함합니다. 이 규칙은 창작을 답답하게 만드는 제한이 아니라, 매일 반복되는 발행을 안전하게 만드는 운영 인터페이스입니다.

왜 파일 계약이 중요한가

바이브코딩은 빠르게 만들고 바로 확인하는 방식에 강합니다. 하지만 블로그 자동화는 매일 같은 시간대에 실행되고, 사람이 실시간으로 지켜보지 않는다는 차이가 있습니다. 크론이 새 글을 만들 때마다 파일 구조가 달라지면 실패 원인을 좁히기 어렵습니다. 어느 날은 date가 빠지고, 어느 날은 태그가 문자열로 들어가고, 어느 날은 slug가 한글이나 공백을 포함하면 검증과 빌드가 불안정해집니다.

자동화가 읽을 수 있는 형식이 필요하다

사람은 약간 어긋난 문서를 보고도 의도를 이해할 수 있지만, 자동화는 정해진 신호를 기준으로 움직입니다. 오늘 날짜가 frontmatter에 있는지, 파일명이 중복되지 않는지, 카테고리 목록이 새 글을 포함하는지는 모두 규칙적인 형식이 있어야 안정적으로 확인할 수 있습니다. Futory의 발행 루틴에서 오늘 날짜 글이 이미 있으면 스킵하는 이유도 여기에 있습니다. 날짜가 일정한 위치와 형식으로 남아 있어야 중복 방지가 정확히 작동합니다.

작은 파일 하나가 배포 전체를 대표한다

Next.js Markdown 블로그에서는 새 파일 하나가 곧 새 URL 하나가 됩니다. 파일이 잘못되면 콘텐츠 테스트가 실패할 수 있고, 빌드가 실패할 수 있으며, 빌드는 성공했지만 목록에 표시되지 않을 수도 있습니다. 그래서 파일 계약은 단순한 작성 규칙이 아니라 배포 가능성의 첫 관문입니다. 새 글 파일이 계약을 지키면 이후 단계의 오류 범위가 크게 줄어듭니다.

Futory식 파일 계약 구성

Futory의 일일 글은 운영자가 나중에 보고 이해할 수 있어야 하고, 동시에 자동화가 검증하기 쉬워야 합니다. 이를 위해 파일 계약을 frontmatter, slug, 본문 구조, 검증 증거 네 부분으로 나눌 수 있습니다.

frontmatter는 검색 가능한 운영 메타데이터다

title, description, date, category, tags는 독자에게 보이는 정보이면서 운영자가 발행 상태를 확인하는 메타데이터입니다. 특히 date: "YYYY-MM-DD"는 중복 방지와 목록 정렬의 기준이 됩니다. category: "바이브코딩"은 Futory의 주제 흐름을 유지하고, 태그 배열은 글이 어떤 운영 관점에 속하는지 알려 줍니다. 태그는 너무 넓게 잡기보다 Next.js, Markdown, 블로그자동화, 운영루틴처럼 실제 검색과 분류에 도움이 되는 단어로 고정하는 편이 좋습니다.

slug는 배포 검증의 손잡이다

파일명은 영어 kebab-case로 만드는 것이 안전합니다. 예를 들어 nextjs-markdown-automation-file-contract.md처럼 의미가 분명한 slug를 사용하면 공개 URL /posts/nextjs-markdown-automation-file-contract를 바로 예측할 수 있습니다. 빌드 후 .next 산출물에서 slug를 찾는 것도 쉬워집니다. 운영 보고서에 파일 경로와 공개 URL을 함께 적을 수 있으므로, 나중에 문제가 생겼을 때 어느 파일이 어느 페이지로 이어졌는지 추적하기 쉽습니다.

작성 자유도와 운영 안정성의 균형

파일 계약은 모든 글을 똑같이 만들자는 뜻이 아닙니다. 주제, 사례, 문장 리듬은 매일 달라질 수 있습니다. 다만 자동화가 반드시 의존하는 뼈대는 고정해야 합니다. 이 균형을 잡으면 AI는 자유롭게 내용을 작성하면서도, 운영 시스템은 예측 가능한 입력을 받게 됩니다.

본문 구조는 독자 경험도 돕는다

## 요약으로 시작하면 독자는 글의 핵심을 빠르게 파악할 수 있습니다. 중간에는 H2와 H3를 섞어 개념과 실무 절차를 나누고, ## 자주 묻는 질문에서는 운영자가 실제로 궁금해할 질문을 정리합니다. 마지막 ## 결론은 오늘 글이 Futory 운영에 어떤 의미가 있는지 닫아 줍니다. 이 구조는 검증을 위한 형식이면서, 반복해서 읽는 독자에게도 익숙한 리듬을 제공합니다.

실패했을 때 복구 기준이 선명해진다

파일 계약이 고정되어 있으면 실패 보고서도 선명해집니다. 콘텐츠 검증 실패라면 frontmatter나 필수 섹션을 먼저 보면 됩니다. 빌드 실패라면 새 파일의 Markdown 문법이나 import 경로를 의심할 수 있습니다. 공개 상세 페이지는 200인데 목록에 없으면 프로세스 재시작, 캐시, 목록 생성 로직을 확인하면 됩니다. 규칙이 없을 때는 모든 것이 의심 대상이지만, 규칙이 있을 때는 의심 범위가 작아집니다.

운영 루틴에 파일 계약을 넣는 방법

실제 자동화에서는 파일 계약을 글 작성 프롬프트에만 적어 두는 것으로 끝내면 안 됩니다. 생성 전에는 기존 글을 확인해 주제와 날짜 중복을 피하고, 생성 직전에는 content/posts를 백업해야 합니다. 생성 후에는 npm run test:content, npm run test:theme, npm run build를 순서대로 실행하고, .next 산출물에 slug가 있는지 확인해야 합니다. 이후 PM2 재시작과 공개 URL 검증까지 이어져야 파일 계약이 실제 발행 계약으로 완성됩니다.

보고서에는 계약 이행 증거를 남긴다

성공 보고서에는 제목, 날짜, 파일 경로, 공개 URL, 선택된 시간, 백업 경로, 테스트 통과 여부, 빌드 통과 여부, PM2 재시작, 공개 상세와 목록 검증 결과를 남기는 것이 좋습니다. 이 항목들은 장식이 아니라 다음 운영 판단의 근거입니다. 특히 매시간 크론이 실행되는 구조에서는 스킵과 성공과 실패를 구분하는 짧은 증거가 자동화 신뢰도를 결정합니다.

자주 묻는 질문

파일 계약이 글의 개성을 줄이지 않나요?

핵심 구조를 고정한다고 해서 글의 개성이 사라지는 것은 아닙니다. 계약은 날짜, slug, frontmatter, 필수 섹션처럼 운영에 필요한 뼈대를 정하는 것입니다. 실제 사례, 설명 방식, 비유, 체크리스트 구성은 충분히 달라질 수 있습니다. 오히려 형식이 안정되면 AI와 운영자는 내용 자체에 더 집중할 수 있습니다.

이미 빌드가 성공하면 .next에서 slug를 또 확인해야 하나요?

확인하는 편이 안전합니다. 빌드 성공은 애플리케이션이 컴파일됐다는 뜻이지만, 새 글이 실제 산출물에 반영됐는지까지 항상 명확히 말해 주지는 않습니다. slug 검색은 파일 생성과 빌드 결과를 연결하는 간단한 증거입니다. 특히 배포 경로와 실행 경로가 헷갈릴 수 있는 환경에서는 작은 확인 하나가 큰 시간을 아껴 줍니다.

오늘 글 파일이 만들어졌지만 공개 검증이 실패하면 어떻게 해야 하나요?

새 글을 또 만들면 안 됩니다. 오늘 날짜 글이 이미 있으므로 중복 방지 규칙에 따라 같은 날 재실행은 스킵해야 합니다. 대신 기존 파일, 빌드 로그, PM2 재시작 결과, 공개 페이지 응답을 기준으로 어디에서 반영이 끊겼는지 확인해야 합니다. 파일 계약은 중복 생성을 막고 원인 분석을 좁히는 기준이 됩니다.

결론

Futory의 Next.js Markdown 자동화에서 파일 계약은 매일 한 편을 안전하게 발행하기 위한 가장 작은 운영 단위입니다. frontmatter, slug, 본문 구조, 검증 흐름을 고정하면 AI가 만든 글도 사람이 운영하는 콘텐츠 시스템 안에서 예측 가능하게 움직입니다.

바이브코딩은 빠른 실행을 가능하게 하지만, 반복 운영에는 빠름을 지탱하는 약속이 필요합니다. 새 Markdown 파일 하나가 계약을 지키고, 검증과 빌드와 공개 확인이 그 계약을 증명하면 자동화는 조용하면서도 신뢰할 수 있는 발행 시스템이 됩니다.