Markdown 파일을 중심으로 작은 퍼블리싱 플랫폼을 만든 과정

본 프로젝트를 시작하면서 가장 중요한 목표는 내가 글을 쓰고, 관리하고, 원하는 형태의 웹사이트에 발행할 수 있는 작은 블로그 시스템을 만드는 것이었다. 처음부터 이렇게 만들어야겠다는 생각은 없었지만, 아마 평소 막연하게나마 AI Agent가 실제 애플리케이션의 일부로 동작하는 시스템을 만들어보고 싶어하던 마음이 투영되었을지도 모른다. 마침 시작한 LilysAI Ambassador 활동이 그 시작 계기가 되었다.

LilysAI Ambassador 활동

처음 생각했던 구성은 단순했다. 글 전체를 읽고 description이나 태그를 만들어 주거나, 긴 글을 몇 줄로 요약하거나, 외부 링크의 Open Graph 정보만 보여주는 대신 실제 링크의 내용을 읽어 더 의미 있는 Preview를 만드는 정도였다. 처음에는 이 기능들을 하나씩 구현하면 블로그 시스템도 자연스럽게 완성될 것이라고 생각했다. 하지만 실제로 첫 프로토타입을 만들기 시작하자 AI보다 먼저 다른 문제가 나타났다.

첫 프로토타입은 기능보다 기반을 만드는 데 시간이 더 들었다

PayloadPayload: The Next.js Headless CMS and App FrameworkPayload: The Next.js · Built with TypeScript · Payload는 어떤 서비스인가요?

초기에는 Payload CMS와 데이터베이스, visual editor를 중심으로 콘텐츠를 관리하는 구조를 실험했다. CMS를 사용하는 것 자체가 문제였던 것은 아니다. 오히려 잘 갖춰진 CMS라면 콘텐츠 관리에 필요한 많은 기능을 이미 제공한다.

문제는 지금 만들고 있는 것이 작은 개인 프로젝트였다는 점이었다. 새로운 기능 하나를 시험해 보려고 해도 그 기능에 도달하기 전에 저장 방식, editor integration, schema, 변환 과정처럼 직접 구현하고 관리해야 할 것들이 계속 생겼다. 내가 확인하고 싶은 것은 새로운 publishing workflow와 AI 기능이 실제로 유용한지였는데, 초기 prototype을 만드는 과정 자체가 점점 병목이 되고 있었다.

그래서 시스템을 조금 더 단순하게 만들기로 했다. 현재의 canonical content는 frontmatter와 assets를 포함할 수 있는 Markdown/MDX 계열 파일이다. Git commit이 공유 가능한 revision이 되고, Site는 그 revision의 파일을 직접 소비한다.

Obsidian / IDE / Agent
        ↓
 Markdown / MDX + assets
        ↓
   Docs repository
        ↓
      Site
        ↓
  GitHub Pages

여기에 필요한 경우에만 Engine이 같은 document workspace를 후처리한다.

optional Engine processing
        └────────→ same document workspace

글을 작성할 때는 주로 Obsidian을 사용하지만, Obsidian 자체가 시스템의 원본은 아니다. 파일을 의미를 보존하면서 수정할 수 있다면 IDE나 다른 editor, Agent 역시 같은 위치에 들어갈 수 있다.

Repository를 역할별로 나누는 것이 처음에는 관리가 익숙하지 않아 어려웠지만, 이 구조도 나름대로의 장점은 있었다. 어떤 기능이 글 자체를 수정하는지, 어떤 기능이 derived data를 만드는지, 어떤 기능이 최종적으로 그것을 보여주는지를 조금씩 분리할 수 있게 된 것이다. 그리고 이 구조가 만들어지고 나서야 처음 생각했던 AI 기능을 어디에 넣어야 할지도 조금씩 보이기 시작했다.

첫 AI 기능은 가장 싸게 반복할 수 있는 곳에 넣었다

가장 먼저 구현한 것은 article frontmatter enrichment였다.

Engine #23 에서는 문서 본문과 이미 작성되어 있는 metadata를 바탕으로 비어 있는 title, description, tags를 모델이 생성할 수 있도록 했다. 여기에는 거창한 Agent orchestration이 필요하지 않았다.

