pr-first-reader-check

name	pr-first-reader-check
description	PR が「その文脈を知らない初見のレビュアー（別チーム／入社直後）」に通じるかを点検したいときに使う。初見が詰まる原因は2つ。①意味が取れない（issue/PR にしか登場しない呼び名「Phase-2」「軸B」、PR に含まれない参照、未定義の略語、暗黙の前提「前回の議論どおり」等）と、②頭に入ってこない（一文が長い・主述が遠い・名詞化・回りくどい述語・結論が後ろ＝可読性）。語は分かるのに文がまどろっこしいときも対象。社内で定着しコードに実体がある用語（grep で定義に辿れる社内サービス名等）は対象外。トリガー例:「初見でレビューできる？」「PRのジャーゴンを消して」「文がまどろっこしい」「スッと頭に入らない」「onboarding した人が分かる？」。

PR 初見レビュアビリティ検査

PR を、**そのプロジェクトの文脈を一切知らない初見のレビュアー（別チーム / 入社直後）**が読んで理解できるかを検査する。

初見が詰まる原因は2つある。

1. 意味が取れない（文脈依存）— 知らない語・参照。「なにこれ、知らないんだけど」となる。
2. 頭に入ってこない（可読性）— 語は全部分かるのに、一文が長い・回りくどくて一読で取れない。「読めるけど、スッと入らない」となる。

両方を洗い出して直す。①だけ見て②を素通しすると、「用語は全部分かるのに、なぜか頭に入らない PR」が残る。

何のためのスキルか（位置づけ）

• codex review / code-review … 行レベルの正しさ
• pr-impact-review … ユーザー価値・プロダクト品質（出して良いか）
• 本スキル … 初見の人がこの PR だけ見て理解・レビューできるか（伝わるか）。①文脈②可読性の両面で見る

レビューは「読んで分かる」ことが前提。書き手には自明な語・参照でも、文脈を共有しない読み手には通じない。それが紛れ込むと、レビューは止まり、質問の往復が増える。語が分かっても、文が回りくどければ一読で取れず、読み手は同じ文を二度読む。どちらもレビューを遅くする。両方を未然に潰す。

いつ使うか

• PR を出す前（自分の PR の最終チェック）
• 他人の PR が「文脈依存で読みにくい」と感じたとき
• コメント・docstring・PR 説明をレビュー観点で点検したいとき

使わなくてよい場面: 文言が一切無い純粋なリネーム等。ただしコメント・説明が1行でもあるなら通す価値がある。

判断基準（これだけ覚える）

① 文脈:「今日入った人 / 別チームのレビュアーが、この PR だけを見て意味が取れるか？」 取れなければ直す対象。git log や社内 Wiki、過去の議論を知らないと分からない情報は、PR の中で自己完結させる。

② 可読性:「その文は、一読で頭に入るか？ 二度読みしないと取れない文はないか？」 二度読みが要るなら直す対象。語が全部分かっても、一文が長い・回りくどいと初見は読み返す。

code-intent-documentation.md（コードコメントは「履歴を知らない新メンバーが読んで意味が通るか」で判断）と同じ目線を、PR 全体（説明・コミット・コード）に広げたもの。

社内用語そのものは禁止しない — 「issue/PR にしか無い語」が対象

判定の軸は「社内かどうか」ではなく 「その語がコード／プロダクトに根ざしているか、それとも issue/PR の中だけの呼び名か」。

• ✅ 残してよい: 社内で定着しコードやプロダクトに実体がある用語（例: OrderRouter のように grep で定義に辿れるサービス名、テーブル/フィールド名、機能名）。レビュアーはコードを辿れば確認できる。
• ❌ 対象: issue / PR / 企画ドキュメントにしか登場しない呼び名（例: 「Phase-2」「軸B」のような企画上の分類ラベル・施策の通し番号）。コードにもプロダクトにも実体が無く、その企画文脈を知らないと指す対象が分からない。

検査対象（すべて見る）

1. PR タイトル
2. PR 説明（body）
3. コミットメッセージ
4. 差分内のコメント・docstring
5. 新規に導入した識別子・定数名・ラベル文言（ユーザーや他開発者の目に触れるもの）

