pr

このリポジトリの変更に対する GitHub プルリクエストを作成するとき、または既存の PR のタイトルや説明を編集するときに、このスキルを使用します。

gh CLI

このスキルでは、全体を通して gh CLI を使用します。gh コマンドが未インストールまたは未認証で失敗した場合は、ユーザーがコピーして貼り付けられるように、PR のタイトルと本文を明確に提示し、関連する GitHub URL も併記してください。

• 新規 PR：https://github.com/cloudflare/cloudflare-docs/compare/production...<branch>（git branch --show-current でブランチを確認します）
• 既存の PR の編集：https://github.com/cloudflare/cloudflare-docs/pull/<number> — 説明の Edit を選択するよう案内します。

既存の PR の編集

既存の PR の説明（またはタイトル）の更新や編集を依頼された場合は、以下のルールに厳密に従い、その後は作業を終了してください。以下の「新規 PR の作成」の手順には進まないでください。

1. 変更を加える前に、必ず現在の PR の説明を読むため、gh pr view <number> --json title,body を実行します。
2. 説明が空の場合は、新規 PR の本文として扱い、以下の「新規 PR の作成」セクションのテンプレートとガイドラインに従います。
3. 既存の形式に従います — 作成者が説明を特定の構成にしている場合は、その構成を維持してください。作成者が記述したセクションの再フォーマット、並べ替え、再構成はしないでください。
4. 依頼された箇所のみ変更します — 依頼を満たすために必要な最小限の編集にとどめてください。関係のない表現の改善、ほかの箇所の文法修正、概要の書き直し、依頼されていないチェックリスト項目の変更は行わないでください。
5. 編集を適用します。
   • タイトル：gh pr edit <number> --title "..."
   • 本文：Write ツールを使用して更新した本文を一時ファイルに書き込み、その後 gh pr edit <number> --body-file /tmp/pr-body.md を実行して、rm /tmp/pr-body.md でファイルを削除します。--body "..." は使用しないでください — シェルのクォート処理によって、バッククォートなどの Markdown 書式が壊れるためです。

ブランチにプッシュした後、オープン中の PR がある場合

オープン中の PR がすでにあるブランチに新しいコミットをプッシュした場合は、ブランチの変更内容を PR のタイトルと説明が引き続き正確に表しているか、必ず確認してください。新しいコミットによって、当初の説明にない変更が追加されることはよくあります。

1. ブランチに対するオープン中の PR を確認します：gh pr view --json number,title,body。
2. 最新のコミットだけでなく、ブランチ全体の差分（git diff production...HEAD --stat）とタイトルおよび本文を比較します。
3. 内容が不正確または不十分になっている場合は、「既存の PR の編集」のルールに従って更新します — 作成者の構成を維持し、新しい変更内容を反映するために必要な最小限の編集を行ってください。引き続き正確に説明できている場合は、変更しないでください。

プッシュ後は、この確認を先回りして行ってください。PR の内容を同期するよう別途依頼される必要はありません。

新規 PR の作成

新規 PR を作成する場合（または既存の PR の説明が空の場合）に限り、以下のステップ 1〜4 に従ってください。

ステップ 1 — コンテキストの収集

まず --stat を実行して、コンテキストを大量に消費せずに変更範囲を把握します。

git log --oneline production..HEAD
git diff production...HEAD --stat
git status

git status に未追跡ファイルまたは変更済みファイルが表示される場合は、これらのファイルをこの PR の一部としてコミットする必要があるか、ユーザーに確認してから作業を進めてください。黙って無視しないでください — 提出する変更に不可欠なファイルである可能性があります。

stat の出力に変更ファイルが約 20 個を超えて表示される場合は、差分全体を実行しないでください。代わりに、stat の出力から内容が不明な特定のファイルを読みます。変更ファイルが 20 個未満の場合は、差分全体を確認してかまいません。

git diff production...HEAD

ステップ 2 — PR のタイトルを作成

ブランチ：production

このリポジトリでは main ではなく、production をデフォルトブランチとして使用します。PR を作成する際は、必ず --base production を指定してください。他のリポジトリからのコントリビューターは main を想定することがよくありますが、これは意図的な設定です。

特に異なるベースをユーザーから指定されていない限り、最新の production コミットを基点にフィーチャーブランチを作成してください（git fetch origin を実行してから、origin/production を基点にブランチを作成します）。

形式

コンテンツの変更では、製品名を角括弧で囲む形式が標準です。

[Product] Short description

複数の製品にまたがる変更の場合：

