AI 블로그 자동화에서 frontmatter 계약을 지키는 법

요약

Futory처럼 평일마다 AI가 Markdown 파일을 만들고 Next.js 빌드와 PM2 재시작까지 이어 가는 블로그에서는 본문 품질만큼 frontmatter 품질이 중요합니다. 제목이 좋아도 date, category, tags, description이 사이트가 기대하는 형식과 어긋나면 글은 상세 URL에서는 보이지만 목록에서 빠지거나, 날짜 정렬이 흔들리거나, 나중에 중복 방지 로직이 오늘 글을 찾지 못할 수 있습니다. 그래서 frontmatter는 장식이 아니라 발행 자동화와 공개 사이트 사이의 계약으로 다뤄야 합니다.

오늘의 핵심은 “작게 고정하고 매번 확인한다”입니다. 새 글을 만들기 전에는 오늘 KST 날짜가 이미 있는지 확인하고, 새 파일을 만든 뒤에는 frontmatter가 정해진 모양을 따르는지 테스트로 검증합니다. 그다음 빌드 산출물과 공개 목록에서 날짜 또는 slug가 실제로 노출되는지 확인해야 합니다. 바이브코딩은 빠르게 만들고 배포하는 태도지만, 반복 발행에서는 빠른 실행을 지탱하는 작은 계약이 있어야 운영이 흔들리지 않습니다.

frontmatter를 계약으로 봐야 하는 이유

Markdown 블로그의 장점은 파일 하나로 글을 관리할 수 있다는 점입니다. 하지만 파일 하나 안에는 사람이 읽는 본문과 프로그램이 읽는 메타데이터가 함께 들어 있습니다. Next.js 콘텐츠 로더는 frontmatter를 읽어 목록, 카테고리, 정렬, SEO 설명, 태그 페이지를 구성합니다. 이 값이 틀리면 본문이 아무리 정상이어도 사이트의 여러 경로에서 예상과 다른 결과가 나옵니다.

사람에게는 제목, 시스템에게는 신호다

제목과 설명은 독자에게 글의 방향을 알려 주지만, 자동화에는 더 직접적인 신호가 됩니다. 발행 보고서의 제목, 목록 카드의 설명, 검색 엔진 미리보기, 내부 링크 후보가 모두 이 값에 기대어 움직입니다. 특히 date: "YYYY-MM-DD"는 하루 한 편 원칙을 지키는 중복 방지 기준입니다. 오늘 날짜가 정확히 들어 있지 않으면 다음 실행이 같은 날짜 글이 없다고 판단할 수 있습니다.

카테고리는 공개 탐색 경로와 연결된다

Futory의 반복 글은 category: "바이브코딩"을 사용합니다. 이 문자열이 조금만 달라져도 /vibe-coding 목록에서 빠질 수 있습니다. 자동화가 상세 URL 200만 보고 성공이라고 판단하면 카테고리 누락을 놓치기 쉽습니다. 그래서 frontmatter 계약은 로컬 테스트뿐 아니라 공개 홈, 전체 글 목록, 카테고리 목록 검증까지 이어져야 합니다.

Futory에서 지켜야 할 최소 계약

계약은 복잡할 필요가 없습니다. 매일 발행 루틴에서 반드시 필요한 필드를 안정적으로 유지하는 것이 먼저입니다.

1. 날짜는 KST 기준으로 고정한다

cron은 UTC 시간에 실행되더라도 발행 판단은 Asia/Seoul 기준이어야 합니다. 파일의 date도 같은 KST 날짜를 사용해야 합니다. 이렇게 해야 “오늘 이미 발행했는가”라는 질문에 파일 시스템과 공개 사이트가 같은 답을 하게 됩니다. 날짜가 UTC 기준으로 밀리면 금요일 저녁이나 월요일 오후 같은 경계에서 중복 또는 누락이 생길 수 있습니다.

2. slug와 파일명은 영어 kebab-case로 만든다

파일명은 공개 URL의 일부가 됩니다. ai-blog-frontmatter-contract-routine.md처럼 주제와 운영 단위를 드러내는 영어 kebab-case를 쓰면 로그, 빌드 산출물 검색, 공개 검증이 쉬워집니다. 한글 제목은 독자에게 자연스럽게 쓰고, slug는 운영자가 추적하기 쉬운 안정적인 식별자로 두는 방식입니다.

3. 태그는 기본 축과 오늘의 초점을 함께 담는다

바이브코딩, Next.js, Markdown, 블로그자동화는 Futory 운영 글의 기본 축입니다. 여기에 오늘 글의 구체 초점인 frontmatter, 콘텐츠운영 같은 태그를 더하면 최근 글과의 차이가 선명해집니다. 매일 같은 태그만 반복하면 검색과 회고에서 글을 구분하기 어려우므로, 최소 하나는 오늘의 실무 포인트를 반영하는 것이 좋습니다.

