Skip to main content

아카이브 화면은 Docusaurus로 둡니다

개요: 아카이브 도구로 Docusaurus를 고른 이유입니다. Markdown 파일이라 에이전트가 읽고 쓰기 쉽고, React라 화면 커스텀이 쉬우며, 요즘 AI 에이전트는 다른 폴더를 그대로 임포트해서 쓰므로 Markdown 파일 관리가 곧 에이전트 사용이 됩니다.

상태​

채택됨

배경​

ADR-0001에서 원본을 Git 안의 Markdown으로 정했습니다. 그 파일을 사람이 읽고, 에이전트가 읽고, 화면으로도 보여 줄 도구가 필요했습니다. 도구를 고를 때 중요했던 것은 기능 목록이 아닙니다. 파일을 건드리지 않으면서, 사람과 에이전트 모두에게 편해야 했습니다.

이유​

1. Markdown 파일이라 에이전트가 읽고 쓰기 쉽습니다​

Docusaurus의 콘텐츠는 변환 없이 그대로인 .md / .mdx 파일입니다. 에이전트가 이 아카이브에서 하는 일, 역할 문서를 읽고, 오케스트레이션을 고르고, 템플릿 코드를 복사하고, Curator가 새 문서를 쓰는 일은 전부 평범한 파일 읽기와 쓰기로 끝납니다.

  • 특별한 API나 export 단계가 없습니다. 파일이 곧 콘텐츠입니다.
  • 에이전트가 문서를 추가하거나 고쳐도 사람이 보는 화면이 그대로 따라옵니다.
  • 코드 템플릿(.java)을 README 옆에 두고 코드 블록으로 보여 줄 수 있어서, 에이전트는 원본 파일을 복사하고 사람은 사이트에서 읽습니다.

2. React 기반이라 화면 커스텀이 쉽습니다​

홈, About, 나중에 붙일 광고 자리처럼 문서가 아닌 화면이 몇 개 필요했습니다. Docusaurus는 React라서 이런 페이지를 src/pages/에 컴포넌트로 만들면 됩니다. 테마를 해킹하거나 별도 프론트를 붙이지 않아도 됩니다. 작성자가 이미 쓰는 스택이기도 해서 화면을 고치는 비용이 낮습니다.

3. 요즘 AI 에이전트는 다른 폴더를 임포트해서 씁니다​

Cursor, Claude Code, Codex 같은 에이전트는 작업 중인 프로젝트 밖에서 폴더 하나를 통째로 컨텍스트로 가져올 수 있습니다. 그래서 이 아카이브를 Markdown 파일로 관리해 두면, 다른 프로젝트에서 일할 때 이 저장소(또는 docs/harness/ 같은 하위 폴더)를 그대로 임포트하는 것이 곧 하네스를 쓰는 것이 됩니다.

  • 배포나 동기화 절차가 없습니다. Git에 있고 파일이면 임포트됩니다.
  • 임포트한 쪽 에이전트는 평문 Markdown을 읽으므로, 사이트가 어떻게 렌더링되는지는 몰라도 됩니다.
  • 화면(Docusaurus)과 사용(폴더 임포트)이 같은 파일에서 갈라지므로, 사이트를 끄거나 바꿔도 에이전트 사용은 그대로입니다.

이 세 가지가 한 방향입니다. Markdown으로 관리하니 읽고 쓰기 쉽고, React라 보여 주기도 쉽고, 파일 폴더라 에이전트가 가져가서 쓰기 쉽습니다.

결정​

Docusaurus(classic preset, docs 플러그인만, 블로그 비활성)로 Origemite Archive를 관리하고 보여 줍니다.

  • docs/는 /docs로 서빙하고 사이드바는 폴더 구조에서 자동 생성합니다.
  • _category_.json, sidebar_position, unlisted, frontmatter는 탐색과 표시용입니다. 이것들에 엔지니어링 의미를 담지 않습니다.
  • 문서가 아닌 화면(홈, About, 법적 고지 등)만 src/pages/의 React 컴포넌트로 만듭니다.
  • 블로그 플러그인은 끕니다. 날짜순 글이 필요해지면 그때 별도 결정으로 다룹니다.

대안​

  1. Hugo / Jekyll: 정적 빌드는 빠르지만 테마가 블로그 우선이라, 폴더 트리 사이드바와 React급 커스텀 페이지를 만들려면 테마를 고쳐야 합니다.
  2. MkDocs (Material): Markdown 트리를 사이트로 만드는 데는 가장 가깝습니다. 다만 커스텀 페이지가 약하고, 나머지 작업이 JS/Java인 저장소에 Python 툴체인이 하나 더 생깁니다.
  3. VitePress: 가볍고 문서에 강합니다. 커스텀은 Vue로 하게 되는데, 이 스택의 다른 어디에서도 Vue를 쓰지 않습니다.
  4. 직접 Next.js / Astro: 화면 자유도는 가장 높지만, 사이드바, 검색, MDX 처리를 전부 직접 만들고 유지해야 합니다. 아카이브가 목적이고 사이트는 아닙니다.
  5. GitBook / Notion / Obsidian Publish: 쓰기 경험은 좋지만 콘텐츠가 벤더 형식이나 벤더 저장소로 들어갑니다. 폴더를 임포트해서 쓰는 방식과 맞지 않고, ADR-0001의 원본 원칙과도 어긋납니다.

결과​

  • 에이전트가 문서를 읽고 쓰는 것이 파일 작업이라, 별도 연동이 없습니다.
  • 다른 프로젝트에서 이 저장소를 임포트하는 것만으로 하네스를 쓸 수 있습니다.
  • 화면 커스텀은 React 컴포넌트라 비용이 낮습니다.
  • main에 푸시하면 GitHub Actions가 빌드해서 S3에 올립니다. 사이트 반영은 커밋으로 끝납니다.

관련​

저장소 경로: docusaurus.config.ts, sidebars.ts, docs/**/_category_.json, src/pages/.