docs-review

ドキュメントレビュースキル

@./../_shared/metabase-style-guide.md

レビューモードの検出

重要: レビューを開始する前に、どちらのモードを使用するかを判断してください:

1. PR レビューモード: mcp__github__create_pending_pull_request_review ツールが利用可能な場合、GitHub PR をレビューしています

   • 保留中レビューのワークフローを使用して、すべての指摘を 1 つのまとまったレビューとして投稿します
   • 以下の「PR レビューモードのフォーマット」にあるワークフローの手順に従ってください

2. ローカルレビューモード: MCP ツールが利用できない場合、会話内に指摘を出力します

   • すべての指摘を番号付きの Markdown リストでフォーマットします(以下の「フィードバックのフォーマット」で説明するとおり)

レビュープロセス

1. レビューモードを検出する - mcp__github__create_pending_pull_request_review が利用可能かどうかを確認します
2. 変更内容を一度通して読み、意図を理解します
3. スタイルガイドに違反している指摘、または読みやすさに大きく影響する指摘をすべて確認します
4. 言及する価値のある指摘だけを取り上げます - 読者に実質的な違いをもたらさない場合はスキップしてください
5. 必須: すべてのフィードバックに連番を付ける - Issue 1 から始めて、見つかった指摘ごとに番号を増やします

レビューチェックリスト

diff を一通り確認して、以下の指摘を探します:

トーンと語調:

• 硬すぎる/ビジネス的な言葉遣い(「使用する」ではなく「使う」、「提供物」など)
• 「people」や「companies」ではなく「users」を使用している
• 過剰な感嘆符や、明るすぎるトーン
• 読者に実際に見せるのではなく、何かがすごいとだけ伝えている

構成と明瞭さ:

• 重要な情報が先頭ではなく埋もれている
• ほとんど価値のない冗長な文章
• 明確な目的のない段落
• 要点が伝わらない曖昧な見出し
• 「何をするか」を伝える前に「なぜ」を説明している手順
• タスクを「簡単」または「シンプル」と表現している

リンクと参照:

• 説明的なテキストではなく「ここ」という単語にリンクしている
• 見出し内のリンク(見出し全体がリンクの場合を除く)

フォーマット:

• 「and」の代わりとしてのアンパサンド(固有名詞を除く)
• 一貫性のないリストのフォーマット

コードと例:

• 動作しない、またはエラーになるコード例
• 実行順序になっていないコマンド
• 対象を絞った UI 要素ではなく全幅のスクリーンショット
• 過剰または不要な画像

文の構成:

• 新しい用語を導入する際の代名詞の使いすぎ

クイックスキャン表

パターン	指摘
we can do X, our feature	「Metabase」または「it」にすべき
click here, read more here	説明的なリンクテキストが必要
easy, simple, just	見下すような修飾語は削除する
users	可能であれば「people」または「companies」にすべき

フィードバックのフォーマット

必須要件: すべての指摘に Issue 1 から始まる連番を必ず付けてください。

この番号付きフォーマットは変更できません。これにより、ユーザーは特定の指摘を効率的に参照し(例:「Issue 1、3、5 を修正してください」)、どのフィードバックが対応済みかを追跡できます。

ローカルレビューモードのフォーマット

会話内に指摘を出力する場合(ローカルモード)、次のフォーマットを使用します:

## Issues

**Issue 1: [Brief title]**
Line X: Succinct description of the issue
[code or example]
Suggested fix or succinct explanation

**Issue 2: [Brief title]**
Line Y: Description of the issue
Suggested fix or explanation

**Issue 3: [Brief title]**
...

例:

Issue 1: 硬いトーン 15 行目: もっと会話的にできます。たとえば「You cannot...」ではなく「You can't...」を検討してください。

Issue 2: 曖昧な見出し 8 行目: 見出しをより具体的にできます。要点を直接示してみてください:「Upgrade process」ではなく「Run migrations before upgrading」

PR レビューモードの形式

GitHub に投稿する場合（PR モード）、保留中のレビューワークフローを使用します。

ワークフローの手順:

1. レビューを開始する: mcp__github__create_pending_pull_request_review を使用して保留中のレビューを開始します

   • これにより、送信されるまで表示されない下書きレビューが作成されます

2. diff 情報を取得する: mcp__github__get_pull_request_diff を使用して、コードの変更と行番号を把握します

   • これは、コメントに正しいファイルパスと行番号を特定するのに役立ちます

3. すべての問題を特定する: すべての変更を読み、言及する価値のあるすべての問題を特定します

   • コメントを投稿する前に、すべての問題を収集します
   • 順番に番号を付けます（Issue 1、Issue 2、Issue 3 など）

4. レビューコメントを追加する: 各問題に対して mcp__github__add_pull_request_review_comment_to_pending_review を使用します

   • 重要: 並列の複数のツール呼び出しを使用して、すべてのコメントを 1 つのレスポンスで投稿します
   • 各コメントは、diff から特定のファイルパスと行番号を参照する必要があります
   • 各コメント本文の先頭に **Issue N: [Brief title]** を付けます
   • 説明と推奨される修正を含めます

5. レビューを送信する: mcp__github__submit_pending_pull_request_review を使用して、すべてのコメントを一度に公開します

   • イベントタイプに "COMMENT"（"REQUEST_CHANGES" ではない）を使用して、非ブロッキングにします
   • 本文メッセージを含めないでください - 本文は空にするか、完全に省略します
   • すべてのコメントは、1 つのまとまったレビューとして一緒に表示されます

コメント形式の例:

**Issue 1: Formal tone**

This could be more conversational. Consider: "You can't..." instead of "You cannot..."

重要:

• 各問題は、保留中のレビューに添付される独自のレビューコメントになります
• すべてのコメントに順番に番号を付けます（Issue 1、Issue 2、Issue 3 など）
• コメント本文は常に **Issue N: [Brief title]** で始めます
• すべてのコメントを 1 つのレスポンスで並列に追加する必要があります - 別々のレスポンスで次々に追加しないでください
• 会話に要約メッセージを出力しないでください - GitHub のレビューコメントのみを投稿します
• レビューを送信するときは、PR を要約テキストで煩雑にしないよう、body パラメータを含めないでください（または空のままにしてください）
• 送信すると、レビューは複数のコメントを含む 1 つのレビューとして表示されます

最終チェック

1. 対処しても読者に実質的な違いをもたらさない問題は、評価から除外します。作成者が修正する時間を割く価値のある問題のみを指摘します。
2. すべての問題が Issue 1 から順番に、番号の抜けなく付けられていることを確認します。
3. 形式が正確に一致することを確認します: **Issue N: [Brief title]**（N は問題番号）。
4. PR モードの場合: 各問題が個別の GitHub コメントとして投稿されたこと（会話に出力されていないこと）を確認します。