document
   ↓
missing field detection
   ↓
model inference (Ollama)
   ↓
structured result validation
   ↓
patch only unset fields

Ollama올라마의 문서올라마(Ollama)는 로컬 환경에서 대규모 · 언어 모델(LLM) 실행을 용이하게 하는 툴 · 개발자들이 AI 앱 구축에 활용 가능

Ollama를 활용해 경량 모델을 로컬로 운용하기로 선택한 가장 큰 이유는 단순했다. 별도의 API 비용이 들지 않았고, 실시간으로 응답할 필요도 없었고, 무엇보다 하드웨어 스펙에 여유가 많지 않았다. 문서를 작성한 뒤 한 번 실행해서 metadata를 채우는 작업이라면 수 초나 수십 초의 inference 시간이 제품 경험에 큰 문제가 되지 않는다.

물론 같은 작업을 충분한 context와 함께 더 좋은 model에 맡긴다면 더 좋은 결과가 나올 가능성이 높다고 생각한다. 하지만 사용할 수 있는 token과 computing resource는 무한하지 않다. 현재 가지고 있는 하드웨어 안에서 반복해서 실행할 수 있는 작은 모델을 사용하고, 모델이 해야 할 작업의 범위를 좁히는 편이 이 프로젝트에는 현실적이었다. AI는 잘 구조화된 시스템과 정책 안에서 적절한 scope와 context를 받았을 때 더 좋은 성능을 낼 수 있다고 생각한다. 충분한 모델과 하드웨어가 있다면 Agent에게 더 넓은 자율성을 주는 실험도 해보고 싶다.

이 프로젝트에서 처음 필요했던 것은 이미 가지고 있는 문서에서 몇 개의 반복적인 값을 만들어 주는 기능이었다. 그런데 외부 링크를 다루기 시작하면서 상황이 달라졌다. 로컬 문서 안에 이미 존재하는 정보를 정리하는 것과, URL 하나만 가지고 외부 자료의 내용을 이해하는 것은 다른 종류의 문제였다.

현 상황에서 LilysAI 유용성은 외부 자료를 읽는 능력이었다

ogp.meThe Open Graph protocolOpen Graph 프로토콜은 웹페이지를 · 소셜 미디어 플랫폼에서 풍부한 콘텐츠로 · 표현하여 공유를 향상시킵니다.

외부 링크 Preview를 만들 때 가장 먼저 사용할 수 있는 정보는 Open Graph metadata다. og:title이나 og:description만으로도 기본적인 카드 UI는 만들 수 있다. 하지만 그것만으로는 해당 링크가 실제로 무엇을 설명하고 있는지 충분한 context를 얻기 어려운 경우가 있다.

이 지점에서 LilysAI를 실제 workflow에 연결해 보기 시작했다. 첫 vertical slice인 Engine #42는 의도적으로 단순했다.

external URL
    ↓
LilysAI MCP
    ↓
project / source
    ↓
note generation
    ↓
editable Markdown summary

외부 URL 하나를 LilysAI에 전달하고, 분석이 끝날 때까지 기다린 뒤 생성된 note를 다시 Markdown으로 가져온다. 처음에는 source CLI에서 검증했고 이후 packaged Engine artifact에서도 실제 authenticated flow를 실행했다.

이 실험을 통해 LilysAI에서 가장 유용하다고 느낀 부분은 외부 자료를 읽고 semantic context를 얻는 능력이었다. 이미 가지고 있는 짧은 text를 다시 생성하는 것보다, 직접 읽지 않은 외부 문서를 시스템이 이해할 수 있는 정보로 바꾸는 쪽에서 더 명확한 역할이 보였다.

물론 이건 LilysAI가 가진 실제 능력 중 절반도 쓰지 못하고 있는 것이다. 안타깝게도 Web UI에서 제공되는 기능과 MCP를 통해 제공되는 기능의 범위가 완전히 같지는 않아 더 이상의 고도화는 어려웠다. 어쩌면 현재 시점에서는 통합에 적절한 상태가 아니라고 보는 것이 적절할 수도 있겠다.

MCP를 붙여보니 제품의 기능과 API의 기능은 달랐다

