Confluence 아키텍처 문서를 MCP로 Archyl에 마이그레이션하는 방법 - Archyl Blog

Confluence를 떠나지 않아도 됩니다. 아키텍처를 설명하는 페이지만 옮기고 나머지는 그대로 두세요. 옮기는 일은 Atlassian의 MCP 서버와 Archyl의 MCP 서버를 같은 AI 에이전트에 연결하면 끝납니다.

Confluence 아키텍처 문서를 MCP로 Archyl에 마이그레이션하는 방법

매주 듣는 이야기가 있습니다. 한 팀이 Archyl을 도입해 시스템을 C4로 모델링하고, ADR과 API 계약을 연결합니다 — 그리고 누군가 당연한 질문을 던지죠: "Confluence에 있는 200페이지는 어떡하죠?"

먼저 할 말은, 벤더 입에서 나올 거라고는 아무도 기대하지 않는 이야기입니다. 그 페이지들 대부분은 Confluence에 그대로 두는 게 맞습니다. 회의록, 온보딩 체크리스트, 온콜 runbook, 지난 분기 기획 문서. 그건 Confluence가 잘하는 일이고, Archyl이 가져가려는 영역도 아닙니다. 옮겨야 하는 건 아키텍처를 설명하는 부분뿐이고, 어떤 페이지가 거기에 해당하는지 가려내는 일이 사실 작업의 대부분입니다.

예전에 어려웠던 건 옮기는 작업 자체의 품이었습니다. 예전이라면 답은 "임포터가 나올 때까지 기다리세요" 아니면 "오후 내내 복사-붙여넣기 하세요"였습니다. 어느 쪽도 좋지 않죠. 하지만 지난 1년 사이 뭔가 달라졌습니다: 이 마이그레이션의 양쪽 모두가 이제 MCP를 말합니다.

Atlassian은 Confluence와 Jira를 어떤 AI 에이전트에게든 열어 주는 공식 원격 MCP 서버를 제공합니다. OAuth와 기존 권한 체계를 그대로 쓰죠. 그리고 Archyl은 문서, 폴더, ADR, C4 모델 전체 — 플랫폼 전부를 자체 MCP 서버로 노출합니다. 도구가 181개입니다.

그 가운데에 에이전트를 하나 놓으면, 기다리던 임포터가 프롬프트 하나가 됩니다.

어떤 페이지가 옮겨 가고, 어떤 페이지가 남는가

무엇이든 연결하기 전에 이것부터 하세요. 제가 쓰는 판단 기준은 이렇습니다. 새로 합류한 엔지니어가 이 페이지를 필요로 하는 이유가 시스템이 어떻게 돌아가는지 이해하기 위해서인가, 아니면 첫 주를 넘기기 위해서인가? 앞쪽은 모델 옆에 있어야 할 것이고, 뒤쪽은 위키에 있어야 할 것입니다.

그러면 스페이스 하나가 네 무더기로 나뉩니다.

  • 문서로 옮기세요. 시스템을 설명하는 페이지들입니다. 결제 서비스가 어떻게 만들어졌는지, 무엇과 통신하는지, 왜 앞단에 큐가 있는지, 재시도 정책은 어떤지. Archyl에서는 이런 문서를 그것이 설명하는 container나 시스템에 붙입니다. 그러면 페이지 트리에서 세 번 클릭해 들어가는 대신, 해당 요소와 함께 바로 눈에 들어옵니다.
  • ADR로 옮기세요. "Why we chose X", RFC, 트레이드오프 정리 글, 결정으로 마무리된 사후 분석 페이지. 이것들은 문서가 아니라 결정이고, Archyl은 이를 상태를 가지고 영향을 준 요소와 연결되는 별개의 객체로 다룹니다.
  • Confluence에 두세요. 회의록, 스프린트 계획, 팀 핸드북, 그리고 Jira 매크로를 중심으로 짜여 사실상 살아 있는 리포트인 페이지들. 이런 걸 옮기면 얻는 건 없고 매크로만 잃습니다.
  • 지우세요. 어느 스페이스에나 2년 전에 내려간 시스템을 설명하는 페이지가 있습니다. 마이그레이션은 누군가 그걸 다시 읽어 볼 유일한 기회이고, 그러니 정직하게 지울 수 있는 유일한 기회이기도 합니다.

