Quick Doc Review

/doc-review は文書の目的・対象読者・可視化提案まで含めた質的なレビューで、全文を読む subagent を起動するため時間がかかる。本スキルはそれとは別物で、判断ログ上で繰り返し指摘されてきた具体項目だけを、メインの会話内で直接・高速にチェックし、その場で修正する。網羅的な品質判定はしない。

例外は項目9（冗長な記述）だけで、ここは差分だけを渡す軽い subagent（deletion-advocate-agent）を起動する。削除の判定を書き手が自分で下すと必ず「要る」と結論するので、この項目だけは自問では成立しない。

quick-issue と同様に「本格フローの軽量版」シリーズの1つ。

[!NOTE]
（AI・必須） 判定基準は本来 documentation-policy.md・documentation-policy-for-humans.md と、その書き方を定める Rule .claude/rules/document-writing.md・.claude/rules/document-writing-for-humans.md が正（SSOT）だが、本スキルは速度を優先し、そこから具体的な判定基準を書き下して自己完結させている（DRYより速度を優先した意図的な例外）。これらが改訂されたときは、このチェック項目も追従して見直すこと。要件定義書（docs/requirements.md と手本の samples/docs/requirements.md。以下のチェック項目で docs/requirements.md と書くときは手本も含む）だけは requirements-doc-policy.md が一部の規約を上書きするため、該当するチェック項目の判定基準に例外として書き下してある。設計書（docs/design/**/*.md と手本の samples/docs/design/**/*.md）は design-doc-policy.md と Rule .claude/rules/design-doc.md が固有の規約を足すため、対象を設計書のみと明記したチェック項目に書き下してある。いずれのポリシー・Rule の改訂時も同じく追従すること。

対象

1. 対象ファイル：引数にファイルパスがあればそれを対象にする。無ければ、直前のターンで自分がEdit/Writeしたファイルを対象にする。
2. チェック範囲：git diff HEAD -- <対象ファイル> で差分を取得する。差分があれば差分部分だけをチェック対象にする（速度優先のデフォルト）。差分が無ければ（コミット済みで変更がない、または新規追加ファイルで差分が出ない等）、ファイル全文を対象にする。
3. 決着済みの例外：チェックを始める前に grep <対象ファイルのパス> docs/reference/doc-rule-exceptions.md を実行する。該当行があれば、その行が挙げる規定を指摘しない。ただし行の「判断」列に書かれた外形的な事実（列数・行数など）が現物と違っていれば、決着は当てはまらないので通常どおり指摘する。
4. 人間向け文書か：docs/policy/documentation-policy-for-humans.md の frontmatter applies-to に対象ファイルのパスが当たるかを見る。当たるファイルを以下「人間向け文書」と呼ぶ。当たらなければ、「人間向け文書のみ」と書いた項目・部分を N/A と報告する。

チェック項目・判定基準