gh pr view <PR番号> --json title,body
gh pr diff <PR番号>
DEFAULT_BRANCH="$(git remote show origin | sed -n 's/.*HEAD branch: //p')"
git log --format='%h %s%n%b' "origin/${DEFAULT_BRANCH}..HEAD"   # コミットメッセージ

① 何を「初見に通じない」とみなすか（文脈）

種別	例	なぜ詰まるか
issue/PR 限定の呼び名	「Phase-2」「軸B」「INC-1234 対応」のような企画上の分類・通し番号	コード/プロダクトに実体が無く、企画文脈を知らないと指す対象が不明
PR に含まれない参照	別リポのファイルパス（analytics/queries/foo.sql）、BI ツール（Redash/Metabase 等）のクエリ名だけ、リンクの無いチケット番号、社内ドキュメント名	レビュアーはそのファイル/クエリ/ページを開けない・存在を知らない
未定義の略語・専門用語	社内独自の略語、「結果整合性 (eventual consistency)」のような概念前提の用語	知識前提。説明なしだと読み飛ばすか調べる手間
暗黙の前提	「いつものフロー」「例のフラグ」「前回の議論どおり」	共有されていない前提への参照
内部テーブル/フィールド名・マスタ ID の生出し	is_premium_eligible 等のカラム名や、ラベルID 237・職種ID 13・代表ユーザー 8205 等の生 ID を説明なしで判断材料に使う	そのスキーマ／マスタを知らないと指す対象が分からない（必要なら1行の意味づけ or 凡例を添える）

逆に、消さなくてよいもの:

• コードに実体がある用語（上の「✅ 残してよい」と同じ。grep で定義に辿れるなら社内語でも残す）
• UI に出る機能名・プロダクト用語（ユーザーが画面で目にする正式名称）
• 一般的な技術用語（HTTP, debounce, TSV 等）
• ライブラリ/ツールの正式名（camelcaseKeys, vitest 等）。調べれば分かる

② 何を「頭に入らない」とみなすか（可読性）

語が全部分かっても、文が回りくどいと初見は二度読みする。見出し・表・箇条書きが整っていても、つまずくのは個々の文。語のチェックとは別に、文単位で次を見る。

判断はシンプル。一読で取れたか。取れなければ、下のどれかに当てはまる。

症状	直す型	before → after
一文に主張が2つ以上（原因と結果、条件と結論を1文に詰める）	一文一義。文を分ける（日本語は1文 50〜60 字が目安）	「A を無視していたため、B にも届かない C を母集団に含めた予測値を返していた」→「A を見ていなかった。そのため B にも届かない C まで母集団に入り、予測値が高く出ていた」
主語と述語が遠い・ねじれる／修飾が入れ子（「X は〜という〜を〜した〜を返す」、主語に対し述語が噛み合わない）	主語の直後に述語を置く。長い修飾節は前の文に切り出す。主述を噛み合わせる	主述の間に修飾が 40 字以上（目安）挟まる、または主語と述語がねじれる → 修飾を別の文にほどき、主語→述語を直結させる
名詞化（「〜の実施」「〜化」「突き合わせを行う」）	動詞で書く。動作主＋動詞の能動形に	「年収の算出を行う」→「年収を算出する」／「母集団の絞り込みがかかる」→「母集団を絞る」
回りくどい述語（「〜する方向で動く」「〜という形になる」「〜となっている」）	言い切る	「予測値が下がる方向で動く」→「予測値が下がる」
結論が後ろ（前置き・理由を先に積んでから結論）	主点を先頭に（BLUF）。段落も箇条書きの各項目も結論から	「〜を踏まえ、〜した結果、X とした」→「X にした。理由は〜」
二重否定・多義・曖昧	肯定形・具体値に	「対応しないわけではない」→「一部だけ対応する」／「しばらく後」→「約 5 分後」
冗長・重複	余分な語を削る	「必ず必要」→「必要」／「まず、はじめに」→「まず」

よくある誤解: 「構造（見出し・表）が整っている＝読みやすい」ではない。章立てが良くても一文一文が長ければ詰まる。その場合、直すのは章立てではなく文。

