reviewing-developer-guide

reviewing-developer-guide — SKILL.md

バリアント： standard · 使用する場面： 完成した（または修正済みの）開発者ガイドを受け入れゲートとして評価するとき — 開発者がそのガイドを使ってツールを導入、統合、運用できるかを確認し、実行可能な指摘事項とともに VERDICT: approve|revise を出力します。

概要

このスキルは、開発者ガイドの作成／評価ペアのうち、レビュー側を担います。完成した開発者ガイド（SDK、ライブラリ、CLI、フレームワーク、API プラットフォームなどの開発者向けツール製品について、利用開始の案内、導入手順、主要な概念、コード中心の統合方法、エンドツーエンドのチュートリアル、本番環境でのベストプラクティス、トラブルシューティングの手順、api-reference への案内を含む、導入と統合のための説明）を持つレビュアーが読み込み、次の一点を基準に評価します。開発者は、このガイドだけを頼りにツールをインストールし、そのメンタルモデルを理解し、一般的な統合シナリオを完了し、よくあるエラーから復旧し、本番環境で運用できるか。さらに、実行可能なコードがあり、すべての手順がツールの実際の動作と一致しているか。 固定された導入容易性＋正確性のチェックリストを適用します。これは開発者ガイドの作成者が満たす基準と同じであり、作成基準とレビュー基準が乖離しないようにします。そのうえで、機械で解析できる単一の判定と、作成者が1回の修正で対応できる指摘事項を出力します。これは受け入れゲートです。ガイドの作成、修正、書き換えは行いません。評価して指摘事項を返し、作成者が修正します。

基準の一本化。 Step 2 の14の条件は、ここで独自に定めたものではありません。authoring-developer-guide が準拠する導入容易性＋正確性の基準（同スキルの Step-5 のセルフチェックと1対1で対応）であり、references/adoptability-bar.md に要約されています。これにより、レビュー基準と作成基準が一つの基準になります。

対象形式（現時点）。 レビュー対象のガイドは、レンダリング済みのドキュメントサイトではなく、Markdown（説明文と、フェンスで囲まれたインストール／統合コード）です。レビューの方法と基準は形式に依存しません。将来 Figma／Confluence／レンダリング済みドキュメントに対応するバックエンドが加わっても変わるのは形式だけであり、このスキルが確認する内容は変わりません。

起動する場面

• 完成した開発者ガイドを、統合を行う開発者に公開する前に承認するか修正を求めるか判断する必要がある場合。
• 作成者が作成した開発者ガイドを、独立したレビュアー／ゲートとして評価する場合。
• 以前の判定が revise だった開発者ガイドを、修正後に再評価する場合。
• AMEND を評価する場合 — すでに公開済みのガイドに対する差分（例：ツールの新バージョンがリリースされた場合）を対象に評価するとき（条件12）。

次の場合は起動しないでください：

• 開発者ガイドを作成または修復する場合 → authoring-developer-guide を使用してください（このスキルが定めるものと同じ基準に準拠して作成します）。このスキルがガイドを書くことはありません。
• エンドユーザー向け製品ガイド（技術者ではないユーザーが読む、利用者向けのヘルプ）をレビューする場合 → user-guide-review スキルを使用してください。このゲートはエンドユーザーにとっての使いやすさを評価し、このゲートは開発者にとっての導入容易性を評価します。
• api-reference（エンドポイント／シンボルを網羅したカタログ）をレビューする場合 → api-reference-review スキルを使用してください。そのゲートはカタログの網羅性と契約との一貫性を評価し、このゲートは api-reference へ案内する開発者向けの説明を評価します。
• エンジニアリング設計文書（アーキテクチャ仕様、設計文書、ADR、RFC）をレビューする場合 → design-review を使用してください（コードベースに照らして設計上の主張を検証します）。これは別のゲートであり、基準も異なります。
• テンプレートやセクションへの準拠を確認する場合 → これはテンプレートに関する確認です。このスキルは、すべての見出しが存在するかではなく、基準に対する品質を評価します。

ワークフロー

Step 1: ガイド全体を新鮮で独立した視点で読み、上流資料を集める

