docs-review

ドキュメントの変更を、正確性、スタイル、構成の観点からレビューします。

主なスタイルの参照先： .agents/references/style-guide.md — レビューの前にお読みください。MDX 構文、フロントマター、文体、書式、リンク、コードブロック、アドモニションに関する標準ルールが記載されています。各トピックをさらに詳しく確認する必要がある場合は、スタイルガイドの全文が src/content/docs/style-guide/ にあります。

提案する場合と編集する場合

判断基準

1. 明示的な指示を優先します。 ユーザーが「提案して」「提案のみ」「変更しないで」と指示した場合は、gh CLI を使って提案を投稿し、コミットはプッシュしません。「修正して」「対応して」「更新して」と指示した場合は、ファイルを直接編集してコミットします。
2. 実行者が異なる場合は提案します。 レビューを依頼した人が PR の作成者ではなく、修正の明示的な指示もない場合は、作成者が決定権を保てるように提案を投稿します。
3. 同一人物または不明な場合は、原則として修正します。 依頼者が PR の作成者である場合（または不明な場合）は、ファイルを直接編集することを基本とします。MDX 構文エラー、コードの破損、無効なフロントマター、誤ったコンポーネントの使用など、明らかな誤りは提案にとどめず、必ず修正します。

クイックリファレンス

指示	対応
「レビュー」「変更を提案」「提案を提示」	gh CLI で提案のみ投稿します — コミットはプッシュしません
「提案のみ」「変更しないで」	提案のみ投稿します — ファイルの編集やプッシュは行いません
「修正」「対応」「更新」	必ずファイルを直接編集し、変更をコミットします
「レビューして修正」	影響の小さい問題は直接修正し、影響の大きい変更は提案します
PR 作成者以外の人から依頼された場合	明示的に修正を指示されていない限り、提案を投稿します
PR 作成者から依頼された場合（または不明な場合）	直接修正します — 特に MDX 構文、コードのエラー、ビルドを妨げる問題

判断に迷った場合は、明らかな誤り（ビルドを妨げる問題、MDX 構文、誤ったインポート、コードの破損）は修正し、主観的な変更（表現、構成の見直し、スタイル上の好み）は提案します。

GitHub の提案を投稿する

gh api を使って GitHub REST API 経由で PR に行単位の提案を投稿します。提案のみを行う場合に変更を提案する唯一の方法です。

前提条件

投稿する前に、PR 番号と最新のコミット SHA を確認します。

PR_NUMBER=$(gh pr view --json number -q '.number')
COMMIT_SHA=$(gh pr view --json commits -q '.commits[-1].oid')

単一行の提案

差分内の 1 行を置き換えます。subject_type: "line" を指定します。

gh api repos/{owner}/{repo}/pulls/${PR_NUMBER}/comments \
  -f body='Tighten the phrasing:

```suggestion
Workers use an event-driven architecture. Each incoming request triggers a `fetch` handler.
```' \
  -f commit_id="${COMMIT_SHA}" \
  -f path="src/content/docs/workers/get-started/index.mdx" \
  -F line=42 \
  -f side="RIGHT" \
  -f subject_type="line"

複数行の提案

行の範囲を置き換えます。start_line と start_side を追加します。

gh api repos/{owner}/{repo}/pulls/${PR_NUMBER}/comments \
  -f body='Simplify this paragraph:

```suggestion
Bindings provide direct, in-process access to Cloudflare services like R2, KV, and D1.
They require no network hop, no authentication token, and add no extra latency.
```' \
  -f commit_id="${COMMIT_SHA}" \
  -f path="src/content/docs/workers/runtime-apis/bindings.mdx" \
  -F start_line=18 \
  -F line=22 \
  -f start_side="RIGHT" \
  -f side="RIGHT" \
  -f subject_type="line"

提案を含まないコメント

特定の置き換え箇所に対応しないフィードバックには、通常のレビューコメントを投稿します（提案ブロックは付けません）。

gh api repos/{owner}/{repo}/pulls/${PR_NUMBER}/comments \
  -f body="This claim needs a source. Link to the relevant API reference or remove it." \
  -f commit_id="${COMMIT_SHA}" \
  -f path="src/content/docs/workers/observability/index.mdx" \
  -F line=55 \
  -f side="RIGHT" \
  -f subject_type="line"

提案ブロックのルール