#	項目	判定基準
1	TL;DRが1決定1行・3行以内か	対象は人間向け文書のみ。文書冒頭に TL;DR／「決定事項」の要約ブロックがある場合、決定1件1行の箇条書きになっていなければNG（1段落べた書きは行数に関わらずNG）。本文（見出し行を除く）が4行以上あってもNG。決定を含まない事実列挙の文書（用語集・API一覧等）はTL;DR自体が無くてよく、対象外
2	書き手の事情が本文に書かれていないか	次の3種が本文にあればNG（人間の明示指示がある場合を除く）。①進捗・経過・状態：「整備中」「整備途上」「今後」「暫定」「TODO」「予定」「これから」「旧仕様では」等の語。色分け・バッジ・ハイライトなど**「今回追加した箇所」を示す視覚表現も含む。未完了作業はIssue番号の参照に置き換える。語があるだけではNGにせず、その語が指しているのが「この文書・この作業の状態」か「対象システムの振る舞い」かで判定する——後者（例：「今後追加されるジョブもこの経路を通る」）と、Issue番号を添えた TODO(#31) はNGにしない ②記載・作図の判断**：「省略理由：〜のため」「この表を図にしない理由」「この図種を選んだ理由」「〜も行にしているのは〜だからである」など、何をどう書くか決めた経緯。ユーザーへの回答に書くもので本文からは消す。②か「本文に書くべき設計判断の理由」かは、その理由が答えているのは「対象がどうあるべきか」（本文に書く）か、「この文書にどう書くか」（②なので消す）かで判定する。「ここでは見ない／Xが見る」という担当範囲の宣言は前者に入り、NGにしない ③文書の構成説明：「図＝流れ、下表＝相手」「〜で対応づけている」「上の表は〜を示す」「以下では〜を説明する」など、図表を見れば分かる役割分担・対応関係・読み方の案内。逃がし先はなく消す。要件定義書（docs/requirements.md）も例外にしない
3	件数・列挙を転記していないか	「◯つの」「N個の」等の個数表現が、直後ではなく離れた場所・別文書にある列挙を指しているとき、その個数や列挙内容をハードコードしていればNG。個数を書かず、参照（リンクや呼称）に置き換える
4	文書内DRYが崩れていないか	同一ファイル内で同じ主張・説明が2箇所以上繰り返されていればNG（calloutが直前の本文を再掲するケースを含む）。文言が違っても、置かれた役割が違っても（方針の宣言とチェックリスト、概要の表と本文など）、同じ規定が2箇所にあればNG。ただし冒頭のTL;DR・決定事項の要約ブロックと、末尾のまとめ節との間の要点再掲だけは意図的な例外として許容する。要件定義書（docs/requirements.md）だけは別の例外があり、同じ事実を表・図・文章で重ねて見せる重複は指摘しない（凍結する文書なので、保守より読み手の理解が勝つ）。ただし同じ事実を離れた場所に別々に書く重複は要件定義書でもNG（書いた時点で食い違い、どちらが正か読めなくなる）
5	構造が文章のまま埋もれていないか・2列以下の表がないか	次のいずれかが箇条書き・表・図にならず文章のままならNG：①文の中に、動詞を含む項目を3つ以上並べた列挙（「A を作り、B を分析し、C を削除する」→箇条書き。「図・表・箇条書き」のような名詞の並びはNGにしない）②1項目が名前のほかに2つ以上の情報を持つ並び（3列以上の表）③複数要素が関係し合う説明（関係図）④複数の主体が時間順にやり取りする流れ（シーケンス図）⑤階層構造（ツリー図）⑥状態遷移（状態遷移図）⑦上のどれにも当てはまらない分岐・合流（フローチャート）。単一の主張・理由はNGにしない。加えて、2列以下の表があればNG——名前と説明なら - **名前**：説明 の用語リスト、名前と決まった値（必須/任意、✅/❌、数値など）なら値ごとにまとめた箇条書き、悪い例と良い例の対なら - ❌ 悪い例 → ✅ 良い例 に直す。「2項目の対比だから」「表の方が整って見える」は表のまま残す理由にしない。図種の選び直しは次項で見る。①②と2列以下の表は人間向け文書のみが対象（③〜⑦は全文書）。例外：要件定義書（docs/requirements.md）は2列の表をNGにしない
6	図が過剰・図種が不適切でないか	差分に図があるとき、逆変換テストを当てる：図のノード関係が分岐・合流・ループ・並行・多対多・階層・状態遷移のいずれも含まない一直線（A→B→C）の構成なら、表・箇条書きに戻してNGとする（戻す先を明示して指摘する）。上記のいずれかを含む図はNGにしない。加えて図種も見る：フローチャートは他のどの形にも当てはまらないときだけ選んでよく、シーケンス図・状態遷移図・ツリー図等が合う情報をフローチャートで描いていればNG。要件定義書（docs/requirements.md）の機能要件だけは例外で、逆変換テストを当てない（表で掴める内容でも図を必ず添える決まりのため）
7	見出しに連番を振っていないか	## 1. 目的 のような番号付き見出しがあればNG（番号なしに直す）。§3 [原則2](x.md) のように他文書の内部番号を名指しした参照もNG（見出し名・アンカーリンクに直す）。例外は実行順序そのものが情報である手順書（runbook・セットアップ手順・移行手順）。順序に意味がない列挙は手順書の中でもNG。もう1つの例外は要件定義書（docs/requirements.md）の非機能要件の分類で、A. 可用性 のような記号は許容する（IPA「非機能要求グレード」の大項目IDをそのまま借りたもので、こちらの都合で節が増減しない）
8	calloutに宛先・強制力ラベルがあるか	行動を促す callout（[!IMPORTANT] [!TIP] [!WARNING] 等）の本文が **（AI・必須）** のような宛先・強制力ラベルで始まっていなければNG。宛先は AI / 人間、強制力は 必須（MUST） / 推奨（SHOULD）。両対象なら **（AI・必須 / 人間にも）**（人間にも同じ強制力で効く）。行動を促さない補足・前提（[!NOTE] 等）はラベル不要で対象外
9	冗長な記述がないか	候補を自分で挙げない。 削除テストは deletion-advocate-agent に投げ、返った候補を捌く（手順は「項目9の実行手順」）。3点セットが揃った候補を全件報告したうえで、消すかは呼び出し元が判断する。ただし「この内容を将来変更するとき、何箇所を直す必要があるか」だけは自分で問い、1箇所で済まないならハードコード・重複の兆候としてNG。要件定義書（docs/requirements.md）だけは例外で、表・図・文章にまたがる重複を候補にさせない（凍結する文書なので重ねて見せてよい）
10	硬い言い回しになっていないか	中学生テスト：専門用語を別の記号に置き換えたとき、残りの文の構造と論理を中学生が一度で追えるか。追えなければNG。音読テスト：声に出して言わない硬い言い回し（「〜を企図する」等）があればNG。専門用語そのものは数に入れない。直すのは言い回しと構造：漢語の硬い動詞を和語に（「担保する」→「保つ」）、名詞化をほどく（「変更への耐性を担保する」→「変更に強くする」）、一文の主語・述語は1組まで
11	他文書リンクが必要最低限か	他文書リンクを1本ずつリンク削除テストにかける：「消しても読者はこの文書だけで判断・行動できるか」。できなければNG（結論を1〜2文で転記してから、必要ならリンクを残す）。加えて次もNG：①同一リンク先を1文書で2回以上張っている ②「詳細はXを参照」だけで結論を本文に書いていない ③読者が開けるとは限らない場所（テンプレートリポジトリなど）を参照先にしている（リンク先の内部番号を名指しした参照は「見出しに連番を振っていないか」で見る）。ハブ文書（design-hub / policy-hub）と docs/reference/ の索引は対象外
12	表に詳細が詰め込まれていないか	対象は人間向け文書のみ。差分にある表を行ごとに見る。①1セルの文字数：4列以下は上限なし／5〜6列は150文字／7列以上は80文字を超えていればNG。半角・全角を区別せず1文字と数える ②列数：7列以上なら、列を減らす3つの手（表を分ける／列をまとめる／列の取りうる値を縛る）のどれかが当たらないかを見て、当たるのに使われていなければNG。どれも当たらないなら7列以上のままでよい。直し方は超えた理由で分ける——2つ以上の項目が入っているセルは行を分ける、1つの項目の必須要素が並ぶセルは表から外して表の直下へ移す（移した先の形式は次項が決める）
13	トグル化すべき箇所が本文のまま並んでいないか	対象は人間向け文書のみ。次のどれかに当たる箇所が <details> になっていなければNG：①表・一覧の項目に1対1で対応する詳細が3つ以上並ぶ（並んだ全部を畳む。表・一覧の直下に置いた項目ごとの説明・理由・内訳、機能ごとの補助図などが該当）②Mermaid 以外のコードブロック・出力例が20行を超える③図の直下に、その図の設計意図を書いている（設計書の図直下トグル）。逆に、これらに当たらない箇所を畳んでいてもNG（畳みすぎ）。要件定義書（docs/requirements.md）は①の件数条件の例外——.claude/rule-bodies/requirements-doc.md が表ごとに名指しした詳細（本文型はその表の全行、補足型は列の記述だけでは読み取れない行）は、1件でも畳んでよく、畳みすぎと判定しない。対象外：見出し（#### 等）を持つ節（トグルに見出しは入れられない）。畳んだ内容にはトグル削除テストを当てる——畳んだ部分を伏せて本文だけを読み、読者が判断・行動できなければNG（結論・規定を畳んでいる。その理由・根拠は畳んでよい）。記法もNG判定に含む：<details> 直後と </details> 直前に空行が無い／中に見出しがある／summary が「詳細」「補足」など中身の分からない語（ID 名前・項目名にする。ただし設計書の図直下トグルは「設計意図」で固定）／対応する表・一覧と並び順が違う
14	基本方針が考え方1文＋方針の箇条書きで書かれているか	対象は設計書（docs/design/**/*.md と samples/docs/design/**/*.md。ただし docs/design/interface-specification.md は対象外）のみ。以降の項目で「対象は設計書のみ」と書いたものはすべてこの範囲を指す。冒頭に「基本方針」の節が無ければNG。あっても①この設計が取る考え方を1文で言い切っていない ②その考え方から出てくる方針の箇条書きが無い ③方針を表にしている のいずれかならNG（理由は添えず冒頭の1文が兼ねる。理由の列を足すと個々の判断が冒頭に集まる）。方針を ### の小節に分けている場合は小節ごとに①②を判定し、節全体で1文・1箇条書きであることは求めない。TL;DR を置いていてもNG（基本方針が兼ねるため設計書にTL;DRは置かない）
15	個々の設計判断が名指しした ## に立っているか	対象は設計書のみ。①「重要なポイント」のような、中身を名指ししない傘セクションがあればNG（見出しをその判断の中身に変えるか、基本方針・前提と制約へ移す）②1セクションに2つ以上の決定が入っていればNG（見出し1行で言い切れず「〜と〜」で並ぶもの。例：「AIジョブのセキュリティ」に権限分離・コマンド限定・ログ制限を全部入れる）③セクションの中身が構成図の描き直し（同じノード・同じ関係）になっていればNG（書くのは構成図に描かれていない内訳＝実行条件の一覧・失敗時の分岐・状態の遷移・環境ごとの差。図の重複は項目6、コードの書き写しは項目18でも見る）④同じ対象の列挙が他のセクションと重なっていればNG（1つ足すたびに2箇所を直すことになる。文書内DRYは項目4でも見る）。セクションの長さに下限は無く、内訳の薄い決定は数行でよい
16	却下案が設計書に書かれていないか	対象は設計書のみ。NGは①ADR対象の判断（adr-policy の判定で「作る」になる決定）について、採らなかった案の優劣を論じている記述 ②同じくADR対象の判断について旧設計から変えた経緯を論じている記述。①②は設計書から消し、決定した Issue に残っているかを確かめる（ADR にした決定は ADR にも書き、設計書からリンクする。書き先は adr-policy に従う）。NGにしないもの：ADR対象より軽い判断で、理由が「別の形にするとこう壊れる」という対比で書かれているだけの文。採用した案の代償（「〜になるが〜を優先した」）は却下案ではなく「受け入れた不便」なので、削除させず「前提と制約」の節へ移させる
17	まだ無いものが書かれていないか	対象は設計書のみ。これから実装するつもりの構成・機能が、現に存在するかのように書かれていればNG（実装を grep して現物の有無を確かめる）。例外は2つ——①意図的にやらないと決めたこと（「前提と制約」に書く）②入れ物は実在し中身が空の状態（TODO(#31) のようにIssue番号を添える）。番号の無い進捗表現は項目2で見る
18	コードを読めば分かることが混入していないか	対象は設計書のみ。各記述に①「これはコードを読めば分かるか」②分かるなら「1箇所ずつしか読めず、一覧できないものか」を順に問う。①がYesで②がNoならNG（手順は手順書へ、業務の振る舞いは docs/requirements.md へ、入出力・エラー契約は型＋テストへ、実装詳細・具体値はコードへ逃がす）。②がYesなら集約に価値があるので概要を表に置いてよいが、各行の中身（個々のルール・閾値）まで書いていればNG。docs/design/interface-specification.md は対象外（納品物のため契約の網羅を書いてよい。design-doc-policy の例外規定）
19	図のノードが抽象名だけになっていないか	対象は設計書のみ。図のノード名が「常時実行の検査」のような抽象名で、実装の固有名詞（ジョブ名・ラベル名・リソース名・クラス名）に対応づかなければNG。NGにしないもの：コードに対応物が無いノード（人・組織・外部サービスの利用者など業務側の主体）。図の役目はコードへの入り口を作ることなので、入り口の無いノードは対象外。混入禁止が禁じるのは中身（ロジック・設定値）の書き写しであって、名前ではない
20	図直下トグルの中身が図の言い換えになっていないか	対象は設計書のみ。図の直下に <details><summary>設計意図</summary> があるとき、その中身を見る。①構成図のノード・エッジをなぞり直しただけならNG ②図を読めば分かることの言い換え（「A から B へ流れる」等）だけで、なぜその形にしたかが無ければNG ③却下した代替案の優劣を論じていればNG（設計書に書かず、書き先は adr-policy に従う）④表になっていればNG（短い文章にする）。トグルが無いこと自体はNGにしない——「書く「なぜ」が基本方針の1項目の言い換えにしかならないなら置かない」という例外があり、有無では機械判定できないため。水増しを落とす側で担保する
21	前提と制約の位置と小節が揃っているか	対象は設計書のみ。①節の位置が構成図（全体像）の節の直後でなければNG ②### 技術的制約 と ### 組織の制約 の2小節に分かれていなければNG。該当が無い小節を削っていてもNG（「なし」＋一言理由で閉じる）。技術的制約に入るのは触ると壊れる前提・意図的にやらないと決めたこと・受け入れた不便、組織の制約に入るのは組織・ガバナンスから課され自分たちでは変えられない制約（命名規約・タグ規則・暗号化要件・リージョン制約など）。節そのものが無いことは項目17で見る。契約の網羅を書く仕様書（docs/design/interface-specification.md）は2本柱の対象外なので①はN/A

項目9の実行手順（切り離した評価者に投げる）

1. 対象読者と用事の一文を引く

順	探す場所	例
1	## 対象読者 節の一文	「Markdown でドキュメントを書く／レビューする人 / AI が、何を書き・何を削り・どう可視化するか迷ったとき」
2	frontmatter の description	.claude/skills/・.claude/agents/ 配下の場合
3	文書冒頭（H1 直後）の一文	「CI/CD パイプラインの設計。ポイントは〜」
4	docs/adr/ 配下ならディレクトリ既定	「過去の決定の経緯を追う人 / AI が、なぜそう決めたかを知るために読む」

どれでも引けなければ、中断せず、呼び出し元（自分）が一文を起草して文書冒頭に追記する。

2. deletion-advocate-agent を起動する

チェック対象が属する最も内側の見出し節ごとに起動する。渡すのは次の3つだけ。

1. 手順1で引いた対象読者と用事の一文
2. その節の原文
3. そのうちどれがチェック対象（差分・新規追加行）かの印

会話履歴・作業の経緯・誰が書いたか・「これで良いか確認したい」等の期待を示す言葉は渡さない。切り離しが効き目そのもので、文脈を渡すとエージェントは書き手の味方をしはじめる。

3. 3点セットが揃わない候補を棄却する

• 原文の引用：対象ファイルに実在する文字列と一致するか
• 対象読者の宣言文の引用：手順1で引いた一文の中にある文字列か
• 消したときの読者の行動の変化：「変わらない＋根拠」か、変わる行動が動詞で書かれているか

1つでも欠けていれば棄却する。棄却した候補は報告に残すが、NG としては扱わない。

4. 残った候補を報告し、消すかを判断する

候補は消したもの・残したものを全件報告する。挙がった候補を報告から落としてはならない——切り離した評価者に判定させた意味が消える。

消すかどうかは呼び出し元が判断する。 ただし、対象がどうあるべきかに答える理由の文は消さない（adr-policy「いまそうしている理由は、ADR にしてもしなくても仕組みの本文に書く」）。この文書にどう書くかに答える理由の文は、書き手の事情なので消してよい（documentation-policy「本文に書く理由と、書かない理由を見分ける」）。残す場合、その理由は報告表のコメント欄に書く。文書本文に「なぜ残したか」を書いてはならない。

チェック項目に載せない規約と理由

documentation-policy.md・documentation-policy-for-humans.md と Rule document-writing.md・document-writing-for-humans.md の規約のうち、次は意図的にチェック項目から外している。軽量チェックが成立する条件は「差分だけを見て、その場で直せる」ことで、これを満たさない規約は /doc-review の責務に置く。

• 600行の分割目安：文書全体の構成判断であり、直し方が「その場で修正」ではなく分割提案になる
• 1文書内の俯瞰の一覧：同種の詳細が2件以上並ぶかは差分の外の前後の節まで読まないと分からず、直し方も一覧の新設という構成変更になる。/doc-review が判定する（前からある違反は --full のときだけ）
• 400行超の目次必須と ### までのネスト：判定に要るのは行数と見出しの一覧だけで、差分を読む必要がない。/doc-review が判定する（前からある違反は --full のときだけ）
• 対象読者・目的の明示と妥当性：文書の狙いを読み解く質的判断で、差分だけでは判定できない
• 見出し・トピックセンテンスの質：同上。良し悪しに幅があり、機械的な判定基準に落ちない
• 視覚的な強調の手段：太字を禁じる規定ではなく、どの箇所が「特に重要」かに幅があるため、機械的な判定基準に落ちない
• 文書間DRY（SSOT）：判定には差分の外の全文検索が要る。検索せずに「他文書に無い」と断定できてしまい、通らないゲートになる。/doc-consistency が見る
• 置き場所を定義表で引くこと：直し方がファイルの移動と参照元の貼り替えになり、その場で直せない。/doc-review が観点「配置と言語」で判定する
• 削除の判定を書き手が下すこと：項目9として残すが、判定は自分で下さず deletion-advocate-agent に委譲する。書き手が自分の文章に削除テストを当てると、ほぼ常に「要る」と結論するため

チェック項目外の所見の扱い

対象を読む過程で、上記の全項目に当てはまらない問題に気づくことがある。その場合は確信度で扱いを分ける。

• grep・リンク検証など機械的な確認1回で存在を確かめられる問題（誤字・矛盾・壊れたリンク等）：その場で修正する
• 確認に読み手の解釈を要する問題：修正せず、報告のみ行う

出力と修正

1. 対象を読み、上記の全項目をチェックし、次の表で報告する（OKの項目も含め全項目を報告し、見落としを隠さない）。設計書（docs/design/**/*.md・samples/docs/design/**/*.md）以外を対象にしたときは、対象を設計書のみと明記した項目を N/A と報告する。チェック項目外の所見があれば表の下に追記する。

#	判定	該当箇所・コメント
1	OK / NG	...

2. NGがあれば、確認を挟まずその場でEdit/Writeを実行して修正する。修正内容は上表の該当行にコメントとして併記する。
3. 修正が見出し（#〜######）の追加・削除を伴う場合は、実行前に一言その旨を添えてから進める。