開発者として初めてこのツールを導入するつもりで、著者の枠組みにとらわれず、開発者ガイドを最初から最後まで読みます。あなたは門番の立場です。指摘に重みがあるのは、開発者が記載どおりにツールを導入、統合、または運用できないことを示す場合、またはある手順がツールの実際の動作と一致しない場合に限られます。

提出された上流資料（通常は機能仕様書、API プラットフォームの場合は API リファレンス）を取り込みます。Step 2 の正確性と網羅性の条件は、これらの資料と照らし合わせて確認します。製品の類型（単一目的の簡素な CLI か、幅広い API プラットフォームか）を特定します。求められる基準は、それに応じて変わります。改訂の場合は、変更リクエストと変更後の上流資料も集めます。cond-12 はそれらと照らし合わせて確認します。コードサンプル、統合手順、API リファレンスへの参照が重要な役割を担う箇所を記録します。チェックリストでは、そうした箇所を精査します。

Step 2: 導入可能性と正確性のチェックリストを実施し、各条件を判定する

以下の各条件について、合格または不足と判定します。条件が不合格となるのは、具体的な名称を挙げられる実際の不備がある場合に限られます。「セクションの順序を変えたほうがよかった」は不足には当たりません。不足がある場合は、正確な箇所と欠けている内容を記録します（Step 4 で実行可能な指摘にまとめます）。この 14 項目の条件が唯一の基準です（references/adoptability-bar.md）。独自の条件を追加してはいけません。各条件は比例的です。簡素なツールでは、不要な要素を正当に省略できます（「比例性」を参照）。