[Product1, Product2] Short description

コンテンツ以外の変更（ツール、CI、設定、コンポーネント、ワーカーのコード、リポジトリの保守）では、代わりにConventional Commitsのプレフィックスを使用します。

chore: Short description
fix: Short description
feat: Short description

ファイルパスから製品名の角括弧を判断する

作成者に使用する製品名の角括弧を尋ねず、変更されたファイルパスから判断してください。

• src/content/docs/{slug}/ と src/content/partials/{slug}/ は製品に直接対応します。表示名を取得するには、src/content/docs/{slug}/index.mdx の title フィールドを確認し、製品名の角括弧には「Cloudflare 」のプレフィックスを取り除いた名前を使用します（例：タイトルが「Cloudflare Workers」なら [Workers]）。
• src/content/changelog/{slug}/ も同様に製品名の角括弧を使用し、[Changelog] は使用しません。複数の製品にわたる変更ログエントリーの追加または更新のみをPRが行う場合に限り、[Changelog] を使用します。
• 変更が4つ以上の製品にまたがる場合は、特に重要な2〜3製品を使用します。

ルール

• 角括弧内の製品名はタイトルケースにします：[Workers]、[AI Search]、[Zero Trust]
• 説明は約60文字未満にします
• 命令形を使用します：追加、修正、更新、削除、文書化、訂正
• 末尾にピリオドを付けません
• 角括弧内の一般的な略称：Durable Objectsは[DO]、[KV]、Zero Trustは[ZT]、[R2]、[D1]

タイトルの例（実際のPRより）

[AI Search] Add hybrid search and boosting configuration docs
[Hyperdrive, Workers VPC] Document TCP services, TLS cert verification
[Browser Rendering] Add Wrangler CLI commands documentation
[Billing] Restructure billing docs into intent-based sections
[DMARC Management] ELI5
[Client-side security] ELI5 updates
[DNS, Fundamentals] Onboarding review and add video
[Style Guide] Adding products frontmatter to all visible examples
[Workers] Document Durable Object Facets
[Changelog] CDP + WebMCP changelog entries

コンテンツの変更では、デフォルトとして[Product]形式を使用します。コンテンツ以外の変更では、Conventional Commitsのプレフィックスを使用してください。

ステップ3 — PR本文を書く

本文を書く前に、リポジトリからPRテンプレートを読み込んでください。

cat .github/pull_request_template.md

このファイルをPR本文の正確なベースとして使用してください。テンプレートをハードコードしたものには頼らず、変更されている可能性があるため、必ずディスクから最新の内容を読み込んでください。

各セクションの記入方法

概要

以下を含む簡潔な説明を記載します。

• 変更するドキュメントの種類（新規ページ、更新、修正、再構成、変更履歴の記載）
• 変更が必要な理由、または変更のきっかけ
• 関連する公開情報へのリンク：GitHub の issue、関連する PR、公開ドキュメントページなど

このリポジトリは公開されているオープンソースリポジトリです。PR のタイトル、説明、コメントには、非公開の Cloudflare 情報、シークレット、認証情報、環境変数の値、内部リソース（チケット、Wiki ページ、内部ドキュメント）の URL やタイトルを含めないでください。公開しても安全かどうか判断に迷う場合は、作業を中断してユーザーに確認してください。

事実に基づいて記載してください。チェックリストの項目を繰り返す必要はありません。小規模で焦点の絞られた PR なら、1～2 文で十分です。多くのファイルや複数の領域にまたがる大規模な PR では、説明を長めにしてかまいません。概要を読みやすくするために、文章の段落よりも表、リスト、コードブロックを活用してください。

良い例：

小規模で焦点の絞られた PR：

SCIM プロビジョニングにおける active 属性のマッピング動作について、注意書きを追加します。

https://github.com/cloudflare/cloudflare-docs/issues/1234 を修正します。

中規模の PR：

Access ポリシーのインデックスを更新し、新しいポリシーグループ UI を反映します。古くなったスクリーンショットを修正し、手順の順序を更新します。

複数の領域にまたがる大規模な PR：

課金ドキュメントを目的別のセクションに再構成し、ユーザーが料金と使用量に関する情報を見つけやすくします。

変更前	変更後
billing/usage.mdx	billing/usage-and-limits.mdx
billing/limits.mdx	（上記に統合）
billing/overview.mdx	billing/index.mdx

• 移動したページを参照するすべての内部リンクを更新
• 名前を変更したすべてのファイルにリダイレクトを追加

スクリーンショット（任意）

