quick-doc-review

# Quick Doc Review `/doc-review` は文書の目的・対象読者・可視化提案まで含めた質的なレビューで、全文を読む subagent を起動するため時間がかかる。本スキルはそれとは別物で、**判断ログ上で繰り返し指摘されてきた具体項目だけ**を、メインの会話内で直接・高速にチェックし、その場で修正する。網羅的な品質判定はしない。 例外は項目9（冗長な記述）だけで、ここは差分だけを渡す軽い subagent（`deletion-advocate-agent`）を起動する。**削除の判定を書き手が自分で下すと必ず「要る」と結論する**ので、この項目だけは自問では成立しない。 `quick-issue` と同様に「本格フローの軽量版」シリーズの1つ。 > [!NOTE] > **（AI・必須）** 判定基準は本来 `documentation-policy.md` が正（SSOT）だが、本スキルは**速度を優先し、そこから具体的な判定基準を書き下して自己完結させている**（DRYより速度を優先した意図的な例外）。`documentation-policy.md` 自体が改訂されたときは、このチェック項目も追従して見直すこと。要件定義書（`docs/requirements.md`）だけは `requirements-doc-policy.md` が一部の規約を上書きするため、該当するチェック項目の判定基準に例外として書き下してある。設計書（`docs/design/**/*.md` と手本の `samples/docs/design/**/*.md`）は `design-doc-policy.md` が固有の規約を足すため、対象を設計書のみと明記したチェック項目に書き下してある。いずれのポリシーの改訂時も同じく追従すること。 ## 対象 1. **対象ファイル**：引数にファイルパスがあればそれを対象にする。無ければ、直前のターンで自分がEdit/Writeしたファイルを対象にする。 2. **チェック範囲**：`git diff HEAD -- <対象ファイル>` で差分を取得する。差分があれば**差分部分だけ**をチェック対象にする（速度優先のデフォルト）。差分が無ければ（コミット済みで変更がない、または新規追加ファイルで差分が出ない等）、**ファイル全文**を対象にする。 3. **決着済みの例外**：チェックを始める前に `grep <対象ファイルのパス> docs/reference/doc-rule-exceptions.md` を実行する。該当行があれば、その行が挙げる規定を指摘しない。ただし行の「判断」列に書かれた外形的な事実（列数・行数など）が現物と違っていれば、決着は当てはまらないので通常どおり指摘する。 ## チェック項目・判定基準 | # | 項目 | 判定基準 | | --- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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項目の対比だから」「表の方が整って見える」は表のまま残す理由にしない。図種の選び直しは次項で見る。**例外**：`CLAUDE.md` は②も箇条書きでよい（常時ロードされ、罫線のトークンを毎回払うため）。要件定義書（`docs/requirements.md`）は2列の表をNGにしない | | 6 | 図が過剰・図種が不適切でないか | 差分に図があるとき、**逆変換テスト**を当てる：その図を表・箇条書きに戻して、文章を読まずに構造を掴めるならNG（戻す先を明示して指摘する）。図の価値は分岐・合流・ループ・並行・多対多・階層・状態遷移にあり、一直線（A→B→C）の箱並べは文章の言い換え。テキストへ復元できること自体は理由にならない（測るのは認知負荷）。加えて図種も見る：フローチャートは他のどの形にも当てはまらないときだけ選んでよく、シーケンス図・状態遷移図・ツリー図等が合う情報をフローチャートで描いていれば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 / 人間 / AI・人間、強制力は 必須（MUST） / 推奨（SHOULD）。両対象なら `**（AI・必須 / 人間にも）**`。行動を促さない補足・前提（`[!NOTE]` 等）はラベル不要で対象外 | | 9 | 冗長な記述がないか | **候補を自分で挙げない。** 削除テストは `deletion-advocate-agent` に投げ、返った候補を捌く（手順は「[項目9の実行手順](#項目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`）は①の件数条件の例外**——`requirements-doc-policy.md` が表ごとに名指しした詳細（本文型はその表の全行、補足型は列の記述だけでは読み取れない行）は、1件でも畳んでよく、畳みすぎと判定しない。**対象外**：見出し（`####` 等）を持つ節（トグルに見出しは入れられない）と `CLAUDE.md`（毎回読み込まれタグのトークンを払い続ける）。畳んだ内容には**トグル削除テスト**を当てる——畳んだ部分を伏せて本文だけを読み、読者が判断・行動できなければNG（結論・規定を畳んでいる。その理由・根拠は畳んでよい）。**記法**もNG判定に含む：`<details>` 直後と `</details>` 直前に空行が無い／中に見出しがある／`summary` が「詳細」「補足」など中身の分からない語（`ID 名前`・項目名にする。ただし設計書の図直下トグルは「設計意図」で固定）／対応する表・一覧と並び順が違う | | 14 | 基本方針が考え方1文＋方針の箇条書きで書かれているか | **対象は設計書（`docs/design/**/*.md` と `samples/docs/design/**/*.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対象の判断**（アーキテクチャの水準で、後から変えるのが高くつく決定。細目は [create-adr](../create-adr/SKILL.md) のADR判定基準）について、採らなかった案の優劣を論じている記述 ②旧設計から変えた経緯。ADR（`docs/adr/`）へ出してリンクに置き換える。**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 へ出す）④表になっていればNG（短い文章にする）。**トグルが無いこと自体はNGにしない**——「図だけで説明が閉じるなら置かない」という例外があり、有無では機械判定できないため。水増しを落とす側で担保する | | 21 | 前提と制約の位置と小節が揃っているか | **対象は設計書のみ**。①節の位置が構成図（全体像）の節の直後でなければNG ②`### 技術的制約` と `### 組織の制約` の2小節に分かれていなければNG。該当が無い小節を削っていてもNG（「**なし**」＋一言理由で閉じる）。技術的制約に入るのは触ると壊れる前提・意図的にやらないと決めたこと・受け入れた不便、組織の制約に入るのは組織・ガバナンスから課され自分たちでは変えられない制約（命名規約・タグ規則・暗号化要件・リージョン制約など）。節そのものが無いことは項目17で見る。契約の網羅を書く仕様書（`docs/design/interface-specification.md`）は2本柱の対象外なので①はN/A | ## 項目9の実行手順（切り離した評価者に投げる） **1. 対象読者と用事の一文を引く** | 順 | 探す場所 | 例 |