1. 目標別に構成されている。 開発者が何を構築・達成できるかを軸にし、レシピには目標に基づいた名前を付けます。エンドポイントを平坦に並べた一覧にはしません。不足：導入までの流れがなく、エンドポイントを列挙しただけの場合。
2. はじめにの手順で、検証可能な最初の成功まで到達できる。 前提条件（認証情報の入手先、つまりサインアップからキー取得までの手順を含み、最初の呼び出しにはテスト／サンドボックスモードを使うよう案内します） -> インストール -> 認証情報の設定 -> 実際に成功する呼び出しを1つ実行 -> 期待される出力を示した検証手順。実行可能で、コピー＆ペーストして使えます（単なる Hello World ではなく）実際の価値を示し、環境変数による認証情報を使用して、ハードコードしません。最初に検証済みの成功を得るまでの手順を最小限に抑え、短く、つまずかずに進められる経路にします（TTFC の意図は「短く、つまずかずに進められる」ことで評価し、ストップウォッチで測るものではありません）。不足：検証手順がない、最初の呼び出しを実行できない、認証情報がハードコードされている、または不必要に長い／妨げのある経路になっている場合。
3. 主要な概念がレシピより前に説明されている。 クライアントオブジェクト、ドメインの用語、ライフサイクル、環境といったメンタルモデルを、理解を促す内容として説明し、統合レシピより前に配置します。パラメーターの一覧にはしません。不足：概念が説明されていない、またはレシピの後やレシピ内に埋もれている場合。
4. 統合方法の説明が、提出された上流資料にある一般的なシナリオを網羅している。 一般的なシナリオごとに、目標を示す名前の付いた、コード中心で単独でも読み進められるレシピを用意します。実行可能なコードを示し、すべてのオプションについてはリファレンスへのリンクで案内します。不足：提出された機能仕様／API リファレンスにある一般的なシナリオのうち、レシピがないものがある場合（カバレッジの穴）。
5. エンドツーエンドのチュートリアルで、実用的な小さなものを最初から最後まで構築する。 セクション4の参照用レシピとは分けて、適切に How-to と Tutorial を区別します。不足：エンドツーエンドの構築手順がない、またはチュートリアルとレシピが一体化している場合。
6. 実際の利用に基づいたベストプラクティスがある。 認証／シークレット、再試行可能なエラーと致命的なエラーの処理、再試行＋冪等性＋バックオフ、ページネーション、レート制限、Webhook（ツールが送信する場合は署名／リプレイ／順序）、リソースの適切な管理（クライアントの再利用／プーリング／タイムアウト）について、それぞれ推奨パターンとコード例を示します。オプションの羅列にはしません。不足：本番環境での考慮事項が説明されていない、または推奨事項がなく、オプションを羅列しただけの場合。
7. Diataxis の各モードが適切に分類され、分離されている。 チュートリアル／How-to／解説／リファレンスをそれぞれ独立したモードで扱い、互いに混在させません。不足：モードが混同されている（はじめにがリファレンスの羅列になっている、概念がレシピ全体に散らばっている、チュートリアルがレシピと一体化している）場合。
8. API リファレンスへリンクし、内容を重複させない。 網羅的なエンドポイント／シンボルのカタログは、ガイド内に再掲せず、信頼できる参照先としてリンクで案内します。不足：ガイド内にカタログをそのまま再掲している場合（api-reference-linking チェック — ステップ3）。
9. コード例が実行可能で、実際の／CURRENT ツールや API に正確に即している。 すべての例が、提出された機能仕様／API リファレンスに記載された実際の機能／エンドポイントを反映し、環境変数による認証情報を使用し、上流の仕様と矛盾しないようにします。例が対象とするツールのバージョンも明記します。不足：例が、上流資料に存在しないエンドポイント／メソッド／機能を呼び出している場合、つまり捏造している場合（upstream-accuracy チェック — ステップ3）。（レビュー担当者がツールのバージョンを判断する根拠は、提出された上流資料以外にありません。「記載されたバージョンが最新かどうか」は新規作成時のチェックではありません。鮮度に関する確認は cond-12 で行います。）
10. ツールのバージョン管理と移行について記載されている。 バージョン体系、非推奨化のポリシー／期間、変更履歴へのリンク、およびメジャーバージョン更新ごとの移行前後の説明（アーキタイプに応じた規模）を含めます。不足：バージョン管理されたツールを提供しているのに、バージョン管理／移行のガイダンスがない場合。
11. 捏造せず、上流資料に基づいている。 機能／エンドポイント／コードは上流資料を反映させます。実際に情報が不足している場合は、エンドポイント、機能、コードパスを創作せず、明示的な前提／未解決の質問として示します。不足：情報が不足している箇所を、完全な内容に見せるために捏造している場合。（cond-9 との区別：例の中で捏造したエンドポイント／メソッドについては cond-9 を挙げます（例と上流資料の正確性チェック）。本来不足として示すべき箇所で捏造した回答／前提については cond-11 を挙げます。同じ欠陥を両方に重複して挙げないでください。）
12. 差分に限定した修正（amend モードの場合のみ）。 変更依頼＋変更された上流資料が提出された場合（入力シグナル）にのみ有効で、新規作成では該当なしです。変更されていないガイド全体ではなく、変更箇所を評価します。変更されたブロックが基準を満たしていること（変更された例は実行可能で、CURRENT ツールに正確であること）、上流資料との不整合の総点検が完了していること（削除／改名された機能を呼び出す例／レシピ／参照先が残っていないこと。amend における最も影響の大きい欠陥です）、内部の一貫性が保たれていること（概念がレシピより前にあり、チュートリアルが引き続き実行できること）、ガイド自体のバージョンが更新され、変更履歴に項目が追加されていること、置き換えられた／非推奨の内容が明示されていることを確認します。不足：古い例が残っている、変更履歴がない、または置き換えられた内容が何の説明もなく削除されている場合。（変更されておらず、現在も正確なレシピは再レビューしないでください。）
13. トラブルシューティング／よくあるエラーへの対応経路がある。 頻繁に発生し、原因が判明している問題に対するセルフサービスの解決手段（症状 -> 原因 -> 解決策。ツールにエラーコードがある場合はエラーコード表、簡潔な FAQ）を用意します。はじめにで扱う最初の呼び出し時の2〜3件の失敗にとどまりません。不足：頻繁に発生し、原因が判明しているエラーに遭遇した開発者が、ガイド内で解決策を見つけられない場合。規模に応じて判断します — 単機能の小規模なツールでは、これをはじめにの手順にまとめても問題ありません。「Troubleshooting」という名前のセクションがあるかどうかを評価する項目ではありません。
14. 見つけやすい — 開始場所が明示され、読者の読み進める順序が整っている。 初めて読む人が、API をあらかじめ知っていなくても、最初に読むべき場所と目的に合ったセクションを見つけられます。不足：案内や最初に読むべき場所がなく、新しい読者がどこから始めればよいかわからない場合。規模に応じて判断します — 1ページのガイドは容易に見つけられるため、不足には該当しません。重複判定を避けるための重要な注意： cond-14 はナビゲーション／見つけやすさについての項目です。cond-1（目標別の構成）や cond-3（概念の配置順）ですでに指摘した欠陥を、cond-14 で再度指摘しないでください。cond-14 で不適合とするのは、案内／最初に読むべき場所自体がない、または辿れない場合だけです。エンドポイントの羅列（cond-1）や、概念がレシピの後にあること（cond-3）を二重に減点するために使わないでください。 名前付きの3つのチェック（影響が最も大きいもの）：