• suggestion のフェンス付きブロック内の内容は、対象の行をそのまま置き換えます。正しいインデントを使い、置き換え後のテキストをすべて含めてください。
• 単一行の場合：line に差分の行番号を指定します。start_line は指定しません。
• 複数行の場合：start_line に最初の行、line に置き換える範囲の最後の行を指定します。
• 常に side を "RIGHT"（差分の新しいファイル側）に設定します。
• 常に subject_type を "line" に設定します。
• 行番号は、古いファイル側ではなく、差分内の新しいファイル（右側）の行番号を指します。
• 数値フィールド（line、start_line）には -f ではなく -F を使い、gh が整数として送信するようにします。
• 提案ブロックより前の文章は 1 文にします。説明しすぎないでください。

レビューオブジェクトによるバッチ処理

3 件以上の提案を投稿する場合は、通知のスパムを避けるために、複数のコメントを含む単一のレビューを使用してください:

gh api repos/{owner}/{repo}/pulls/${PR_NUMBER}/reviews \
  --input - <<EOF
{
  "event": "COMMENT",
  "body": "A few suggestions for this PR.",
  "commit_id": "${COMMIT_SHA}",
  "comments": [
    {
      "path": "src/content/docs/workers/get-started/index.mdx",
      "line": 42,
      "side": "RIGHT",
      "body": "Tighten:\n\n\`\`\`suggestion\nWorkers use an event-driven model.\n\`\`\`"
    },
    {
      "path": "src/content/docs/workers/get-started/index.mdx",
      "line": 58,
      "side": "RIGHT",
      "body": "Fix link:\n\n\`\`\`suggestion\nFor more information, refer to [Bindings](/workers/runtime-apis/bindings/).\n\`\`\`"
    }
  ]
}
EOF

ヒアドキュメントで --input - を使用する場合、-f/-F フラグを渡さないでください。すべてのフィールドは JSON ボディに含めます。JSON には event、commit_id、body、comments を含める必要があります。

レビュープロセス

1. 完全な差分を読む

gh pr diff ${PR_NUMBER}

コンテキストを把握するためにファイル全体を読んでください。差分では間違って見えるコードも、コンテキストの中では正しい場合があります。変更がどのセクションに位置し、その前後に何があるかを確認してください。

2. ルールに照らして確認する

完全なルールについては .agents/references/style-guide.md を参照してください。クイックリファレンス:

ルール	詳細
エスケープされていない MDX 文字	本文中の {、}、<、> はエスケープするかバッククォートで囲む必要があります
コンポーネントのインポート	使用するすべてのコンポーネントは ~/components からインポートする必要があります
Workers のコード	素の js/ts フェンスではなく、TypeScriptExample を使用する必要があります
設定ブロック	TOML 入力を伴う WranglerConfig を使用する必要があります。compatibility_date には $today を使用してください
パッケージインストールコマンド	素の sh フェンスではなく、PackageManagers を使用する必要があります
コードブロックの言語	小文字で、サポートされているセットから選択してください — .agents/references/style-guide.md を参照してください
内部リンク	ルート相対パス、末尾スラッシュ、ファイル拡張子なし、完全な developers.cloudflare.com URL は使用しないでください
フロントマター	title と description は必須です。pcx_content_type は有効な値である必要があります
ライティングスタイル	.agents/references/style-guide.md を参照してください — 文体、短縮形、用語、見出しなどをカバーしています
コードの正確性	型チェック、API の使用方法、バインディングパターンについては、code-review スキルを読み込んでください
正確性	主張には根拠が必要です — 信頼できる情報源にリンクし、他のページで扱っている内容を再説明しないでください

3. 指摘すべき事項の評価

指摘すべき事項	指摘すべきでない事項
不正確な技術的内容	スタイルガイドにないスタイルの好み
壊れた MDX (ビルドが失敗します)	変更されていない行に既存の問題
誤った API の使用方法や型	コードが正しい場合の「もっとクリーンにできる」
コンポーネントの使用漏れ (TypeScriptExample、WranglerConfig)	証拠のない理論上の懸念
不正確または根拠のない主張	PR の範囲外の不足している機能
例におけるセキュリティや安全性の問題	意味を変えない軽微な文言の違い
スコープクリープ (PR の意図外のファイルへの変更)

4. 優先順位付け

重大度の順にレビューしてください:

1. ビルドを壊すもの — エスケープされていない MDX、インポートの欠落、無効なフロントマター
2. 不正確な内容 — 誤った API、誤った動作の説明、壊れた例
3. ベストプラクティスの欠如 — TypeScriptExample の不使用、ハードコードされた互換日、素のコードフェンス
4. スタイルと構造 — 見出しレベル、リンク形式、文章の品質