먼저 분류하는 것 — 그게 이 작업을 전부 아니면 전무의 마이그레이션으로 만들지 않는 방법입니다. 당신은 Confluence를 비우는 게 아닙니다. 거기서 한 겹을 뽑아내는 겁니다.

필요한 것

  • MCP 클라이언트. 여기서는 Claude Code를 쓰지만, Cursor나 다른 MCP 호환 에이전트도 똑같이 동작합니다.
  • Confluence 계정 — 마이그레이션할 스페이스에 대한 읽기 권한이 있어야 합니다.
  • Archyl API 키 — _프로필 → API 키_에서 쓰기 스코프로 하나 만드세요.

두 서버 연결하기

명령어 두 줄이면 됩니다. 먼저 Atlassian의 호스팅 서버부터 (처음 사용할 때 OAuth를 위해 브라우저가 열립니다):

claude mcp add --transport http atlassian https://mcp.atlassian.com/v1/mcp/authv2

그다음 Archyl:

claude mcp add --transport http archyl https://api.archyl.com/mcp \
  --header "X-API-Key: your_api_key"

설정은 이게 전부입니다. 이제 에이전트는 당신의 위키를 읽고 아키텍처 워크스페이스에 쓸 수 있습니다.

마이그레이션을 만들지 말고, 설명하세요

실제 프롬프트입니다. 우리 스페이스에 썼던 것과 거의 같습니다:

"Platform Engineering" Confluence 스페이스를 내 Archyl 프로젝트
"Aurora Commerce"로 마이그레이션해줘.

1. 먼저 스페이스의 페이지 트리를 나열하고 계층 구조를 보여줘 —
   아직 아무것도 가져오지 마.
2. 문서 폴더로 계층 구조를 재현한 다음, 각 페이지를 마크다운으로
   가져와. 제목은 유지하고, 서식은 정리하고, 가져온 페이지들
   사이의 링크는 Archyl 버전을 가리키도록 다시 써줘.
3. 결정을 기록한 페이지 — "Why we chose X", RFC, 트레이드오프
   정리 글 — 는 일반 문서 대신 ADR로 만들어줘. 상태는 accepted로
   하고, 원래 날짜는 컨텍스트 첫 줄에 넣어줘: "2024-03-11 결정,
   Confluence에서 이관."
4. 만든 것 전부를 요약 표로 보여줘.

다음에 벌어지는 일을 보세요. 에이전트는 getConfluenceSpaces와 getPagesInConfluenceSpace를 호출해 스페이스 지도를 그리고, getConfluencePageDescendants로 트리를 순회하며, getConfluencePage로 각 페이지를 가져옵니다. Archyl 쪽에서는 create_documentation_folder로 구조를 그대로 비추고, 각 페이지를 마크다운으로 변환해 create_documentation으로 안착시킨 다음, move_documentation을 호출해 알맞은 폴더에 정리해 넣습니다(문서를 만드는 것과 배치하는 것은 별개의 도구입니다). 그리고 — 제가 제일 좋아하는 부분인데 — 결정 성격의 페이지는 create_adr로 따로 보냅니다.

이 마지막 단계가 보기보다 중요합니다. 어느 팀의 위키에나 "Documentation" 아래 화석처럼 굳어 버린 결정들이 한 겹 묻혀 있습니다. 임포터라면 그대로 복사했을 겁니다. 에이전트는 그것을 읽고, "Why we moved off RabbitMQ"가 아키텍처 결정이라는 것을 알아채고, 결정이 있어야 할 자리에 정리해 넣습니다 — 그 결정이 영향을 준 요소에 연결되고, C4 모델 옆에서 조회 가능한 상태로요.

0단계 규칙: 대량 작업 전에 리뷰하세요

프롬프트에 "계층 구조를 먼저 보여줘 — 아직 아무것도 가져오지 마"라고 적혀 있는 것을 눈여겨보세요. 꼭 그렇게 하세요. 어느 위키에나 아카이브 섹션, 회의록 무덤, 그리고 2019년에 만들어진 "TEST do not delete"라는 페이지가 있습니다. 에이전트가 트리를 제안하게 하고, 답장 한 번으로 가지치기한 뒤("Archive랑 Meeting Notes는 건너뛰어"), 그다음에 돌리세요.