• 上流との正確性チェック（cond-9）。連携手順とコードサンプルを、提出された feature-spec／api-reference と照合して抜き取り確認します。実在しない機能やエンドポイントは、影響が最も大きい欠陥であり、名前を挙げて指摘すべき不足です。上流資料が存在しない場合（API ではない CLI に api-reference がない場合など）は、前提として明示し、提出された内容に基づいて採用可能性を判断します。上流資料がないこと自体は、修正を求める理由にはなりません。
• api-reference へのリンクチェック（cond-8）。ガイドは api-reference の該当箇所を指し示し、カタログを再掲してはなりません。項目を本文に再掲している場合は不足、明確な参照先が示されていれば合格です。
• 修正時の古い記述の一掃チェック（cond-12、修正モードのみ）。ツールの変更後、削除または改名された機能への参照がガイド内に残っていないことを確認します。古いサンプルが残っていることは、修正時の最も重大な欠陥です。

適切な規模。「導入し、連携し、運用できること」の範囲は、製品に応じて変わります。単機能の小規模な CLI のガイドでは、不要なセクションを省略するのが適切です。レシピを少なくする、概念の説明を軽くする、トラブルシューティングを導入手順にまとめる、移行表を設けない、1ページですぐ見つかる構成にする、といった対応は不足ではなく、適切な規模です。幅広い API プラットフォームでは、レシピ、Webhook、トラブルシューティング、移行に関する注意事項を充実させます。セクション数や文字数ではなく、最初に検証可能な成功を得られることと、本番環境で正しく連携できることを評価します。該当するすべての条件を満たす、小規模で完結したガイドは合格です。（条件2と9は、規模にかかわらず適用されます。最初の呼び出しで検証できること、そしてサンプルを捏造しないことが必要です。）

ステップ3：判定を決める

• approve — 該当するすべての条件に合格しています。開発者はこのガイドだけでツールをインストールし、その仕組みを理解し、一般的な連携シナリオを完了し、よくあるエラーから復旧し、本番環境で運用できます。コードは実行可能で、各手順はツールの実際の動作と一致しています。文体を改善できると思っても、採用可能性と正確性が基準であり、完璧さや網羅性の最大化ではないため、承認してください。
• revise — 1つ以上の条件に、導入・連携・運用を妨げる、明確に特定できる不足があります。たとえば、検証可能な最初の成功がない、レシピより後に概念の説明がある、提出されたシナリオのレシピがない、捏造された、または古くなったエンドポイント／機能がある、カタログをリンクせずに重複して掲載している、Diataxis のモードが混同されている、必要なツールなのにトラブルシューティングの手順がない、開始方法が見つけにくい、修正後も古いサンプルが残っている、または回答が捏造されている場合です。

労力を評価したり、あると望ましい機能を求めたりするために修正を要求してはいけません。条件は満たされているか、満たされていないかのいずれかです。

ステップ4：判定と、対応可能な指摘を出力する

判定は1行だけで出力します。文字列 VERDICT: approve または VERDICT: revise を、前後にコードフェンス、引用符、その他の語句を付けず、単独の行として記載します（以下のフェンスは例示にすぎません）。

VERDICT: approve

続く行に指摘を列挙します。revise の場合、各指摘は対応可能な内容とし、該当する条件、正確な箇所、修正方法を示してください。これにより、著者が一度の修正で解決できます。approve の場合、指摘は任意の、承認を妨げない補足事項です。修正が必要だと受け取られる書き方は避けてください。

