Skip to main content

quick-doc-review

ドキュメント編集直後の軽量レビュー。よく指摘される項目だけを高速にチェックし、その場で修正する。「quick-doc-review」「軽くdocチェックして」と指示されたとき。大掛かりなレビューは /doc-review。

Ir para a instalação

Informações da origem

Repositório
kasiopeiya/claude-dev-template
Última atividade na origem
14 de setembro de 2026 às 06:00
Idioma detectado do SKILL.md
japonês
Estrelas
0
Forks
0

Opções de instalação

Por padrão, está selecionado o prompt que primeiro revisa a origem. Você pode mudar para um comando direto ou baixar uma cópia local.

Revise os arquivos de origem

Leia o SKILL.md e os arquivos complementares exibidos pelo SkillsMP antes de decidir se vai instalar.

Exibindo SKILL.md

SKILL.md
Instruções da origem · Visualização somente leitura
name
quick-doc-review
description
ドキュメント編集直後の軽量レビュー。よく指摘される項目だけを高速にチェックし、その場で修正する。「quick-doc-review」「軽くdocチェックして」と指示されたとき。大掛かりなレビューは /doc-review。
argument-hint
[file-path]
# 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. 対象読者と用事の一文を引く** | 順 | 探す場所 | 例 |
Ver no GitHub
Este SKILL.md e muito grande, entao o SkillsMP mostra aqui apenas a primeira secao. Ver no GitHub