confluence-reader

Confluence Reader

セルフホスト型Confluenceからページの取得・検索・探索を行うスキル。 依存: curl と jq（jqが無い場合はJSONを直接読み取る）

前提条件

環境変数 CONFLUENCE_PAT と CONFLUENCE_BASE_URL が設定されていること。

export CONFLUENCE_BASE_URL="https://confluence.example.com"
export CONFLUENCE_PAT="your-personal-access-token"

ベースURL: 環境変数 CONFLUENCE_BASE_URL で指定する（例: https://confluence.example.com）

共通のcurlオプション

すべてのAPIリクエストに以下のヘッダーとオプションを付与する:

curl -s -k \
  -H "Authorization: Bearer ${CONFLUENCE_PAT}" \
  -H "Accept: application/json" \
  "<API_URL>"

• -s: サイレントモード
• -k: 自己署名証明書を許可

---

パターン1: URL指定でページを取得する

トリガー

ユーザーが以下のようなプロンプトを送った場合:

URL https://confluence.example.com/spaces/DEV/pages/12345/ページタイトル を参照してください

手順

Step 1 — URLからページIDを抽出する:

URLパターン	抽出方法
/spaces/{spaceKey}/pages/{pageId}/{title}	/pages/ 直後の数字
/pages/viewpage.action?pageId={pageId}	pageId= の値

Step 2 — ページコンテンツを取得する:

curl -s -k \
  -H "Authorization: Bearer ${CONFLUENCE_PAT}" \
  -H "Accept: application/json" \
  "${CONFLUENCE_BASE_URL}/rest/api/content/{pageId}?expand=body.storage,version,space,ancestors"

Step 3 — レスポンスの主要フィールドを読み取る:

• title — ページタイトル
• body.storage.value — 本文（HTML形式、Confluenceマクロ含む）
• version.number — バージョン番号
• space.key / space.name — スペース情報
• ancestors[].title — 親ページのパンくずリスト

---

パターン2: キーワードでページを検索する

トリガー

以下のような状況で使用する:

• ユーザーが「Confluenceで○○について調べて」と依頼した場合
• 作業中に関連するドキュメントを探す必要がある場合
• パターン1で取得したページの内容だけでは情報が不足している場合

手順

Step 1 — CQL（Confluence Query Language）でページを検索する:

# タイトルで検索（あいまい検索）
curl -s -k \
  -H "Authorization: Bearer ${CONFLUENCE_PAT}" \
  -H "Accept: application/json" \
  "${CONFLUENCE_BASE_URL}/rest/api/content/search?cql=type=page+AND+title~\"検索ワード\"&limit=10&expand=version,space"

# タイトル＋本文のフルテキスト検索
curl -s -k \
  -H "Authorization: Bearer ${CONFLUENCE_PAT}" \
  -H "Accept: application/json" \
  "${CONFLUENCE_BASE_URL}/rest/api/content/search?cql=type=page+AND+text~\"検索ワード\"&limit=10&expand=version,space"

# 特定スペース内に絞って検索
curl -s -k \
  -H "Authorization: Bearer ${CONFLUENCE_PAT}" \
  -H "Accept: application/json" \
  "${CONFLUENCE_BASE_URL}/rest/api/content/search?cql=space=SPACEKEY+AND+type=page+AND+title~\"検索ワード\"&limit=10&expand=version,space"

Step 2 — 検索結果から関連ページを選択する:

レスポンスの results[] 配列から以下を確認:

• results[].id — ページID（詳細取得に使用）
• results[].title — ページタイトル
• results[].space.key — スペースキー
• results[].version.when — 最終更新日時
• results[]._links.webui — ブラウザ表示用URL

Step 3 — 関連性の高いページの詳細を取得する:

検索結果から目的に合うページのIDを使い、パターン1のStep 2と同じ方法で本文を取得する。

CQLの主なオペレータ

オペレータ	意味	例
=	完全一致	space=DEV
~	部分一致（あいまい）	title~"設計"
AND	AND条件	space=DEV AND title~"API"
OR	OR条件	title~"設計" OR title~"仕様"
> / <	日付比較	lastModified>"2025-01-01"

検索のコツ

• 日本語の検索ワードはURLエンコードが必要。curlは --data-urlencode を使うか、事前にエンコードする
• 検索ワードが長すぎると結果が返らないことがある。短いキーワードから試す
• ヒットしない場合は title~ を text~ に変えてフルテキスト検索を試す

---

パターン3: ページツリーを探索する

トリガー

以下のような状況で使用する:

• あるページの配下にある関連ページを一覧したい場合
• ドキュメント構造の全体像を把握したい場合
• 「このページの子ページも見て」と依頼された場合

手順

Step 1 — 子ページ一覧を取得する:

curl -s -k \
  -H "Authorization: Bearer ${CONFLUENCE_PAT}" \
  -H "Accept: application/json" \
  "${CONFLUENCE_BASE_URL}/rest/api/content/{pageId}/child/page?limit=100&expand=version"

Step 2 — 必要なページの詳細を取得する:

子ページ一覧の results[].id と results[].title を確認し、関連性の高いページをパターン1の方法で取得する。

---

パターン4: スペース一覧・スペース内ページ一覧

スペース一覧の取得

どのスペースがあるか分からない場合:

curl -s -k \
  -H "Authorization: Bearer ${CONFLUENCE_PAT}" \
  -H "Accept: application/json" \
  "${CONFLUENCE_BASE_URL}/rest/api/space?limit=50&expand=description.plain"

スペースのトップレベルページ一覧

curl -s -k \
  -H "Authorization: Bearer ${CONFLUENCE_PAT}" \
  -H "Accept: application/json" \
  "${CONFLUENCE_BASE_URL}/rest/api/space/SPACEKEY/content/page?depth=root&limit=50&expand=version"

---

自律的な情報収集の判断基準

Claude Codeが作業中にConfluence検索を行うべき状況:

1. ユーザーがプロジェクト固有の用語や名前を使った時 — その用語をキーワードに検索して文脈を補完する
2. コード実装中に仕様の詳細が不明な時 — 仕様書や設計ドキュメントを検索する
3. 取得したページ内に別のConfluenceページへのリンクがある時 — リンク先のページIDを抽出して追加取得する
4. 検索結果が多すぎる時 — スペースを絞る、日付で絞るなどCQL条件を追加して再検索する
5. 検索結果が0件の時 — キーワードを短くする、別の表現を試す、フルテキスト検索に切り替える

エラーハンドリング

HTTPステータス	原因	対処
401	認証失敗	CONFLUENCE_PAT の有効期限・正誤を確認
403	権限不足	該当ページ/スペースへのアクセス権を確認
404	ページ未発見	ページID・スペースキーの正誤を確認
400	CQL構文エラー	CQLの構文・エスケープを見直す

添付ファイル

ページの添付ファイル一覧が必要な場合:

curl -s -k \
  -H "Authorization: Bearer ${CONFLUENCE_PAT}" \
  -H "Accept: application/json" \
  "${CONFLUENCE_BASE_URL}/rest/api/content/{pageId}/child/attachment"

添付ファイルのダウンロード:

curl -s -k \
  -H "Authorization: Bearer ${CONFLUENCE_PAT}" \
  -O -J \
  "${CONFLUENCE_BASE_URL}{download_link}"

download_link は添付ファイル一覧の results[]._links.download から取得する。