適切な指摘では、不足内容と修正方法を明示します。

revise — 上流との正確性（cond. 9）、「メッセージを送信する」レシピ：client.messages.schedule(at=...) を呼び出していますが、提出された api-reference にスケジュール機能を持つエンドポイントも schedule メソッドもありません。修正：api-reference に記載された実在の機能に置き換えるか、スケジュール機能を未解決の質問として明示し、捏造した呼び出しを掲載しないでください。

revise — 修正時の古い記述の一掃（cond. 12）：ガイドは SDK v3 に更新されていますが、「請求を返金する」レシピには、v3 で削除された Client(key=...) の呼び出しが残っています。修正：すべてのサンプルを Client.from_env() に置き換え、v2 の書式には旧方式であることを明記してください。

不適切な指摘は、曖昧で対応方法がわかりません。

コード例をもっと充実させるとよいでしょう。 (どのサンプルに問題があるのでしょうか。何が問題で、どう直せばよいのでしょうか。)

ルール

絶対ルール（決して違反しないこと）：

• 判定行は VERDICT: approve または VERDICT: revise のいずれか1行だけを出力すること — その文字列を単独の行に記載し、それ以外は何も出力しないでください。後続のツール（_parse_verdict）が解析します。
• 判断者に徹し、執筆者にならないこと。 指摘事項を返してください。ガイドを書き直したり、修正したり、内容を補ったりしないでください。修正は作成者が行います。
• 単一基準に従うこと。 Step 2（references/adoptability-bar.md、作成者が準拠するのと同じ基準）の14項目に照らして判断してください。基準を独自に追加したり、独自の厳しい基準を適用したりしないでください。
• 誤った revise を避けること。 適用されるすべての条件を満たしているガイドは、単一用途のツール向けの簡潔なものでも承認してください。最初の成功に到達でき、提示されたシナリオを網羅できているなら、分量が相応であることは欠陥ではありません。実際に存在する、具体的な不足がある場合に限り revise としてください。
• 誤った approve を避けること。 相手に合わせるために、実際の不足があるのに承認してはいけません。阻害要因となる不足があれば revise です。
• cond-14 で二重に減点しないこと。 cond-1（goal-organization）または cond-3（concepts-ordering）ですでに検出される欠陥について、見つけやすさ（cond-14）を問題にしないでください。cond-14 を不合格にするのは、開始案内が存在しない、またはたどれない場合に限ります。
• 捏造された、または古くなったエンドポイント／機能は、根拠ではなく不足です（cond-9／cond-12）。提出された上流資料に存在しないもの（またはツール変更で削除されたもの）を呼び出すサンプルは、最も影響の大きい欠陥です。
• カタログは複製せず、リンクすること（cond-8）。
• 最初の成功では検証できることが必須です（cond-2） — 実行可能で検証可能な最初の呼び出し、期待される出力、そしてハードコードではなく環境変数を使った認証情報が必要です。
• レシピより先に概念を説明すること（cond-3）。
• Amend の対象は差分に限定すること（cond-12） — 変更内容、古くなった情報の確認、変更履歴をレビューしてください。変更されていないガイド全体を対象にしてはいけません。手を加えていないレシピの正当性を再説明していないことを理由に、問題のない小規模な amend を誤って revise にしないでください。
• 提示された上流資料に照らして判断すること。 提示されていない上流資料は、決して revise の根拠にしてはいけません。前提事項として指摘してください。ただし、提示された上流資料を無視しているガイド（シナリオに対応するレシピがない、サンプルが api-reference と矛盾しているなど）は、正当な指摘対象です。
• revise の指摘はすべて、対応可能な内容にすること — 違反した条件、該当箇所、具体的な修正内容を示してください。

望ましい事項（上書き可能）：

• 指摘事項は深刻度順に並べてください — まず阻害要因となる不足（捏造／古い情報、最初の成功がないなど）、次に軽微なものを記載します。
• 作成者が基準に照らして対応できるよう、各指摘に条件番号／名称を記載してください。
• approve の注記は少数にとどめ、明らかに承認を妨げるものではないと分かるようにしてください。

注意点

