서론

안녕하세요, 주식회사 Kiva의 uchida입니다.

이 기사에서는 ReadMe.io에서 운용하던 개발자용 문서를 Copilot CLI를 사용하여 셀프 호스팅 환경으로 옮겼을 때의 모습을 소개합니다.

아울러, 이식 과정 중에 만든 Skill과 그 업데이트 규칙이 얼마나 효과적이었는지도 함께 적어두겠습니다.

배경

저희 회사의 가장 오래된 서비스인 Proteger에서는 ReadMe.io를 이용하여 개발자 문서를 공개하고 있었습니다.

최근 들어 ReadMe.io에 월 4만 엔 정도를 지불하고 있었다는 사실이 밝혀졌습니다.

다른 서비스에서는 이미 Docusaurus나 Starlight의 운용 실적이 있었고, 이전부터 "문서는 셀프 호스팅으로 옮기고 싶다"고 생각하고 있었기에, 다음 구독 갱신 전까지 이행하기로 결정했습니다.

요구사항 정비 · 아키텍처 설계

• API Reference를 자동 생성할 수 있을 것
• 추가 비용이 거의 들지 않을 것

요구사항은 이 두 가지뿐이었습니다.

ChatGPT에 상담해 본 결과 fumadocs가 후보로 나왔고, 직접 만져보니 느낌이 좋아 채택했습니다. 개인적으로는 지금까지 사용해 본 것 중 가장 느낌이 좋았습니다.

실행 환경은 AWS로 통일하고 싶었기에, 처음에는 S3 + CloudFront 또는 AWS Amplify 중 하나로 진행하는 것을 전제로 했습니다.

이식 절차 구상

이식 대상 문서는 크게 3개 파트였습니다. 서비스 가이드, API Reference, Changelog입니다.

• 서비스 가이드는 사이트상의 Copy Markdown으로 취득할 수 있으므로, 브라우저 조작을 자동화하여 회수하는 방침으로 정했습니다.

• 50페이지 정도라 수작업으로도 30분 정도 걸릴 것이라 생각했지만, 기왕 하는 김에 AI에게 맡기기로 했습니다.

• API Reference는 사내에서 관리하는 openapi.yaml로부터 자동 생성할 수 있으므로, 리포지토리 내에 심볼릭 링크(Symbolic Link)로 배치하면 충분하다고 판단했습니다.

• Changelog도 서비스 가이드와 동일한 회수 방법을 상정했습니다.

• fumadocs에 Changelog/블로그 전용 기능은 보이지 않았지만, 운용을 통해 흡수할 수 있을 것으로 예상했습니다.

이식 시작

"가급적 AI에게 시킨다"를 전제로, 이식 작업은 Skill을 성장시킴으로써 효율화해 나가는 방침으로 정했습니다.

작업 중에 개선점이 나오면 그 자리에서 반영하고, 완료 시점에 Skill도 업데이트하는 흐름으로 하고 있습니다.

1. 리포지토리 베이스를 수동으로 구축

Quickstart에 따라 토대를 만듭니다.

bunx create-fumadocs-app

셋업 시에는 Next.js (SSR), AI SDK, oxlint를 선택했습니다.

AI 채팅이 처음부터 탑재되어 있는 것은 놀라웠습니다. openrouter의 openai/gpt-oss-120b:free를 설정했습니다.

서버 운용이 필요해졌기 때문에, 배포처는 AWS Amplify로 결정했습니다.

별도 리포지토리에서 관리하는 openapi.yaml은 심볼릭 링크로 배치해 둡니다.

Skill 생성에는 Anthropic의 skill-creator를 사전에 넣어두었습니다.

2. openapi.yaml로부터 API Reference 자동 생성

fumadocs의 OpenAPI 연동 문서를 바탕으로, Copilot CLI (GPT-5.3-Codex)에게 autopilot mode로 생성을 의뢰했습니다.

3. 기존 사이트의 외관 만들기

기존 사이트는 탭 바(Tab Bar)로 페이지를 전환하는 UI였기에, 그 부분을 재현했습니다.

UI 확인용으로 skill:docs-ui-checker를 만들어 외관과 동선을 체크했습니다.

아울러 URL slug가 구 사이트와 일치하도록 샘플 페이지 배치도 조정했습니다.

이것으로 토대는 완성되었습니다. 남은 것은 페이지 이식뿐입니다.

4. ReadMe.io에서 문서 이식

이식용으로 skill:readmeio-to-fumadocs-migrator를 생성했습니다.

초판은 "ReadMe의 문서를 fumadocs로 이식한다" 정도의 대략적인 설명입니다. 나중에 자동 업데이트할 예정이므로 처음에는 거칠어도 문제없습니다.

다음으로 skill:instruction-preflight를 생성했습니다.