발행 루틴에 넣을 점검 순서

frontmatter 계약은 파일을 쓰는 순간에만 확인하면 부족합니다. 새 글이 공개 경로 전체에 반영되는지 끝까지 확인해야 계약이 실제로 지켜진 것입니다.

발행 전에는 기존 날짜를 먼저 찾는다

가장 먼저 할 일은 오늘 날짜가 들어간 frontmatter나 파일명이 이미 있는지 확인하는 것입니다. 이 검사는 중복 발행을 막는 마지막 방어선입니다. 오늘 날짜 글이 있다면 새 글을 만들지 말고 기존 파일과 제목을 보고해야 합니다. 새 글을 만들 수 있는 조건은 “선택된 KST 시간이고, 평일이고, 오늘 날짜 글이 없다”가 모두 참일 때뿐입니다.

발행 후에는 테스트와 빌드가 계약을 재확인한다

파일을 만든 뒤에는 npm run test:content, npm run test:theme, npm run build를 순서대로 실행합니다. 콘텐츠 테스트는 frontmatter와 본문 구조를, 테마 테스트는 사이트 규칙을, 빌드는 실제 Next.js 산출물 생성을 확인합니다. 하나라도 실패하면 PM2를 재시작하지 않는 것이 원칙입니다. 실패한 계약을 공개 런타임에 반영하면 문제 범위가 커집니다.

공개 검증은 목록까지 포함한다

재시작 후 상세 URL만 확인하는 것은 절반의 검증입니다. 홈, /posts, /vibe-coding에서 오늘 날짜나 slug가 보이는지 확인해야 합니다. 이 단계는 frontmatter의 date와 category가 공개 탐색 경로에서 실제로 동작하는지 보여 줍니다. 캐시 우회 쿼리와 Cache-Control: no-cache 헤더를 함께 사용하면 관측 결과의 신뢰도도 올라갑니다.

자주 묻는 질문

frontmatter 오류는 빌드에서 항상 잡히나요?

항상 그렇지는 않습니다. 어떤 오류는 빌드 실패로 드러나지만, 어떤 오류는 빌드는 통과하고 목록 노출만 틀어지는 형태로 나타납니다. 그래서 콘텐츠 테스트, 빌드, 공개 목록 확인을 모두 해야 합니다. 특히 카테고리 문자열이나 날짜 정렬 문제는 공개 페이지를 읽어야 더 분명하게 확인됩니다.

이미 상세 URL이 열리면 성공으로 봐도 되나요?

상세 URL 200은 중요한 증거지만 충분하지 않습니다. 독자는 대부분 홈이나 글 목록, 카테고리 페이지를 통해 새 글을 발견합니다. 상세는 열리는데 목록에 없으면 발행은 기술적으로 일부 성공했지만 운영적으로는 미완료입니다. Futory의 자동 발행 보고에는 네 경로의 확인 결과가 함께 있어야 합니다.

계약을 엄격하게 하면 바이브코딩 속도가 느려지지 않나요?

오히려 반대입니다. 매번 같은 형식의 frontmatter와 검증 순서를 유지하면 실패했을 때 원인을 빨리 좁힐 수 있습니다. 자유롭게 바꿔도 되는 것은 본문의 관점과 예시이고, 고정해야 하는 것은 날짜, 카테고리, slug, 테스트 순서입니다. 작은 고정점이 있어야 빠른 실험도 안전하게 반복됩니다.

결론

AI 블로그 자동화에서 frontmatter는 Markdown 파일 상단의 보조 정보가 아니라 발행 시스템과 공개 사이트가 공유하는 작은 계약입니다. Futory의 평일 발행 루틴은 KST 날짜 확인, 최근 글 점검, 백업, 새 파일 작성, 콘텐츠 테스트, 테마 테스트, 빌드, .next slug 확인, PM2 재시작, 공개 상세와 목록 검증으로 이어질 때 안정적입니다.

바이브코딩은 빠르게 만들고 빠르게 검증하는 문화입니다. 그 속도를 오래 유지하려면 매일 반복되는 값은 더 정확하게 고정해야 합니다. frontmatter 계약을 지키면 중복 발행을 막고, 목록 누락을 줄이며, 나중에 운영 로그를 읽을 때도 어떤 글이 언제 어떤 경로로 공개되었는지 쉽게 추적할 수 있습니다. 그렇게 Futory의 자동 발행은 단순한 글 생성이 아니라 검증 가능한 콘텐츠 운영 루틴으로 남습니다.