• 導入しやすさではなく、網羅性を基準に承認してしまうこと。 すべてのセクションがそろっていても、開発者が統合できない場合があります（最初の呼び出しで検証できない、サンプルがエンドポイントを捏造している、概念がレシピの後に置かれているなど）。テンプレートが埋まっているかではなく、開発者が導入し、統合し、運用できるかを判断してください。
• 実行できそうなサンプルに紛れ込んだ、捏造されたエンドポイント。 提出された api-reference/feature-spec（cond. 9）と照らし合わせて、重要なサンプルをすべて抜き取り確認してください。これは影響の大きい欠陥の中で最もよく見られるものです。
• ツール変更後の古いサンプル。 修正時に、削除または改名された機能を呼び出すサンプルが残っていると、見た目は問題なくても実行時に失敗します。これは修正時に最もよく見られる欠陥です（cond. 12）。陳腐化の確認を行ってください。
• カタログを本文中に再掲してしまうこと。 ガイドに全エンドポイントとパラメーター表を親切に再掲すると、内容がずれていく二つ目のコピーになってしまいます（cond. 8）。充実して見えるため、見過ごされがちです。
• レシピに概念を紛れ込ませること。 ハウツーの中でメンタルモデルを断片的に説明すると、読者はモデルを理解する前にコードに直面します（cond. 3）。完成しているように見えても、そうではありません。
• Diátaxis のモードが混在していること。 「入門チュートリアル」が実際にはリファレンスの羅列だったり、チュートリアルと検索用レシピが一体化していたりします（cond. 7）。モードが混在していても問題ないように読めますが、学習者にも情報を探す人にも役立ちません。
• 見つけやすさを二重に減点すること。 エンドポイントの羅列（cond. 1）や、レシピの後に概念が置かれていること（cond. 3）を理由に cond-14 も指摘すると、評価が過剰になります。cond-14 が対象とするのは、開始方法の案内がない、または分かりにくい場合だけです。
• トラブルシューティングの過剰な指摘。 単一目的の小規模なツールで、よくあるエラーを入門ガイドに含めているのは適切な分量調整であり、cond-13 の欠落ではありません。専用のトラブルシューティングセクションを求めるのは、ツールで想定されるエラーの範囲がそれを必要とする場合だけにしてください。
• 上流ドキュメントの欠落を過剰に指摘すること。 API を使わない CLI には、リンクしたり正確性を確認したりするための api-reference がありません。これは注記すべき前提であり、修正を求めるものではありません。
• 体系的な過剰指摘（誤った修正判定）。 問題を見つけるよう求められたレビュアーは、適切なガイドまで欠陥があると判断し、過剰に修正しがちです。条件を欠落として扱うのは、明確に名指しできる実際の不備がある場合だけです。自分なら別の書き方をするセクションがないことは理由になりません。もっともらしい細かな指摘が、ここで最もよく見られるレビュアーの誤りです。
• 規模に見合ったガイドを誤って修正判定すること。 単一目的の小規模なツールのガイドは、適切に小さくまとまっている場合があります。短いことを理由に欠落をでっち上げると、避けられる修正の往復が増えます。ツールの類型に合わせて評価してください。
• これを user-guide や api-reference の審査基準と混同すること。 開発者向けガイドは、開発者が導入するための説明です。エンドユーザーの使いやすさやカタログの網羅性を基準にしないでください。
• 判定トークンの揺れ。 「Approved」、「LGTM」、「needs work」、または段落の途中に埋め込まれた判定は、正しく解析できません。VERDICT: approve|revise をそのまま独立した行に出力してください。

アンチパターン

