Confluence を離れる必要はありません。アーキテクチャを説明しているページだけを移し、残りはそのままにしておく。その移行は、Atlassian の MCP サーバーと Archyl の MCP サーバーを同じ AI エージェントにつなぐだけで済みます。

Confluence のアーキテクチャドキュメントを MCP で Archyl に移行する方法

毎週のように耳にする状況があります。あるチームが Archyl を導入し、システムを C4 でモデル化し、ADR と API コントラクトをリンクする——そして誰かが当然の質問を口にします。「Confluence にある200ページはどうするの？」

まず言っておくべきは、ベンダーの口からは誰も期待しない一言です。その大半は Confluence に残すべきです。 議事録、オンボーディングのチェックリスト、オンコールの runbook、前四半期の計画ドキュメント。そこは Confluence が得意な領域であり、Archyl が奪おうとしている場所ではありません。移すべきなのはアーキテクチャを説明している部分だけで、どのページがそれに当たるかを見極めることこそが、この作業のほとんどです。

かつて難しかったのは、移す作業そのものの手間でした。これまで、この質問への答えは「インポーターを待って」か「午後いっぱいコピペで」のどちらかでした。どちらもいただけません。しかしこの1年で状況が変わりました。この移行の両側が、いまや MCP を話すのです。

Atlassian は公式のリモート MCP サーバーを提供しており、OAuth と既存の権限のまま、Confluence と Jira をあらゆる AI エージェントに公開します。そして Archyl は、ドキュメント、フォルダ、ADR、C4 モデル全体——プラットフォームのすべてを、181のツールを備えた自前の MCP サーバーで公開しています。

その真ん中にエージェントを置けば、あなたが待っていたインポーターはプロンプトになります。

どのページを移し、どのページを残すか

これは何かを接続する前にやってください。私が使うテストはこうです。新しく入ったエンジニアがこのページを必要とするのは、システムの動き方を理解するためか、それとも最初の1週間を乗り切るためか。 前者はモデルの隣に置くべきもの。後者は wiki に置くべきものです。

これでスペースは4つの山に分かれます。

ドキュメントとして移す。 システムを説明するページ。決済サービスがどう作られているか、何と通信しているか、なぜその前段にキューがあるのか、リトライポリシーはどうなっているか。Archyl ではこれらを、説明対象の container やシステムに紐づけます。ページツリーの3クリック先ではなく、要素と一緒に目に入るようになります。
ADR として移す。 「なぜ X を選んだか」、RFC、トレードオフの検討メモ、決定で締めくくられたポストインシデントのページ。これらはドキュメントではなく意思決定であり、Archyl はそれを別のオブジェクトとして——ステータスを持ち、影響を与えた要素へのリンクを持つものとして扱います。
Confluence に残す。 議事録、スプリント計画、チームハンドブック、そして Jira マクロを軸に組み立てられた、実質はライブレポートのページ。これらを移しても得るものはなく、マクロを失うだけです。
削除する。 どのスペースにも、2年前に廃止されたシステムを説明するページが眠っています。移行は、それを誰かが最後にもう一度読む唯一の機会です。つまり、正直に削除できる唯一のチャンスでもあります。

先に仕分けをすること。それが、この作業をオールオアナッシングの移行にしないための鍵です。Confluence を空にするのではありません。そこから1つのレイヤーを抜き出すのです。

必要なもの

MCP クライアント。 ここでは Claude Code を使いますが、Cursor でも、MCP 対応のエージェントなら何でも同じように動きます。
Confluence アカウント。 移行したいスペースへの読み取りアクセスが必要です。
Archyl API キー。 Profile → API Keys で書き込みスコープ付きのキーを作成してください。

両方のサーバーを接続する

コマンドは2つだけ。まず 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"

セットアップはこれで全部です。エージェントはもう、あなたの wiki を読み、アーキテクチャワークスペースに 書き込む ことができます。

移行は「作る」のではなく「説明する」

実際に私たちのスペースで使ったものとほぼ同じ、本物のプロンプトがこちらです：

Confluence スペース "Platform Engineering" を、私の Archyl
プロジェクト "Aurora Commerce" に移行してください。

1. まずスペースのページツリーを一覧化して階層を見せてください —
   この時点では何もインポートしないこと。