여기에는 「다른 스킬 실행 전의 준비」, 「검증 방법」, 「유지보수 규칙 (Maintenance rule)」을 작성했습니다. 특히 중요했던 것은, 실행 후에 개선점이 있다면 반드시 Skill 측에 반영하는 규칙입니다.

이 루프가 효과를 발휘하여, 이식을 진행할수록 다음 페이지를 더 안정적으로 처리할 수 있게 되었습니다.

## Skill maintenance rule
At task end, review whether this skill or any skill actively used in the task has missing or outdated guidance.
Update skill content when at least one of these happens:
...

readmeio-to-fumadocs-migrator에는 instruction-preflight를 반드시 참조하도록 내용을 추가했습니다.

당초에는 브라우저 조작으로 Markdown을 복사할 예정이었으나, ReadMe 측의 bot 판정으로 인해 접근할 수 없는 상황이 있었습니다.

최종적으로는 curl로 HTML을 가져온 뒤, 사이드바 정보로부터 섹션 하위 페이지를 한꺼번에 수집하는 방식으로 변경되었습니다.

이식할 페이지의 섹션이 여러 개 있었기 때문에, 다음 루프에서 가장 먼저 Skill을 단련했습니다.

• 우선 1페이지를 이식한다
• fumadocs 측의 에러 (표기법 차이)를 확인한다
• AI에게 수정을 요청한다
• Skill 자동 업데이트

최종적으로 Skill에는 이미지 다운로드 경로 통일, Markdown 표기법 차이 흡수, URL/이메일 주소 처리 등 10개 항목 정도의 규칙이 포함되었습니다.

다만 페이지 수가 그리 많지 않았기에, 딱 Skill이 강해졌을 무렵에 이식이 끝났다는 느낌은 있습니다. 다음에 같은 작업이 있다면 훨씬 수월해질 것입니다.

스킬 규칙의 일부를 아래에 기재해 둡니다.

## Recurring migration rules
- If a migrated page has frontmatter `title` (and optionally `description`), remove a duplicate first `#` heading when it repeats the same title.
- Add frontmatter `description` only when the source page explicitly provides a meaningful description. If source description is missing or unclear, do not force-add one.
...

5. 문장 확인

이식 완료 후, 복사 정밀도를 한 페이지씩 육안으로 확인했습니다.

이 부분이 가장 힘들었습니다. 처음부터 이 확인 공정의 자동화를 고려했어야 했습니다.

실제 사이트의 HTML 비교를 AI에게 자동으로 시킬 수는 있지만, 그럼에도 최종적인 육안 확인은 필요했다고 생각합니다.

나중에 깨달은 점인데, 원본 페이지의 백업을 먼저 리포지토리(Repository)에 저장하고, 그 로컬 Markdown을 바탕으로 Copilot에게 이식을 시키는 편이 정밀도가 더 높아질 것이라고 생각했습니다.

6. 배포

실제로 AWS Amplify에 배포한 결과물이 https://developers.helloproteger.com/ 입니다.

배포 시 막혔던 점들도 남겨둡니다.

• openapi.yaml이 존재하지 않으면 빌드할 수 없음

• 동적 로딩을 중단하고, 페이지 측에 스키마를 내장하는 구성으로 변경

• 빌드 출력물이 너무 커서 Amplify의 max size 초과

• 이미지를 S3로 분리

• 불필요한 standalone 폴더를 삭제

• 일부 페이지만 표시되지 않음

• Git의 대소문자 문제로 디렉토리명이 어긋남

• LLM API Key를 환경 변수에 넣어도 서버에서 보이지 않음

• Amplify의 환경 변수는 빌드 시에만 반영됨. 서버 사용분은 .env에 작성

• Amplify의 환경 변수는 빌드 시에만 반영됨. 서버 사용분은

회고

가장 도움이 되었던 것은 페이지 내 이미지의 다운로드와 경로 재작성을 자동으로 수행해 준 것입니다. 이 부분을 수작업으로 하는 것은 솔직히 매우 힘듭니다.

또한, Skill의 자동 업데이트 규칙은 상당히 효과적이었습니다. 기억에 의존하는 것보다 재현성이 높고, 팀 공유도 용이합니다.

가장 힘들었던 점은 역시 이식 후 검토였습니다. 섹션 순서의 어긋남, 이미지 위치의 어긋남, 문장의 누락, 의도하지 않은 수정 등이 뒤섞여 있었기에, 결국 모든 페이지를 직접 확인하지 않고서는 안심할 수 없었습니다.

돌이켜보면, 모든 페이지의 Markdown을 먼저 로컬에 저장한 뒤, 복사나 이미지 취득, 치환 작업을 스크립트화하여 Skill에 적용하는 방식이 더 빠르고 확실했을 것이라고 생각합니다.

마치며

최종적으로 이식은 2일 정도 걸려 완료되었습니다. ReadMe.io의 운영 스트레스도 해소되었기에, 결과적으로는 상당히 만족하고 있습니다.

Discussion