コンテンツレビューの原則

これらの原則は、このリポジトリで繰り返し寄せられたレビューのフィードバックをもとにしています。

• 信頼できる情報源にリンクする。 独自のドキュメントページがある概念を再度説明しないでください。代わりに、正式なページにリンクしてください。例：HTTP エラー 522 を本文中で説明せず、/support/troubleshooting/http-status-codes/ にリンクしてください。
• 主張の根拠を示す。 ドキュメントに「X はこのように動作する」と記載する場合は、その内容を検証してください。ソースコード、API ドキュメント、または設定スキーマを参照してください。未検証の主張にはフラグを付けてください。
• 推奨事項は明確に伝える。 「リモートの PostgreSQL データベースに接続する場合は、必ず Hyperdrive を使用してください」は、「直接接続するとレイテンシが増えるため、Hyperdrive の使用を検討してください」より適切です。
• 対象範囲を明確にする。 「バインディングを使うと、R2、KV、D1 などの Cloudflare サービスに直接アクセスできます」は、「バインディングを使うと、Cloudflare サービスに直接アクセスできます」より適切です。後者はすべてのサービスに対応するように受け取られるためです。
• コード例は安全にコピーできるものにする。 すべてのコードブロックは、開発者が本番環境に貼り付けるものとして扱ってください。例ではエラーを処理し、正しい型を使用し、最新のベストプラクティスに従ってください。
• 適切なコンポーネントを使用する。 Workers のコードには TypeScriptExample を使用してください。設定には、互換性の日付に $today を指定した WranglerConfig を使用してください。パッケージのインストールコマンドには PackageManagers を使用してください。
• 変更範囲を守る。 レビューで PR の範囲外にあるファイルの問題を見つけた場合は、その問題を指摘するにとどめ、同じ PR では修正しないでください。
• 主張する前に調査する。 API、フラグ、動作が正しいか不確かな場合は、指摘する前に型、スキーマ、またはドキュメントを調べてください。

出力形式

<response_format> あなたの回答は GitHub のコメントとして表示されます。レビュー担当者が読む各コメントには注意が必要です。簡潔かつ率直に書き、同じことを繰り返さないでください。

回答の構成

インラインの提案を投稿する場合は、提案ブロックの前のコメントを 1 文にしてください。説明しすぎないでください。

要約コメントを投稿する場合は、次の構成にしてください。

1. 1 行の結論 — 実施したこと（例：「2 件の問題を修正し、3 件の提案を投稿しました。」）または評価（例：「問題は見つかりませんでした。」「マージ前に修正が必要な問題が 2 件あります。」）。
2. 問題の一覧 — 対応が必要な項目のみを重大度別にまとめてください。重大度ラベルを使用してください：CRITICAL（ビルドの失敗、セキュリティ） | HIGH（内容の誤り、誤った API） | MEDIUM（コンポーネントの不足、古いパターン） | LOW（軽微なスタイル、表現）。各項目にファイルパスと行番号を含めてください。
3. 範囲外の注記（任意） — 今後修正すべき既存の問題を、最大 1～2 文で記載してください。

コメントは以上です。それ以外は追加しないでください。

省略する内容

• レビューに合格した項目は列挙しないでください。問題を 2 件見つけたレビューでは、問題 2 件のみを記載し、問題 2 件と問題のなかった項目 15 件を記載しないでください。
• 褒め言葉や PR の定性的な評価（「よく書かれています」「しっかりした PR です」「技術的に妥当です」）で始めないでください。結論から始めてください。
• 情報を繰り返さないでください。インラインの提案を投稿した場合、要約コメントでは各提案を再記述せず、「インラインの提案を 3 件投稿しました」のように簡潔に触れてください。
• 項目が 4 件未満の場合、表を作成しないでください。箇条書きを使用してください。
• 作業の経緯（「セクションごとに比較しました」「37 件の変更をすべて検証しました」など）を書かないでください。方法ではなく結論を述べてください。
• PR の変更内容を作者に言い直さないでください。作者は内容を把握しています。

フォローアップへの回答

同じスレッド内でフォローアップの依頼（例：「ビルドを修正してください」「レビューコメントに対応してください」）に回答する場合：

1. 変更内容を、ファイルパスと行番号を示して記載してください。
2. そこで止めてください。

レビュー全体をやり直さないでください。PR の要約を繰り返さないでください。以前のコメントのガイダンスを繰り返さないでください。スレッド内の各コメントには、新しい情報だけを記載してください。 </response_format>