200페이지라는 게 실제로는 어떤 일인지

프롬프트 한 번에 오후 한나절로 끝나는 일이 아닙니다. 실제 진행을 좌우하는 게 네 가지 있고, 그걸 미리 아느냐가 깔끔하게 끝난 마이그레이션과 반쯤 하다 만 마이그레이션을 가릅니다.

스페이스 단위가 아니라 섹션 단위로 진행하세요. 에이전트는 배치 사이에도 컨텍스트를 유지하고, 요약을 읽을 수 있는 크기의 배치는 당신이 고칠 수 있는 배치입니다. 열 페이지, 확인, 다시 열 페이지.

Atlassian 서버는 스로틀링을 겁니다. 그것도 예상과는 다른 지점에서요. 공식 MCP 서버에 열려 있는 이슈(2026년 5월 29일 등록, Atlassian의 답변은 아직 없음)에 따르면, 몇 시간에 걸쳐 총 200~300회 정도밖에 안 되는 호출량인데도 병렬 호출이 약 20건을 넘어가면 429가 돌아온다고 합니다. 작성자의 해석은 지속적인 부하보다 동시성 스파이크에 오류가 따라붙는다는 것입니다. 실제 한도가 얼마든 지시는 같습니다. 페이지를 한꺼번에 펼쳐서 처리하지 말고 하나씩 순서대로 처리하라고 에이전트에게 말하세요.

실패한 배치를 다시 돌리면 중복이 생깁니다. Archyl은 문서 slug의 고유성을 강제하지 않습니다. 그래서 열 페이지 중 일곱 번째에서 배치가 죽었을 때 "다시 해봐"라고 하면, 앞의 여섯 개가 두 벌 생깁니다. 재시도 전에 list_documentation을 호출해 이미 있는 것은 건너뛰도록 에이전트에게 요청하세요.

깊은 트리는 평평해집니다. Archyl은 문서 폴더를 3단계까지만 허용합니다. 그보다 깊게 중첩된 Confluence 트리는 Maximum folder nesting depth (3 levels) reached를 돌려주니, 40페이지쯤에서 알게 되는 대신 시작 전에 어떤 단계를 합칠지 정해 두세요.

솔직한 한계

  • 첨부 파일은 여전히 스스로 따라오지 않습니다. 다만 이유가 반대편으로 옮겨 갔습니다. 이 글이 처음 나왔을 때 Archyl에는 첨부 파일을 둘 자리가 없었습니다. 지금은 있습니다. 문서 첨부 파일은 S3 호환 오브젝트 스토리지를 기반으로 이미 제공되고 있고, 당신의 API 키를 가진 에이전트는 파일을 문서에 곧바로 올릴 수 있습니다. 빈 곳은 Confluence 쪽입니다. Atlassian의 원격 MCP 서버에는 첨부 파일 도구가 아예 없습니다 — 2026년 8월 기준 지원 도구 목록에는 Confluence 관련 작업이 열두 개 있지만 파일을 건드리는 건 하나도 없고, 기능 요청은 2026년 3월부터 열린 채로 있습니다. 그러니 에이전트는 MCP로 바이트를 가져올 수 없습니다. Confluence REST API로는 가져올 수 있고(GET /wiki/api/v2/pages/{id}/attachments가 파일마다 downloadLink를 돌려줍니다), 그다음 하나씩 밀어 넣을 수 있습니다:

    curl -X POST https://api.archyl.com/api/v1/docs/$DOC_ID/attachments \
  -H "X-API-Key: $ARCHYL_API_KEY" \
  -F "file=@architecture-overview.png"

    응답에는 페이지에 그대로 붙여 넣을 수 있는 마크다운 스니펫이 들어 있습니다. 파일 형식은 가리지 않고, 기본값은 개당 10 MB입니다. 다만 이게 무엇인지는 분명히 해 두죠. 이건 스크립트이고, 두 번째 자격 증명(Atlassian API 토큰. MCP 서버가 들고 있는 OAuth 세션은 빌려 쓸 수 있는 게 아니니까요)이 필요합니다. 대부분의 스페이스에서는, 정말로 중요한 다이어그램 몇 장만 Archyl 에디터로 다시 업로드하는 쪽이 여전히 더 빠른 답입니다.

  • ADR에는 당신이 만든 날짜가 찍힙니다. MCP든 REST든 결정 날짜를 받아 주는 API가 없어서, 2023년에 내린 결정도 오늘 날짜로 안착합니다. 위 프롬프트가 원래 날짜를 컨텍스트에 적어 두게 하는 이유가 그것입니다. 10년 치 결정을 한 번에 옮기기 전에 알아 둘 만합니다.

  • 문서는 모델에 스스로 연결되지 않습니다. 에이전트는 ADR을 시스템이나 container에 한 번의 호출로 붙일 수 있습니다(link_adr_to_element). 문서에는 아직 대응하는 MCP 도구가 없어서, 가져온 문서는 연결되지 않은 상태로 도착합니다. UI에서 연결하거나, 같은 API 키로 에이전트가 /api/v1/docs/{id}/links에 POST하게 하세요. 이 단계는 건너뛰지 마세요. 문서가 그것이 설명하는 container 옆에 놓여 있다는 것, 그게 그 문서가 위키를 떠난 이유 전부니까요.

  • 복잡한 매크로는 품질이 떨어집니다. Confluence의 화려한 매크로 — Jira 이슈 테이블, 동적 리포트 — 는 일반 텍스트나 링크가 됩니다. 코드 블록, 표, 정보 패널은 깔끔하게 변환됩니다.

  • 권한은 당신의 권한 그대로입니다. Atlassian MCP 서버는 OAuth 사용자가 읽을 수 있는 것만 노출합니다. 이건 기능입니다.