PR で視覚的な変更（新規ページ、ナビゲーションの再配置、UI 手順の更新、画像の変更など）がある場合を除き、このセクション全体を省略してください。スクリーンショットが不要な場合は、空のコメント用プレースホルダーを残さないでください。

PR に視覚的な変更がある場合は、このセクションを含め、担当者が PR をレビューに出す前に記入する必要があることがわかるように、`` コメントを付けてください。

ドキュメントのチェックリスト

各項目が該当するかどうかを確認してください。

1. 変更履歴の記載 — PR で Cloudflare 製品の新機能、機能強化、または注目すべき変更をドキュメント化する場合は必須です。修正、誤字の訂正、内部的な再構成、スタイルの更新の場合は、この項目を削除してください。

2. スタイルガイドの遵守 — src/content/ 以下のファイル、または作成したコンポーネントファイル（.mdx、.astro、.css）について差分を確認してください。該当するファイルが 1 つでも追加または変更されている場合に限り、この項目を残してください。PR がソースコード（.ts、.tsx、.js）、ツール、CI、設定ファイル、エージェントスキル、その他のコンテンツ以外のアセットのみを変更する場合は、これらのファイルが src/ 以下にある場合や、Markdown ファイルである場合でも、この項目を削除してください。

3. 大規模な変更に対する issue の作成 — PR で新しいページを追加する、セクションを再構成する、または既知の誤りに対処する場合は、この項目を残してください。小規模で焦点の絞られた変更の場合は削除してください。

4. 名前変更・移動したファイルのリダイレクト — .mdx ファイルの名前を変更、移動、または削除した場合は、この項目を残してください。ファイルの場所が変わっていない場合は削除してください。

本当に該当しない個々のチェックリスト項目は削除してください。該当しない項目を未チェックのまま残さないでください。レビュー担当者の確認を妨げます。ドキュメントのチェックリストのセクション全体を削除するのは、該当する項目が 1 つもない場合（CI またはツールのみの変更など）に限ってください。1 つでも該当する項目がある場合は、セクションを残し、該当しない項目だけを削除してください。

避けるべきこと

次のパターンはレビューの妨げとなり、PR が差し戻される原因になります。

• 文脈のない書き換え — PR で内容を大幅に変更または再構成する場合は、何を変更したのか、なぜ変更したのかを概要で説明する必要があります。説明のない差分では、レビュー担当者が意図を推測しなければなりません。
• 差分の逐次説明 — 何を変更したのかを行ごとに列挙して PR を要約しないでください（「42 行目の X を Y に変更」「見出しを A から B に更新」など）。機械的に何をしたかではなく、なぜ変更したのかを説明してください。
• 説明のない複数のプロダクト領域にまたがる変更 — PR で複数のプロダクト領域のファイルに手を加える場合は、それらの関連性を説明してください。理由の説明がなく、無関係に見える変更があると、レビュー担当者は懸念を抱きます。
• チェックリストの誤った削除 — 該当しない項目を個別に削除してください。関連する項目が一つもない場合を除き、チェックリスト全体を削除しないでください。レビュー担当者は、残った項目を使って網羅性をすばやく確認します。

ステップ 4 — PR を作成する

ステップ 3 で読み込んだテンプレートをもとに PR の本文を作成します。概要のプレースホルダーコメントを実際の概要に置き換え、該当しないチェックリスト項目を削除し、上記のガイダンスに従ってスクリーンショットのセクションを処理してください。

重要： 本文を --body "$BODY" や --body '...' で渡さないでください。シェルの引用符によって、バッククォートなどの Markdown 形式が崩れるためです。代わりに、本文を一時ファイルに書き込み、--body-file を使用してください。

# 1. Write the PR body to a temp file using the Write tool (not echo/cat)
# 2. Create the PR referencing that file
gh pr create --base production --draft --title "[Product] short description" --body-file /tmp/pr-body.md
# 3. Clean up
rm /tmp/pr-body.md

すべての PR は必ずドラフトとして作成してください。ほとんどのコントリビューターは、そのままレビューキューに進めるべきではありません。作成者が先にデプロイプレビューを確認し、問題がなければ PR をレビュー可能な状態にします。

出力

PR の URL を共有し、ドラフトとして作成されたことをユーザーに伝えてください。変更内容とデプロイプレビューに問題がないことを確認したうえで、納得できたらレビュー可能な状態にするよう案内してください。追加のコミットをプッシュしたり、レビュー担当者を指定したり、依頼されていないのに PR をさらに編集したりしないでください。ここからは人間に任せます。