2. ドキュメントフォルダで階層を再現し、各ページを markdown として
   インポートしてください。タイトルは維持し、フォーマットを整え、
   インポートしたページ間のリンクは Archyl 側のバージョンを指すように
   書き換えてください。
3. 意思決定を記録しているページ — 「なぜ X を選んだか」、RFC、
   トレードオフの検討メモ — は、通常のドキュメントではなく ADR に
   してください。ステータスは accepted に。元の日付はコンテキストの
   1行目に書いてください：「2024-03-11 に決定、Confluence から移行」。
4. 作成したものすべてのサマリーテーブルを見せてください。

次に何が起きるか見てください。エージェントは getConfluenceSpaces と getPagesInConfluenceSpace を呼んでスペースをマッピングし、getConfluencePageDescendants でツリーを辿り、getConfluencePage で各ページを取得します。Archyl 側では create_documentation_folder で構造をミラーリングし、各ページを markdown に変換して create_documentation で登録し、続けて move_documentation を呼んで正しいフォルダに収めます（ドキュメントを作ることと配置することは別々のツールです）。そしてここが私のお気に入りなのですが、意思決定の形をしたページは代わりに create_adr へ振り分けるのです。

この最後のステップは、見た目以上に重要です。どのチームの wiki にも、「ドキュメント」の下に化石化した意思決定の層が埋まっています。インポーターならそれをそのままコピーするだけ。エージェントはそれらを読み、「なぜ RabbitMQ をやめたのか」をアーキテクチャ上の意思決定として認識し、意思決定のあるべき場所に整理します——影響を与えた要素にリンクされ、C4 モデルの隣でクエリできる状態で。

ステップゼロの鉄則：一括実行の前にレビュー

プロンプトに「まず階層を見せて——この時点では何もインポートしないこと」と書いてあるのに気づきましたか？必ずそうしてください。どの wiki にもアーカイブセクションがあり、議事録の墓場があり、2019年から残る「TEST 消さないで」というページがあります。エージェントにツリーを提案させ、返信一発で剪定し（「Archive と Meeting Notes はスキップ」）、それから走らせましょう。

200ページというのが実際どういうことか

プロンプト1本と午後1回で終わる話ではありません。実際の進み方を左右するものが4つあり、それを先に知っているかどうかが、きれいに終わる移行と中途半端に終わる移行の分かれ目になります。

スペース単位ではなく、セクション単位で進めること。 エージェントはバッチ間でコンテキストを保ちます。そしてサマリーを読める大きさのバッチは、あなたが直せるバッチでもあります。10ページ、確認、次の10ページ。

Atlassian のサーバーはスロットリングします。しかも、想像するような数字ではありません。 公式 MCP サーバーの未解決 issue（2026年5月29日提出、Atlassian からの回答は現在も無し）では、数時間で合計200〜300回程度という控えめな総量にもかかわらず、並列呼び出しがおよそ20を超えたあたりで 429 が返ると報告されています。報告者の見立てでは、エラーは持続的な負荷ではなく同時実行のスパイクに連動しているとのこと。実際の上限が何であれ、指示は同じです。ページを扇状に一気に処理させるのではなく、1件ずつ順番に処理するようエージェントに伝えてください。

失敗したバッチをやり直すと重複します。 Archyl はドキュメントの slug に一意性を強制していません。10ページ中7ページ目でバッチが落ちたときに「もう一度やって」と言えば、最初の6ページが2部できあがります。リトライの前に list_documentation を呼び、すでに存在するものはスキップするようエージェントに頼んでください。

深いツリーは平坦化されます。 Archyl のドキュメントフォルダは3階層までです。それより深くネストした Confluence のツリーは Maximum folder nesting depth (3 levels) reached を返すので、40ページ目で気づくのではなく、始める前にどの階層をまとめるか決めておきましょう。

正直な制限事項