왜 이 방식이 고전적인 임포터를 이기는가

일회성 임포터는 바이트를 옮깁니다. 에이전트는 _의미_를 옮깁니다: 마이그레이션하면서 구조를 다시 잡고, 결정을 ADR로 바꾸고, 죽은 서식을 고치고, 끝나면 "뭘 건너뛰었고 왜 그랬는지"까지 답해 줍니다.

그리고 애초에 분류를 가능하게 하는 것도 에이전트입니다. 페이지를 하나 들여다보고 "이건 두고 갈 무더기"라고 판단하는 임포터는 앞으로도 나오지 않을 겁니다. 에이전트는 합니다 — 당신이 규칙을 알려 준다면요.

둘 다 돌아갈 때의 모습

최종 상태는 도구 하나가 아닙니다. 유지되는 경계선입니다:

  • Confluence는 위키의 일을 계속 맡습니다. 노트, 계획, 핸드북, Jira에 얽힌 모든 것. 누구에게도 "그만 쓰세요"라고 말할 필요가 없고, 그래서 이 경계선은 팀과 부딪혀도 살아남습니다.
  • Archyl은 아키텍처 레이어를 맡습니다. C4 모델과, 그것을 설명하는 문서, ADR, API 계약이 각각 속한 요소에 붙어 있습니다. 누군가 결제 container를 열면, 그것을 설명하는 문서와 그 뒤에 있는 ADR이 바로 거기 있습니다.
  • 둘 다 에이전트의 손이 닿는 곳에 있습니다. 당신의 MCP 클라이언트에는 두 서버가 모두 연결돼 있습니다. Archyl에 아키텍처를 물으면서, 같은 대화 안에서 위키의 기획 페이지를 검색할 수도 있습니다.

이게 다시 흐트러지지 않게 하는 규칙이 하나 있고, 한 번쯤 소리 내어 말해 둘 가치가 있습니다: 페이지가 시스템을 설명한다면, 그건 Archyl로 갑니다. 누군가 새 아키텍처 페이지를 Confluence에 쓰는 날, 당신은 200페이지 문제를 처음부터 다시 시작한 겁니다.

키를 만들고, 에이전트를 두 서버에 연결하고, 씹어 볼 섹션 하나를 던져 주세요. 전체 도구 목록은 MCP 서버 문서에 있습니다.

그리고 문서를 다 옮기고 나면, 같은 방법이 아키텍처 자체에도 통합니다: Structurizr 파일, Terraform 모듈, Mermaid 다이어그램, 그리고 코드베이스를 C4 모델로.