直し方

① 文脈の指摘 には次の3択から選ぶ:

1. 平易語に置換 — 「Phase-2 トレンド」→「<その施策で何を見ているかを平易に書く（例: 新規プラン契約者の利用傾向）>」
2. 自己完結させる（リンク or 1行の定義）— 別リポのパス → レビュアーが開ける URL（BI ツールのクエリ URL 等）／チケット番号 → タイトル or 1行要約を添える／略語 → 初出で展開
3. 削除 — そもそもコードに無いものを指す説明（読者が「どこ？」となるだけ）は消す。制約はテストやコードで担保し、説明に頼らない

② 可読性の指摘 は、上の「② 何を頭に入らないとみなすか」表の「直す型」に従う（文を分ける／主述を近づける／動詞で書く／言い切る／結論を先に／削る）。意味は変えず、言い回しだけ直すこと。

出力フォーマット

## PR 初見レビュアビリティ検査: [PRタイトル]

### 判定: 【初見OK / 要修正 N件】（文脈 N件 / 可読性 N件）

### 指摘

| 箇所          | 文言                                               | 軸     | 種別                    | なぜ詰まるか      | 直し方                       |
| ------------- | -------------------------------------------------- | ------ | ----------------------- | ----------------- | ---------------------------- |
| PRタイトル    | 「(Phase-2)」                                      | 文脈   | 社内施策名              | 何の Phase か不明 | 削除                         |
| service.py:10 | `analytics/queries/v2.sql`                         | 文脈   | PR外参照                | 別リポで開けない  | BI ツールのクエリ URL に置換 |
| 説明:なぜ     | 「〜を無視していたため、〜を含めた値を返していた」 | 可読性 | 一文に2主張・主述が遠い | 一読で取れない    | 2文に分ける                  |
| 説明:影響     | 「予測値が下がる方向で動く」                       | 可読性 | 回りくどい述語          | 言い切っていない  | 「予測値が下がる」           |

### 直した結果（修正する場合）

- [箇所] before → after

やりがちな失敗

失敗	どうするか
コードコメントだけ見て PR 説明・コミットメッセージを見落とす	タイトル・body・commit・コメントの全部を対象にする
プロダクト用語まで「ジャーゴン」と消す	UI に出る正式名・一般技術用語は残す。消すのは「文脈を知らないと通じない」もの
「PR 外参照」をリンク化せず放置	レビュアーが開けるか（別リポ/非公開でないか）で判断。開けないなら URL 化 or 自己完結
用語を消すだけで担保も消す	用語（例: 結果整合性）を消すなら、その意図はテスト/コード/平易な説明で残す
語（①文脈）だけ見て、文の長さ・回りくどさ（②可読性）を素通しする	語が全部分かっても、一読で取れなければ要修正。両軸を見る
「構造が整っているから読みやすい」と判断	見出し・表が良くても個々の文が長ければ詰まる。文単位で見る
可読性の修正で意味まで変える	言い回しだけ直す。数値・条件・結論は before と一致させる
指摘を出して直さない	出す前チェックなら、その場で直して before→after を示す

Red Flags（自分がサボっているサイン）

• PR 説明しか見ていない（コミットメッセージ・コメントに同じ語が残る）
• 「自分は分かるから大丈夫」と判断 → 基準は初見の人。自分が分かるかではない
• 社内コードネームを「説明を足せばOK」で残す → 多くは平易語に置換した方が速く確実
• 用語の指摘だけで終える → 一文の長さ・名詞化・回りくどい述語（②可読性）を見ていない
• 自分が一度で読めたから OK と判断 → 書き手は文脈を持つので読める。基準は「初見が一読で取れるか」
• 指摘ゼロで終える → コメント・説明が少しでもあれば、たいてい1つは文脈依存か回りくどさが混じる

---

関連ルール

成果物を書くときは @.claude/rules/conclusion-only-output.md も適用する: 結論だけを書き、そこに至る過程・対比・自己言及（どう調べたか／当初こう考えたが訂正した／別ツールはこう言ったが覆った）を本文に残さない。