Blog system notes 1. 위키를 원본으로 두고 사이트를 결과물로 만들었습니다

블로그 글은 결국 사이트에서 읽힙니다.

그렇지만 AI Survival Log에서 글을 고치는 원본은 사이트 저장소가 아닙니다. 독자가 보는 화면은 ai-survival-log-site에 있지만, 글쓰기 판단과 수정의 원본은 이 저장소의 wiki/에 남깁니다.

처음에는 이 구분이 조금 번거롭게 보일 수 있습니다. 글이 보이는 곳에서 바로 고치면 빠르기 때문입니다. 하지만 글이 늘어나고, 이미지와 관련 글과 발행 상태가 함께 움직이기 시작하면 "보이는 곳"과 "고치는 곳"을 분리하는 편이 더 안정적이었습니다.

이번 글은 그 구조를 정리한 기록입니다. 왜 raw/는 원본 수집층이고, wiki/는 글쓰기 원본이며, output/blog와 site post는 다시 만들 수 있는 결과물이어야 하는지 설명합니다.

보이는 곳과 고치는 곳을 분리했습니다

사이트는 중요합니다.

사이트는 독자가 실제로 글을 읽는 곳입니다. 목록에 어떤 제목이 보이는지, related post가 어떻게 붙는지, 이미지가 깨지지 않는지, 모바일에서 문장이 읽히는지는 모두 사이트에서 드러납니다.

하지만 사이트가 중요하다고 해서 사이트 파일이 글쓰기 원본이 되는 것은 아닙니다.

AI Survival Log의 기본 흐름은 이렇습니다.

raw -> wiki -> output/blog -> ai-survival-log-site/content/posts

이 흐름에서 각 layer의 역할은 다릅니다.

Layer	맡는 역할	원본으로 쓰면 안 되는 이유
raw/	원문, 대화, 자료를 보존합니다	해설과 재작성 판단을 넣기 시작하면 원본성이 흐려집니다
wiki/	요약, 연결, 판단, 발행 가능한 글을 작성합니다	이 layer가 글쓰기 원본입니다
output/blog	wiki에서 만든 publish artifact를 둡니다	다시 생성할 수 있어야 하므로 고치는 원본이 아닙니다
ai-survival-log-site/content/posts	사이트가 읽는 downstream post를 둡니다	독자가 만나는 결과물이지만 authoring source는 아닙니다

이 표의 핵심은 역할의 높낮이가 아닙니다. 어느 곳에서 무엇을 판단할지 정하는 것입니다.

raw는 원본이지만 해설을 쓰는 곳은 아니었습니다

raw/는 가장 앞에 있습니다.

그렇다고 raw/가 글쓰기 원본이라는 뜻은 아닙니다. raw/는 원문을 보존하는 곳입니다. 대화 백업, 기사 원문, 영상 메모, 수집 자료처럼 나중에 다시 확인해야 하는 입력을 가능한 한 그대로 둡니다.

이 layer에서 중요한 것은 해석보다 보존입니다.

원문을 가져온 뒤 바로 다듬고, 요약하고, 해설하고, 발행용 문장을 섞기 시작하면 나중에 어떤 부분이 원자료였고 어떤 부분이 후속 판단인지 흐려집니다. 그래서 raw/는 불변 원본 계층에 가깝게 둡니다.

반대로 사람이 읽기 좋게 정리한 설명, 관련 페이지 연결, 공개 글로 바꾸기 위한 문장 판단은 wiki/에서 합니다.

이 분리가 있으면 다시 확인하기가 쉬워집니다.

글을 쓰다가 "이 표현은 원래 어디서 나온 판단인가"를 확인해야 할 때 raw/로 돌아갈 수 있습니다. 하지만 글을 고칠 때는 raw/를 직접 고치는 것이 아니라, wiki/의 판단과 문장을 고칩니다.

wiki는 글쓰기 판단이 모이는 곳입니다

AI Survival Log에서 wiki/는 단순한 메모 폴더가 아닙니다.

wiki/는 source-of-truth입니다. 여기서 source-of-truth라는 말은 "나중에 다시 만들 때 기준이 되는 곳"이라는 뜻에 가깝습니다.

글의 제목, 설명, slug, related link, 발행 여부, 시리즈 위치, 어떤 자료를 근거로 삼았는지에 대한 판단은 wiki/에 남깁니다. 공개 글이 되기 전의 초안도 wiki/topics/에 둡니다. 운영 계획이나 검수 결과는 wiki/projects/에 남깁니다.

이 구조의 장점은 두 가지였습니다.

첫째, 사람이 직접 읽고 고칠 수 있습니다. Markdown으로 남아 있기 때문에 Obsidian에서도 읽을 수 있고, git diff로도 변화가 보입니다.

둘째, 나중에 다른 결과물을 만들기 쉽습니다. 블로그 글, Instagram 카드, future RAG, state JSON 같은 것들이 필요해져도, 판단의 원본은 하나로 유지할 수 있습니다.

원본이 하나라는 것은 단순한 정리 취향이 아닙니다. drift를 줄이는 장치입니다.

