AI 블로그 자동화에서 콘텐츠 계약 변경을 작게 검증하는 법

요약

Futory처럼 Next.js와 Markdown으로 운영되는 AI 블로그에서 콘텐츠 계약은 글을 보여 주기 위한 조용한 약속입니다. frontmatter의 title, description, date, category, tags가 어떤 형식인지, slug가 파일명에서 어떻게 만들어지는지, /posts와 /vibe-coding 목록이 어떤 값을 기준으로 글을 고르는지가 모두 계약에 해당합니다. 평소에는 잘 보이지 않지만, 이 계약이 조금만 흔들려도 새 글은 존재하는데 목록에는 빠지거나, 빌드는 성공했는데 공개 페이지의 설명이 비어 있는 문제가 생길 수 있습니다.

콘텐츠 계약 변경은 기능 개발처럼 크게 다루기보다 작은 운영 단위로 나누어 검증하는 편이 안전합니다. 특히 무인 크론이 매일 새 Markdown을 만드는 구조에서는 “오늘 글 하나를 추가한다”는 흐름을 유지하면서 계약 변경의 영향 범위를 확인해야 합니다. 이 글은 Futory의 바이브코딩 발행 루틴에서 콘텐츠 계약을 바꿀 때 어떤 순서로 점검하고, 어떤 증거를 남기면 좋은지 정리합니다.

콘텐츠 계약이란 무엇인가

콘텐츠 계약은 글 작성자, 자동화 스크립트, Next.js 빌드, 공개 화면이 같은 데이터를 같은 뜻으로 해석하겠다는 약속입니다. 예를 들어 category: "바이브코딩"은 사람이 보기에는 단순한 분류지만, 시스템 입장에서는 /vibe-coding 목록에 글을 포함할지 판단하는 필터입니다. date: "YYYY-MM-DD"는 발행일 표시인 동시에 중복 방지와 최신 정렬의 기준입니다.

frontmatter는 데이터베이스 스키마처럼 다룬다

Markdown 블로그에는 별도 CMS 데이터베이스가 없더라도 frontmatter가 사실상 작은 스키마 역할을 합니다. 필드 이름을 바꾸거나 날짜 형식을 바꾸는 일은 데이터베이스 컬럼을 바꾸는 것과 비슷합니다. 그래서 새 필드를 추가하거나 기존 필드를 더 엄격하게 검사하려면 기존 글 전체가 그 계약을 만족하는지 먼저 확인해야 합니다. 한두 개의 최신 글만 보고 판단하면 오래된 글에서 빌드 오류가 날 수 있습니다.

목록 페이지는 계약의 공개 테스트다

콘텐츠 계약이 실제로 지켜졌는지는 공개 목록에서 잘 드러납니다. 상세 페이지는 slug만 맞으면 열릴 수 있지만, 카테고리 목록은 category, 날짜 정렬은 date, 카드 설명은 description에 의존합니다. 따라서 계약 변경 후에는 상세 URL 200뿐 아니라 홈, 전체 글 목록, 바이브코딩 목록까지 확인해야 합니다. 목록에 새 글이 보이면 데이터 계약과 렌더링 계약이 함께 통과한 것입니다.

변경을 작게 나누는 방법

가장 위험한 방식은 새 글 작성, 콘텐츠 스키마 변경, 디자인 변경, 배포 설정 변경을 한 번에 섞는 것입니다. 실패했을 때 어느 변경이 원인인지 알기 어렵기 때문입니다. Futory의 정기 발행 루틴에서는 기존 글을 수정하지 않고 오늘의 Markdown 하나만 추가하는 것이 기본입니다. 계약 변경이 필요하다면 별도 작업으로 분리하고, 정기 발행에서는 그 계약을 따르는 새 글이 정상적으로 통과하는지만 확인하는 편이 좋습니다.

먼저 읽고, 그다음 바꾼다

계약 변경 전에는 최근 글의 제목, description, 태그, 날짜 형식을 읽어야 합니다. 최근 글들은 현재 자동화가 실제로 만들어 온 패턴을 보여 줍니다. 예를 들어 태그가 모두 한국어와 영어 기술어를 함께 쓰고 있다면 새 계약도 이 흐름을 고려해야 합니다. 이 사전 점검은 중복 주제 회피뿐 아니라 콘텐츠 형식의 일관성을 지키는 데 도움이 됩니다.

하나의 신호만 추가한다