처음에는 LilysAI Web UI에서 경험할 수 있는 기능들을 MCP에서도 비슷하게 조합할 수 있을 것이라고 기대했다. 실제로 연결해 보니 현재 MCP surface는 그보다 제한적이었다.

이번 프로젝트에서 주로 사용한 것은 source를 project에 등록하고, project 상태를 조회하고, note를 생성하고 다시 가져오는 흐름이었다. 이 정도만으로도 외부 링크의 semantic summary를 만드는 데에는 충분했지만, Web UI에서 제공되는 다양한 기능을 그대로 automation에 이용할 수 있는 것은 아니었다.

개발 경험에서도 아쉬운 점이 있었다. 현재는 integration에 사용할 수 있는 SDK나 추상화가 충분히 풍부하다고 느끼지 못했고, 공식 문서만으로 세부 동작을 파악하기 어려운 부분도 있었다. 결국 실제 MCP response와 tool behavior를 직접 확인하고 contract를 만들어 가며 구현해야 했다.

그 과정에서 provider 자체의 제약도 만났다. 예를 들어 실제 Docs preparation 중 help.lilys.ai 링크를 다시 LilysAI source로 넣으려 하자 provider가 이를 지원하지 않아 전체 preparation이 실패했다. Engine #104에서는 이런 LilysAI-owned URL을 provider call 전에 제외하도록 경계를 추가했다. 이 경험은 단순히 예외 하나 추가하는 것보다, 외부 service가 항상 존재하고 항상 성공할 것이라는 전제로 나머지 시스템을 설계해서는 안 된다는 교훈을 남겨주었다.

외부 AI 호출과 publishing을 같은 경계에 두지 않았다

현재 Publishing Platform은 여러 repository로 나뉘어 있다. engine은 document processing을 담당하고, docs는 canonical content와 derived data의 Git revision을 보존하며, oomia.github.io는 그 데이터를 소비해서 실제 Site를 만든다.

이 구조에서 가장 중요하게 생각하게 된 것은 책임의 경계였다. 그래서 Site build 과정에서 LilysAI를 직접 호출하지 않는다.

external URL
      ↓
Engine preparation
      ↓
LilysAI semantic data
      ↓
Docs derived manifest
      ↓
exact Git revision
      ↓
Site

외부 network와 상태를 가진 서비스는 preparation 단계에서 호출하고, 그 결과는 Docs가 derived data로 보존한다. 또 Site는 자신이 pin한 Docs revision의 로컬 데이터만 읽는다.

Engine은 producer의 동작을 소유하고, Docs는 durable state를 소유하고, Site가 presentation을 소유한다. Knowledge라는 공통 정책 레포를 통해, 나는 한 레포가 다른 것의 내부 구현까지 알아야 하는 상황을 가능한 한 만들지 않으려고 했다. (물론 best-practice 관점에서 당연한 것이지만)

이 구조를 선택한 가장 큰 이유는 cache나 API 비용보다도 멀티 repository 환경에서 책임을 분명하게 유지하기 위해서였다.

읽기 위한 정보와 보여주기 위한 정보는 달랐다

semantic summary를 안정적으로 저장할 수 있게 되자 또 하나의 문제가 보였다. 자료를 이해하기 위한 정보와 사용자가 화면에서 읽기 좋은 정보는 같지 않았다.

LilysAI가 만들어 준 summary는 자료를 이해하는 데에는 유용하지만, 그것을 그대로 작은 LinkCard 안에 넣을 수는 없다. 반대로 Open Graph metadata는 presentation에 유용한 title, image, site name 등을 가지고 있지만 source의 내용을 충분히 설명하지 못할 수도 있다.

그래서 현재의 rich LinkCard에서는 데이터를 세 종류로 나누게 됐다.

semantic
  → LilysAI

preview
  → Open Graph / Twitter / HTML metadata

presentation
  → local model

LilysAI는 외부 source의 의미를 읽는다. Engine의 deterministic fetch/parser는 target page에서 presentation에 필요한 metadata를 수집한다. 그리고 local model은 이미 확보된 semantic/preview 정보를 바탕으로 제한된 UI 안에서 보여줄 ordered three-line presentation을 만든다. 최종적으로 만들어진 derived record는 Docs에 저장되고 Site는 local manifest만을 사용해서 LinkCard를 렌더링한다.