같은 글의 제목이 wiki와 site와 state JSON에 따로 고쳐지기 시작하면, 어느 값이 최신인지 매번 다시 판단해야 합니다. 그래서 이 시스템에서는 markdown wiki가 이깁니다.

output과 site post는 다시 만들 수 있어야 했습니다

output/blog는 버려도 된다는 뜻이 아닙니다.

오히려 발행 흐름에서는 매우 중요합니다. wiki/에서 작성한 publishable page를 site가 읽을 수 있는 형태로 바꾼 결과가 output/blog에 생깁니다. 이 단계에서 frontmatter가 변환되고, 위키 링크가 사이트 링크로 바뀌고, 발행에 필요 없는 ## 관련 페이지 같은 내부 section이 제거됩니다.

하지만 중요하다는 것과 원본이라는 것은 다릅니다.

output/blog는 재생성 가능한 artifact여야 합니다. site의 content/posts도 downstream consumer에 가깝습니다. 사람이 읽는 최종 화면과 연결되지만, 글쓰기 판단의 원본은 아닙니다.

이 원칙이 없으면 편한 수정이 나중의 비용이 됩니다.

예를 들어 사이트에서 깨진 문장을 바로 고쳤는데, wiki 원본을 고치지 않으면 다음 publish 때 다시 예전 문장이 나올 수 있습니다. 반대로 wiki만 고치고 output과 site 반영을 확인하지 않으면 독자 화면은 그대로일 수 있습니다.

그래서 흐름을 나눕니다.

먼저 wiki에서 판단을 닫습니다. 그 다음 output을 다시 만듭니다. 마지막으로 site에서 결과를 확인합니다.

구조 리팩토링에서 이 경계가 실제로 걸렸습니다

이 구조는 처음부터 깔끔하게 정해진 것은 아니었습니다.

이전 리팩토링에서 이미지 위치를 두고 경계가 한 번 걸렸습니다. 처음에는 docs/images 같은 위치에서 자료를 다루려는 흐름이 있었지만, 실제 계약을 다시 보니 원본 자료, 블로그용 자산, 재생성 결과물의 역할이 서로 달랐습니다.

그때 중요한 것은 누가 먼저 계획했느냐가 아니었습니다.

실제 repo 상태와 publishing contract를 함께 보면서, 어떤 파일이 원본이고 어떤 파일이 결과물인지 다시 맞춘 점이 중요했습니다. 이미지도 원문 자료인지, 블로그에 쓰이는 upstream asset인지, 사이트에서 serving되는 public asset인지에 따라 위치가 달라졌습니다.

글도 마찬가지입니다.

눈에 보이는 site post가 있다고 해서 그것이 authoring source가 되지는 않습니다. 반대로 wiki가 원본이라고 해서 site 확인을 생략해도 되는 것도 아닙니다.

이 둘을 분리해야 검증이 가능합니다.

기계가 읽는 state도 원본은 아니었습니다

이 repo에는 output/state 같은 derived JSON도 있습니다.

이런 파일은 유용합니다. index를 만들고, publish 상태를 확인하고, 자동화나 RAG 같은 후속 시스템이 읽기 좋은 형태를 제공할 수 있습니다.

하지만 JSON이 생겼다고 해서 JSON이 원본이 되지는 않습니다.

이 결정은 의도적입니다. 사람은 wiki markdown을 읽고 고칩니다. 스크립트는 그 결과를 바탕으로 state를 만듭니다. 만약 state JSON과 wiki markdown이 충돌하면, 기준은 wiki markdown입니다.

future RAG도 같은 방식으로 봅니다.

나중에 검색이나 벡터 DB가 붙더라도, 그것은 wiki에서 파생된 layer입니다. authoring source를 RAG나 JSON으로 옮기는 순간, 사람에게 읽히는 원본과 기계가 쓰는 원본이 갈라집니다.

이 시스템은 그 갈라짐을 최대한 늦추는 방향을 택했습니다.

그래서 다음 질문은 발행 루프였습니다

원본과 결과물을 나누면 다음 질문도 더 선명해집니다.

wiki가 원본이고 site가 결과물이라면, 글을 사이트에 올렸다고 작업이 끝난 것일까요. 검색엔진이 글을 발견하는지, sitemap과 robots가 맞는지, Search Console이나 Search Advisor 제출 기록이 남았는지도 별도의 루프로 봐야 했습니다.

발행 직전의 판단도 마찬가지였습니다. 콘텐츠 준비, 빌드 통과, 공개 반영과 rollback 판단은 서로 다른 질문입니다. 이 질문들을 하나로 묶으면 사용자는 매번 너무 많은 상태를 한 번에 봐야 합니다.

다만 이 글에서는 그 방법을 자세히 다루지 않습니다. 1편의 목적은 원본과 결과물의 경계를 닫는 것입니다.

다음 글에서는 SEO 제출과 indexing ledger를 다룹니다. 그 다음 글에서는 content, build, deploy queue를 사람이 쉽게 판단할 수 있는 표면으로 정리합니다.

좋은 발행 시스템은 글이 보이는 곳과 글을 고치는 곳을 일부러 분리합니다. 그리고 그 분리 덕분에 다음 단계의 검증 루프도 따로 닫을 수 있습니다.