• ゴム印のような承認。 修正のやり取りを避けるためにざっと目を通して承認すること。このゲートは、開発者が統合に使えないガイドを見つけるためにあります。架空のエンドポイントや、最初の呼び出しで検証が行われない例を見逃して承認すると、開発者は最初の手順で行き詰まります。
• 些細な点にこだわった修正要求。 セクションの順序の好み、文章のスタイル、あるとよい要素を不足事項として扱い、ブロックすることです。修正を求めるのは、採用可能性や正確性を実際に妨げる問題がある場合に限ります。
• 黙って書き直す。 「サンプルを直したほうが手っ取り早かった」――レビュー中に執筆すると、作成と評価の分離が崩れます。
• 条件を勝手に作る。 基準にない独自の要件（「Postman コレクション／動画／Troubleshooting という見出しも必要」など）を追加すると、レビュー基準が作成基準からずれていきます。評価するのは14の条件だけです。手法の観点（ドキュメントをコードとして扱う手法／CI、IA 手法、a11y チェックリスト、アーキタイプのオーバーレイ、ルーブリック）は、成果に基づいて評価する補助的なものであり、要求してはなりません。
• 過剰主義。 単機能の薄いツールのガイドに、幅広いレシピ一式、webhook、移行マトリックス、専用のトラブルシューティングセクションを要求することです。基準が求めるのは、検証可能な最初の成功と、提示されたシナリオへの対応です。可能な限り大きなガイドではありません。
• 上流の確認／古さのスポットチェックを省略する。 コードサンプルを、もっともらしさだけで承認することです。正確性（cond-9）と、修正時の古さの確認（cond-12）は最も影響の大きい評価項目です。絶対に省略してはなりません。
• 曖昧な判定。 「おおむね承認ですが……」や、判定行を2つ出すことです。決定は1つ、トークンは1つにしてください。

出力

開発者向けガイド1件に対するレビュー結果を1つ出します。

• 判定行は1行 — VERDICT: approve または VERDICT: revise を、変更せず単独の行に記載します。
• 指摘事項 — revise の場合、ブロックする問題ごとに、対応可能な指摘を1つ記載します（未達の条件＋場所＋具体的な修正）。approve の場合、ブロックしない補足は任意です。

想定される利用側は、作成からレビューまでのループをオーケストレーションするものです。approve は、統合を行う開発者向けにガイドを公開できると判断します。revise は、範囲を限定した修正作業のため、指摘事項を作成者に返します。

関連項目

• authoring-developer-guide — このペアの作成側です。このスキルが評価するのと同じ14条件の採用可能性＋正確性の基準に沿ってガイドを作成します。組み合わせることで、基準の出典を references/adoptability-bar.md に一本化し、作成とレビューのずれを防ぎます。
• user-guide-review スキル — エンドユーザー向け製品ガイド（非技術文書）のゲートです。文書、対象読者、基準がそれぞれ異なります。このスキルが評価するのは開発者にとっての採用可能性であり、エンドユーザーにとっての使いやすさではありません。
• api-reference-review スキル — エンドポイント／シンボルの網羅的なカタログのゲートです。文書と基準が異なります。このスキルが評価するのは、そのカタログへリンクする開発者向けの解説です。
• design-review スキル — エンジニアリング設計文書（アーキテクチャ仕様、設計文書、ADR、RFC）のゲートです。主張をコードベースと照合します。ゲートと基準が異なるため、開発者向けガイドには使用しません。
• developer-guide template / content-template ツール — セクションの構成を定めます。このスキルが評価するのは基準に照らした品質であり、構造への準拠ではありません。

段階的な情報開示

• references/adoptability-bar.md — 採用可能性＋正確性に関する14条件の単一の基準（authoring-developer-guide が作成時に使用するものと同じ基準）です。条件ごとの合格／不足の兆候と、記入例を含む指摘を掲載しています。新しい cond-12（修正時の古さの確認）、cond-13（トラブルシューティング）、cond-14（見つけやすさ＋重複防止ガード）、さらに内容を深めた cond-2/6/9 も含まれます。基準を詳しく適用するときに読み込みます。
• references/sources.md — レビュー手法の調査根拠です。採用可能性＋正確性に関する単一の基準、Diataxis のモード分離基準、リンクして重複を避けるルール、修正時の古さの確認、誤った修正要求を避けるための規律を裏付ける、レビュアーの過剰修正に関する根拠を記載しています。指針の出典を監査する場合に限り読み込みます。

Body budget

• description <= 1,024 chars (agentskills.io cap). Claude truncates the combined description + when_to_use at 1,536 chars in the skill listing.
• Body <= ~500 lines / 5,000 tokens — kept in context every turn.
• Per reference file: warn >10k tokens, error >25k. Total references: warn >25k tokens, error >50k.