添付ファイルは今も自動では移動しません。ただし理由は反対側に移りました。 この記事の初出時、Archyl には添付ファイルの置き場所がありませんでした。今はあります。ドキュメントの添付ファイルは S3 互換オブジェクトストレージを背後に持つ機能として提供済みで、あなたの API キーを持つエージェントはファイルをドキュメントへ直接ポストできます。足りていないのは Confluence 側です。Atlassian のリモート MCP サーバーには添付ファイル用のツールが一切ありません——2026年8月時点で、サポートされているツールには Confluence 系の操作が12個並んでいますが、ファイルに触れるものは1つもなく、機能リクエストは2026年3月から開いたままです。つまりエージェントは MCP 経由でバイト列を取得できません。Confluence の REST API 経由でなら取得でき（GET /wiki/api/v2/pages/{id}/attachments がファイルごとに downloadLink を返します）、そのうえで1つずつ送り込めます：
```
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"
```
レスポンスには、そのままページに貼れる markdown スニペットが含まれています。ファイル形式は問わず、デフォルトで1件10 MB まで。ただし、これが何なのかははっきりさせておきましょう。これはスクリプトであり、2つ目の認証情報（Atlassian の API トークン。MCP サーバーが保持している OAuth セッションはあなたが借りられるものではないため）が要ります。たいていのスペースでは、本当に重要な数枚の図だけを Archyl のエディタから再アップロードするほうが、いまも速い答えです。
ADR には作成した当日の日付が付きます。 MCP でも REST でも、決定日を受け付ける API はありません。2023年に下した決定も、今日の日付が刻まれて着地します。上のプロンプトが元の日付をコンテキストに書き込ませているのはそのためです。10年分の意思決定を一気に移行する前に知っておく価値があります。
ドキュメントはモデルに自動ではリンクされません。 エージェントは ADR をシステムや container に1回の呼び出しで紐づけられます（link_adr_to_element）。ドキュメントに相当する MCP ツールはまだないため、インポートされたドキュメントはリンクされていない状態で届きます。UI でリンクするか、同じ API キーでエージェントに /api/v1/docs/{id}/links へ POST させてください。ここは飛ばさないこと。説明対象の container の隣にドキュメントが置かれていること——それこそが、そのドキュメントが wiki を出た理由のすべてなのですから。
複雑なマクロは劣化します。 Confluence の凝ったマクロ——Jira 課題テーブルや動的レポート——はプレーンテキストかリンクになります。コードブロック、テーブル、情報パネルはきれいに変換されます。
権限はあなたの権限です。 Atlassian MCP サーバーが公開するのは、あなたの OAuth ユーザーが読めるものだけ。これは、うれしい仕様です。

なぜ従来型のインポーターより優れているのか

一発勝負のインポーターが動かすのはバイト列です。エージェントが動かすのは意味です。移行しながら再構成し、意思決定を ADR に変え、壊れたフォーマットを直し、終わったら「何をスキップして、それはなぜか」に答えてくれます。

そして、仕分けを可能にするのもエージェントです。ページを1枚ずつ眺めて「これは置いていく山だ」と判断するインポーターなど、永遠に現れません。エージェントならやります——ルールさえ伝えれば。

両方が動いている状態はどう見えるか

最終形はツール1つではありません。保たれ続ける境界線です。

Confluence は wiki の仕事を持ち続ける。 ノート、計画、ハンドブック、Jira に紐づくものすべて。誰かに「もう使うな」と言う必要がない——だからこそ、この境界線はチームとの接触に耐えます。
Archyl はアーキテクチャのレイヤーを持つ。 C4 モデルと、それを説明するドキュメント、ADR、API コントラクトが、それぞれ属する要素に紐づいた状態で置かれます。誰かが決済の container を開けば、それを説明するドキュメントも、その背後にある ADR も、そこにあります。
どちらもエージェントから届く場所にある。 あなたの MCP クライアントには両方のサーバーが接続されています。Archyl にアーキテクチャを問い合わせながら、同じ会話の中で wiki の計画ページを検索することもできます。

これがまた元に戻ってしまわないためのルールが1つだけあり、一度は声に出して言っておく価値があります。システムを説明するページは、Archyl に置く。 誰かが新しいアーキテクチャのページを Confluence に書いた日、あなたは200ページ問題を最初からやり直したことになります。

キーを用意し、エージェントを両方のサーバーに向けて、まずは1セクション食べさせてみてください。ツールの完全な一覧は MCP サーバードキュメントにあります。

そしてドキュメントを移し終えたら、同じ手はアーキテクチャそのものにも効きます。Structurizr のファイル、Terraform のモジュール、Mermaid の図、そしてコードベースを、C4 モデルへ。

Confluence のアーキテクチャドキュメントを MCP で Archyl に移行する方法 - Archyl Blog