새로운 운영 신호가 필요하다면 한 번에 하나만 추가하는 것이 좋습니다. 예를 들어 글 카드에 읽는 시간을 표시하고 싶다면 먼저 Markdown에서 계산 가능한지 확인하고, 그다음 목록 렌더링에 반영하고, 마지막으로 공개 HTML에서 값이 보이는지 확인합니다. 태그 구조, 카테고리 경로, 날짜 표시를 동시에 바꾸면 테스트가 실패했을 때 원인을 좁히기 어렵습니다.

Futory 발행 루틴에 적용하기

정기 발행에서는 계약 변경을 직접 수행하지 않더라도, 새 글이 현재 계약을 만족한다는 증거를 매번 남길 수 있습니다. frontmatter가 필수 필드를 모두 갖추었는지, 본문에 ## 요약, ## 자주 묻는 질문, ## 결론이 있는지, 카테고리가 바이브코딩인지, 빌드 산출물에 slug가 포함되는지 확인하면 됩니다. 이 증거들은 나중에 계약을 바꿀 때도 기준선으로 쓰입니다.

테스트 명령을 계약 문서처럼 읽는다

npm run test:content는 글의 형식 계약을 확인하는 단계이고, npm run test:theme은 화면 구성이나 테마 쪽 계약을 확인하는 단계입니다. npm run build는 두 계약이 실제 Next.js 산출물로 이어지는지 확인합니다. 세 명령을 순서대로 통과시키면 “파일은 맞지만 화면은 깨진” 상태를 줄일 수 있습니다. 실패하면 다음 단계로 넘어가지 말고 정확한 명령과 첫 오류를 남겨야 합니다.

공개 검증은 캐시를 의심하며 진행한다

빌드와 PM2 재시작이 성공해도 공개 사이트가 즉시 같은 내용을 보여 주지 않을 수 있습니다. 그래서 검증 요청에는 cache-busting 쿼리와 Cache-Control: no-cache를 붙이는 것이 좋습니다. 상세 URL은 200을 확인하고, /, /posts, /vibe-coding은 오늘 날짜나 slug가 포함되는지 봅니다. 이 방식은 계약 변경 문제가 아니라 캐시나 런타임 반영 문제인지 구분하는 데도 유용합니다.

자주 묻는 질문

콘텐츠 계약을 바꿀 때 기존 글도 함께 수정해야 하나요?

필요할 수 있지만 정기 발행 루틴과 섞지 않는 편이 안전합니다. 오늘의 자동 발행은 새 Markdown 파일 하나를 추가하는 작업이고, 기존 글 일괄 수정은 별도 백업과 검토가 필요한 마이그레이션입니다. 두 작업을 분리하면 실패 원인을 훨씬 쉽게 찾을 수 있습니다.

frontmatter 필드 하나를 추가하는 것도 위험한가요?

필드 추가 자체는 작아 보이지만 목록 렌더링, 검색 색인, 타입 검사와 연결되면 영향이 커질 수 있습니다. 새 필드를 선택 사항으로 시작하고, 기존 글 전체가 안전하게 처리되는지 확인한 뒤 필수 계약으로 올리는 방식이 좋습니다.

공개 목록에 글이 없으면 계약 변경 때문인가요?

항상 그렇지는 않습니다. 먼저 새 slug가 .next 산출물에 있는지, PM2 재시작이 성공했는지, no-cache 요청에서도 같은 결과인지 확인해야 합니다. 산출물에는 있는데 목록에 없다면 카테고리나 정렬 계약을 의심하고, 산출물에도 없다면 Markdown 수집 단계부터 다시 봐야 합니다.

결론

AI 블로그 자동화에서 콘텐츠 계약은 빠른 발행을 가능하게 하는 보이지 않는 기반입니다. Futory의 Next.js Markdown 루틴은 frontmatter, slug, 카테고리, 목록 페이지, 빌드 산출물이 같은 약속을 공유할 때 안정적으로 작동합니다. 계약을 바꿀 때는 한 번에 많은 것을 고치기보다 작은 신호 하나를 추가하고, 테스트와 공개 검증으로 영향 범위를 확인하는 방식이 안전합니다.

바이브코딩은 빠르게 만들고 바로 배포하는 흐름이지만, 빠른 흐름일수록 계약을 더 명확하게 다뤄야 합니다. 오늘의 새 글이 필수 frontmatter를 갖추고, 본문 구조를 지키고, 빌드 산출물과 공개 목록에 나타난다면 자동화는 단순한 파일 생성이 아니라 운영 가능한 콘텐츠 계약을 지킨 것입니다. 이 기준을 유지하면 Futory의 평일 발행은 변화가 있어도 예측 가능한 리듬을 잃지 않습니다.