AI를 많이 붙이는 것보다 시스템을 잘 나누는 것이 더 중요했다

이 프로젝트를 시작할 때에는 AI Agent를 애플리케이션 안에 넣어 보고 싶다는 생각이 먼저 있었다. Cycle 1을 마친 지금은 그 관심 자체는 변하지 않았다. 충분한 computing resource와 더 큰 모델을 사용할 수 있다면 Agent에게 더 넓은 context와 자율성을 주는 시스템도 여전히 만들어 보고 싶다.

다만 이번 프로젝트에서는 다른 것을 먼저 경험했다. AI 기능의 수를 늘리는 것보다 AI가 어떤 데이터를 보고, 어떤 결과를 만들고, 그 결과를 누가 보존하고, 누가 최종적으로 소비하는지를 구분하는 것이 훨씬 중요했다.

• 작은 local model은 제한된 metadata generation을 담당했다.
• LilysAI는 외부 자료에서 semantic context를 얻는 역할을 담당했다.
• deterministic code는 URL을 찾고, metadata를 검증하고, repository 사이의 contract를 지켰다.
• Git은 그 결과를 재현 가능한 revision으로 남겼다.
• 그리고 Site는 producer가 어떤 모델이나 서비스를 사용했는지 알지 않아도 결과를 렌더링할 수 있게 했다.

write
  ↓
commit
  ↓
optionally enrich
  ↓
persist derived state
  ↓
validate
  ↓
render
  ↓
deliver

이번 Cycle에서는 별도의 model API 사용료를 지출하지 않았다. 이미 가지고 있던 컴퓨팅 자원에서 local inference를 실행했고, 무료로 제공받은 2개월 치 ChatGPT 플랜을 개발 과정에 활용했으며, LilysAI Ambassador 활동을 계기로 플랜이 제공된 계정으로 MCP integration을 실험했다.

더 큰 모델, 실시간 inference, 더 높은 throughput이나 복잡한 autonomous Agent가 필요해지면 지금의 방식으로는 부족할지 모른다. 하지만 적어도 이번 프로젝트를 통해 확인한 것은, 처음부터 큰 Agent framework나 많은 API budget을 준비하지 않아도 문제를 작게 나누고 시스템의 경계를 잘 설계하면 AI 기능을 실제 개발·발행 workflow 안에 꽤 깊게 연결할 수 있다는 것이었다.

또 하나 좋았던 점은, 처음 생각했던 구조와 실제로 만들어진 시스템이 꽤 달랐는데, 그 차이는 다양한 문제와 의문점을 에이전트의 대화를 통해 풀어나가 얻은 결과에 가깝다는 것이다. 좋은 질문을 던지는 것만으로도 내 궁금증을 해소할 수 있는 것이 새삼 기뻤고, 이전과는 달리 많이 발전해서 정확도도 높아진 것을 체감할 수 있었다. 앞으로도 프로젝트를 진행하게 된다면, 이러한 구조를 범용성 있게 잘 다듬어 사람들에게 인사이트를 전달하는 글로 나누고 싶다.

Cycle 1 프로젝트 활동

아래 이미지는 Cycle 1 동안의 AI 활용, 직접 개발 활동과 GitHub Project 진행 상황을 기록한 snapshot이다.

References

engine, docs 레포는 GitHub Self-hosted runner를 사용하여, 아쉽지만 공개 대상이 아닙니다.

• Publishing Platform — GitHub Project #11
• Filesystem-first Engine — Engine #21, PR #22
• Local model frontmatter enrichment — Engine #23, PR #30
• LilysAI URL summary vertical slice — Engine #42, PR #43
• External-link first integration — Knowledge #40
• Rich LinkCard integration — Knowledge #42
• LinkCard producer — Engine #79
• LilysAI unsupported-source handling — Engine #104
• Derived LinkCard persistence — Docs #16, Docs #18
• Rich LinkCard consumer — Site #53, PR #60
• LinkCard presentation calibration — Site #61, PR #62
• Deferred article summary experiment — Engine #15
• Deferred MCP-assisted article metadata — Engine #24
• Architecture / release Evidence — Knowledge Context, Implementation Map