authoring-developer-guide

authoring-developer-guide — SKILL.md

バリアント： standard · 使用する場面： 開発者ツールの導入と統合についての説明を作成（または改訂）するとき。開発者がガイドだけを頼りにツールをインストールし、そのモデルを理解し、一般的な統合シナリオを完了し、よくあるエラーを自力で解決して、本番環境で運用できる水準を目指します。実行可能なコードを用い、すべての手順がツールの実際の動作と一致している必要があります。

概要

このスキルは、優れた開発者ガイド、つまり開発者ツール製品（SDK、ライブラリ、CLI、フレームワーク、API プラットフォーム）の利用者向けの導入と統合に関する説明を書く方法を扱います。これは、開発者がゼロの状態から動作する統合を実現し、さらに本番環境向けの正しい統合へ進むために読む文章です。最初の呼び出しをすばやく成功させ、案内に沿って読み進め（どこから始めればよいかを示し）、ツールのメンタルモデルを理解し、コード中心のレシピに従い、実際に役立つ小さなものを最初から最後まで作り、本番環境でのベストプラクティスを適用し、よくあるエラーを自力で解決できるようにします。そのうえで、網羅的なリファレンスへのリンクも示します。技術読者向けに、Diataxis の4つの象限（チュートリアル／ハウツー／解説／リファレンス）全体をカバーします。このスキルが担うのは、セクション一覧ではなく、作成者の判断、すなわち調査方法と品質基準です。前提となるのは、2つの協力者です。セクションの構成を提供する開発者ガイドのテンプレートツールと、確立された開発者エクスペリエンス（DX）ドキュメントの実践、Diataxis、開発者向けドキュメントの品質評価基準（見つけやすさ／正確さ／関連性／明瞭さ／完全性／読みやすさ）に基づく深掘り調査機能です。作成者に渡されるのは、計画でこのガイドに必要と判断された上流ドキュメントであり、白紙から始めることはありません。達成すべき基準は、開発者がガイドだけを頼りにツールをインストールし、そのモデルを理解し、一般的な統合シナリオを完了し、よくあるエラーから復旧できることです。実行可能なコードを用い、すべての手順がツールの実際の動作と一致している必要があります。

このスキルは既存のガイドの改訂にも対応します（よくある実作業です。ステップ6を参照）。開発者ガイドは、対象であるツールが変化するため、ドキュメントの中でも特に変更の影響を受けやすいものです。

使用する場面

• 開発者ツール製品（SDK、ライブラリ、CLI、フレームワーク、API プラットフォーム）の導入と統合についての説明を作成するとき。
• 開発者に必要な、スタートガイド、主要な概念、統合レシピ、エンドツーエンドのチュートリアル、ベストプラクティス、トラブルシューティングを書くとき。
• ツールの変更（新バージョン、機能の非推奨化・改名・変更）や、レシピ／概念の修正が必要になったとき、既存の開発者ガイドを改訂するとき（ステップ6を参照）。
• 提供された feature-spec と api-reference に基づき、調査済みで実行可能かつ正確な内容を開発者ガイドのテンプレートに記入するとき。

次の場合は有効化しないでください：

• エンドポイント／シンボルごとの網羅的な api-reference カタログを書く場合 → 別のドキュメントです。このガイドでは、リファレンスの内容を説明してリンクします。項目を再掲することはありません。
• 技術者以外のエンドユーザー向け user-guide（製品の操作方法を扱い、コードを含まず、対象読者も異なります）を書く場合 → 作成者は上流の PRD に記載された対象読者を基に選択します。
• 内部向けエンジニアリングドキュメント、つまり api-spec（通信規約）、architecture-doc（システム設計）、data-model（永続化スキーマ）を書く場合。
• 完成した開発者ガイドをレビューまたは評価する場合 → reviewing-developer-guide を使用してください。このスキルは作成側専用です。

入力

計画で指定された依存ドキュメント一式、つまり depends_on セットに含まれるすべてのドキュメントを読み、各ハウツーと概念の根拠をそれらまでたどってください。一般的な上流ドキュメントは参考例であり、固定の上限ではありません。

• 一般的な上流ドキュメント。 feature-spec（ガイドで説明する機能）、api-reference（連携レシピで呼び出すエンドポイント。ツールが API を公開している場合）、PRD（対象読者と提供価値）が一般的です。存在する場合は、user-flows（連携シナリオ）とarchitecture-doc（認証／デプロイの背景）も含めます。渡された api-reference を基にレシピを作成してください。実在するエンドポイントと機能を使います。amend では、既存のガイド、変更リクエスト、変更された上流ドキュメントも渡されます（Step 6）。
• 自己完結性と柔軟な対応。 受け取ったコンテキストがどのようなものであっても、それを基に作成してください。想定される上流ドキュメントがない場合（例：API を持たないライブラリ／CLI には api-reference がない場合）は、手元にある情報に基づいて進め、その不足を明示的な前提として示してください。機能、エンドポイント、コードパスを決して捏造しないでください。
• 網羅性を高めるための調査。 テンプレートを埋めるだけでなく、確立された DX ドキュメント／Diataxis の実践に基づいてガイドを作成するため、deep-research を使用してください。

ワークフロー

Step 1：テンプレートツールから構成を取得する — アウトラインを独自に作成しない

開発者ガイド用テンプレートツールから、包括的なバリアントのセクション構成を取得してください。ここでセクション一覧を再掲したり、再構成したりしないでください。このスキルでは、各セクションを適切に埋める方法を説明します。テンプレートを利用できない場合は、包括的な開発者ガイドの構成を用意してください（依頼して作成するか、標準的な構成を使用します。標準的な構成は、概要／全体像と、明確な導入案内、利用開始、主要な概念、連携方法のガイド、エンドツーエンドのチュートリアル、ベストプラクティス、トラブルシューティング／よくあるエラー、API リファレンスへの案内、ツールのバージョン管理／移行、ドキュメントの変更履歴、未解決の質問です）。その後、作業を進めてください。

Step 2：上流ドキュメントを読み込む。feature-spec と api-reference を基に網羅範囲を決める

渡されたドキュメントを読み込んでください。入力資料であり、白紙の状態から始めるわけではありません。feature-spec に記載された機能を、概念とレシピの網羅性を確認するチェックリストとして使います。レシピで呼び出すのは、api-reference に記載されたエンドポイントです。すべてのレシピとコードサンプルは、上流ドキュメントにある実際の機能／エンドポイントに基づくものとし、API を捏造してはいけません。上流ドキュメントの情報が乏しい、または存在しない場合は、その不足を明示的な前提として示し、エンドポイントを暗黙のうちに捏造しないでください。ツールのアーキタイプ（API プラットフォーム／言語別 SDK／CLI／フレームワーク。ツールが複数に該当する場合もあります）を特定してください。アーキタイプに応じて、ガイド全体の重点が決まります（Step 4）。

Step 3：調査に基づいてガイドを作成する

この製品に適したガイドを作成するため、確立された DX ドキュメントの実践（Stripe／Twilio／Auth0 水準：最初の呼び出しを素早く実現し、実行可能なコードを使い、目的別に構成し、リファレンスより概念を先に説明すること。最初に検証済みの成功を得るまでの手順を最小限にし、初回の呼び出しまでの時間を短縮することを意図します）、Diataxis の4つのモード（正しい種類に分類し、適切に分離すること）、およびこの製品向けの開発者向けドキュメントの品質基準（見つけやすさ／正確性／関連性／明瞭さ／完全性／読みやすさ）に基づいてガイドを作成するため、deep-research を実施してください。調査機能を利用できない場合は、インストールコマンド、エンドポイント、パラメーター、エラー形式を捏造しないでください。検証が必要な前提として明記してください。

Step 4：セクションごとの方法を適用する

この方法に従ってテンプレートの各セクションを埋めてください。情報量の少ないツールに不要なセクションは統合し、製品とそのアーキタイプに応じた分量にしてください。（深さ、品質基準、IA、利用開始、概念については references/structure-onboarding.md を参照してください。ベストプラクティス、トラブルシューティング、アーキタイプ、amend の手順については references/bestpractices-archetype-amend.md を参照してください。）

• エンドポイントではなく、開発者の目標を軸に構成します。 ガイド全体を、開発者が「達成したいこと」（「支払いを受け付ける」など）に沿って構成し、手順レシピにもその名前を付けます。API のシンボル名は使いません。何を構築できるのかを最初に示します。
• 情報設計 — 「まずここから」と、読者の学習順序が分かる構成にします。 入口を明確に示します（全体像 → 最初の成功 → 概念 → レシピ → チュートリアル → ベストプラクティス → トラブルシューティング → リファレンス）。認証と入門を目立つ位置に配置し、相互リンクのルールを統一します。見出しはざっと確認しやすくし、目次は焦点を絞ります。よくある手順を先に示し、応用的な選択肢はリンク先で案内するなど、段階的に複雑さを示します。文章のアクセシビリティにも配慮します。意味のあるリンクテキストを使い（「ここをクリック」は使いません）、図には代替テキストを付け、略語は初出時に定義し、正しい見出し階層を守ります。（見つけやすさは評価基準の最初の項目であり、「明確な入口がない」ことは離脱の主な原因です。）
• 概要／全体像 — ツールが何をするのか、どの課題を解決するのか（2 行）、想定読者と前提条件、主なシナリオ 2～4 件（それぞれのレシピにリンク）、最初に進むべき手順を示します。また、網羅的なリファレンスは別の場所にあり、このガイドからリンクすることを明記します。
• 入門ガイド = すばやく、検証可能な最初の成功。 実際に成功する API 呼び出しを 1 回行う、最小限かつ完結したプログラムを示します。前提条件 → インストール → 認証情報の設定 → 最初の呼び出し → 検証の順に進めます。認証情報の取得元（サインアップからキーを取得するまでの手順、またはダッシュボード上の場所）を説明し、最初の呼び出しにはライブ環境ではなくテスト／サンドボックスモードを使うよう案内します。コードは実行可能で、そのままコピーして使えるようにします。認証情報は環境変数または設定から取得し、コードに直接記述しません。呼び出しでは「Hello, World」のような例ではなく、実際に役立つ値を扱います。最初の成功を検証するまでの手順を最小限に抑えます（TTFC の意図に沿います）。最後に、期待される出力をそのまま示し、最初の呼び出しでよくあるエラーを 2～3 件説明します（より詳しい内容はトラブルシューティングに記載します）。（Diátaxis のチュートリアル）
• リファレンスやレシピより先に、基本概念を説明します。 メンタルモデル（クライアント／リソースオブジェクト、ドメインの用語とその関係、リクエストのライフサイクル（同期／非同期、ウェブフック、冪等性の概念）、環境（テストとライブ））を説明し、パラメーターやレシピの意味を理解できるようにします。（Diátaxis の解説）
• 統合の手順ガイド = すでに概要を把握している読者向けの、目標別でコード中心の、単独で実行できるレシピです。（Diátaxis のハウツー）よくあるシナリオごとに小見出しを設け、それぞれで目標、追加の前提条件、要点を絞った実行可能なコード（関連する行のみ）、成功時の結果、すべてのオプションを参照できるリファレンスへのリンクを示します。カタログを本文に載せることは避けます。分量はツールの実際の機能範囲に合わせます。
• エンドツーエンドのチュートリアル = 小規模ながら実用的なものを、最初から最後まで構築します。（Diátaxis のチュートリアル）セクション 4 の検索用レシピとは分けてください。 ハウツーとチュートリアルを統合すると、ドキュメントが分かりにくくなることが最も多くあります。最後に完成したものと、次に進む先を示します。
• 実際の本番利用に基づいたベストプラクティス（Diátaxis の解説。オプションの羅列ではありません）：認証／シークレット（環境変数またはシークレットマネージャー、最小権限のスコープ、テストキーとライブキー）、エラー処理（再試行可能なエラーと致命的なエラーの型判定）、再試行と冪等性（ジッターを伴うバックオフ、retry-after の尊重、書き込み時の冪等性キー）、ページネーション（自動イテレーターまたはカーソルループ、カーソルを破棄する落とし穴）、レート制限（429、Retry-After）、ツールが送信する場合のウェブフック（署名検証、リプレイ／重複排除、順序）、リソースの適切な管理（クライアントの再利用、プーリング、タイムアウト）。それぞれについて推奨パターンと短いコード例を示します。
• トラブルシューティング／よくあるエラー = 頻繁に起きる、原因を特定できるエラーに対するセルフサービスの手段（入門ガイドで扱う最初の呼び出しのエラーよりも範囲を広げます）。よくあるエラー（認証 401／403、検証 400、レート制限 429、見つからない 404、バージョン不一致）を症状 → 原因 → 解決方法の形でまとめます。ツールにエラーコードがある場合は、エラーコード → 意味 → 解決方法の表を作成します。繰り返し生じる概念上の疑問（テストとライブ、非同期処理のタイミング、冪等性）には、短い FAQ を用意します。分量はツールに見合ったものにします。 小規模なツールであれば、入門ガイドにまとめます。（「行き詰まったときに助けがない」ことは、離脱の主な原因です。）
• 現在のツールに合った正確なコード例。 すべての例は、提供された上流リソースにある実際の機能／エンドポイントを反映します。テスト可能な例（自己完結型で、可能な限り動作するコードを単一の情報源として使用）を作成し、ガイドが対象とするツールのバージョンを明記して、古くなっていないか分かるようにします。バージョン表記は amend の陳腐化チェック（ステップ 6）のためのものであり、新規作成時のゲートで最新性を確認するためのものではありません。サンプルの CI 実行はプロジェクトのパイプライン側で行うもので、ガイドの内容ではありません。ただし、テスト可能なサンプルを作成します。
• API リファレンスへの案内 — リンクで案内し、内容は複製しません。 網羅的なカタログが正確な情報源であり、別の api-reference にあることを明記します。必要に応じて、このガイドの概念やレシピをリファレンスの各セクションに対応付けます。補足リソース（サンプルリポジトリ、サポート、ステータス）を列挙します。
• ツールのバージョン管理と移行 — バージョン管理方式（SemVer／日付ベース）、メジャー／マイナー／パッチの意味、バージョンの固定方法を説明します。非推奨ポリシーとスケジュールを示し、変更履歴にリンクします。メジャーバージョンを上げるたびに、破壊的変更ごとの変更前／変更後を示した移行ノートと、移行手順を記載します。
• ツールの種別に応じて強調点を調整します（分量も適切にします）。 API プラットフォーム → curl と 1 つのプログラミング言語、認証フロー、ウェブフック。言語別 SDK → サポートする各言語の最初の成功とレシピ、クライアントのライフサイクル、慣用的なパターン。CLI → 引数／フラグ、終了コード、stdout／stderr の仕様、非対話型利用／スクリプトでの利用、シェル補完。フレームワーク → スキャフォールディング、規約、ライフサイクルフック。必要な基準はツールの種別に合わせて調整し、すべてのガイドを不必要に肥大化させないようにします。

ステップ 5：引き継ぐ前に、採用しやすさと正確さの基準に照らしてセルフチェックする

以下のすべてを満たしていることを確認します（これは reviewing-developer-guide が定める基準です。作成者とゲートで基準を完全に共有し、食い違いが生じないようにします）。それぞれの基準は適切な範囲で適用します。薄いツールで、必要のない項目が省かれていても問題ありません。

1. 目標を軸に構成されている — 開発者が何を作れるかを中心に説明し、レシピにはエンドポイントではなく目標に基づいた名前を付けます。
2. 最初の成功を検証できるところまで、導入手順を案内している — 前提条件（認証情報の入手先と、テスト／サンドボックスの方法を含む）→ インストール → 認証情報の設定 → 実際の呼び出しの成功 → 期待される出力を示す検証手順。実行可能で、コピーしてそのまま使え、実際に役立つ内容（hello-world ではない）とし、認証情報にはハードコード値ではなく環境変数を使用します。手順は短く、途中で行き詰まらない構成にします（TTFC の意図に沿います）。
3. 主要な概念を、リファレンスやレシピより前に掲載している。
4. 引き継いだ上流資料にある一般的なシナリオを、統合方法の説明で網羅している — 目標を示す名前を付け、コードを中心とし、各説明を個別に読み進めて実行でき、リファレンスへリンクしています。
5. エンドツーエンドのチュートリアルで、小規模でも実用的なものを 1 つ作成している。参照用のレシピとは分けて掲載します。
6. 実際の利用に基づくベストプラクティスを示している — 認証／シークレット、再試行可能なエラーと致命的なエラー、再試行＋べき等性＋バックオフ、ページネーション、レート制限、Webhook（該当する場合）、リソースの適切な管理について、選択肢の羅列ではなく、推奨パターンとスニペットを示します。
7. Diataxis の各モードを正しく分類し、分けている — あるモードの内容が別のモードに混在していません。
8. api-reference へのリンクを掲載し、内容を重複させていない。
9. コードサンプルが実行可能で、実際の／CURRENT なツールに即して正確である — すべてのサンプルが、引き継いだ上流資料にある実際の機能／エンドポイントを反映し、上流の仕様と矛盾していません。対象となるツールのバージョンを明記します。
10. ツールのバージョン管理と移行方法を記載している — バージョニング方式、非推奨化の方針と期間、変更履歴へのリンク、メジャーバージョン更新ごとの変更前／変更後の説明を含めます。
11. 根拠に基づき、内容を捏造していない — 機能／エンドポイント／コードは上流資料に基づいています。不明点は作り上げず、明示的な前提として示します。
12. 反復時の修正が適切な差分になっている — 既存の内容を直接編集し、ツールの変更内容に照らして古いサンプルがないか確認し、内部の整合性を保ち、ガイド自体のバージョンを更新して変更履歴を更新し、置き換えられた内容に印を付けます（ステップ 6）。新規に初めて作成する場合は該当しません。
13. トラブルシューティング／よくあるエラーへの対処方法がある — よくある、原因を特定できるエラーについて、利用者自身で対処できるようにします（症状→原因→解決策）。薄いツールの場合は導入手順に組み込むなど、適切な範囲にします。
14. 見つけやすい — 初めて読む人が、API を知らなくても「まずはこちら」の案内と目的に合ったセクションを見つけられます（入口を明示し、読者の進行に沿った順序にします）。

入力が不十分な場合のゲート： ガイドで説明すべきシナリオについて調査できず、実行可能なレシピとして信頼できる前提を置くこともできない場合は、エンドポイントやコードの経路を捏造せず、ブロッカーとして提示します（「統合シナリオの定義が不十分 — api-reference または製品上の判断が必要です」）。

ステップ 6：既存のガイドを修正する（反復／差分）

開発者ガイドは、最も修正が頻繁に行われるドキュメントです。対象（ツール）が変化するためです。たとえば、新しいバージョン、非推奨になったエンドポイントや名称変更されたエンドポイント、シグネチャの変更、新しい認証フローなどがあります。修正は上流の変更に起因する内部的なもので、派生ドキュメントへの下流影響はありません（ガイドは末端に位置し、利用者は開発者自身のインテグレーションに限られます）。修正時（既存のガイド、変更依頼、変更された上流情報を受け取った場合）は、次の手順に従います。

1. 変更範囲を定めます。 この差分が対象とするもの（対象となるツールのバージョンと、該当するレシピ／サンプル／概念／手順）と、意図的に変更しないものを明示します。
2. その場で編集します。影響を受けるブロックのみを変更し、ガイド全体を再生成しないでください（出典情報が失われ、正確なままの未変更サンプルを壊すおそれがあります）。
3. 上流変更に起因する陳腐化を一掃します。変更または削除された機能に言及しているガイド内のすべての箇所（サンプル、レシピ、概念、Getting Started の呼び出し、API リファレンスへのポインター）を見つけ、現在のツールに合わせてそれぞれ正確な内容に更新します。削除または名称変更された機能を呼び出すサンプルを残すことは、修正において最も重大な欠陥です（陳腐化による捏造にあたります）。
4. 内部の一貫性を保ちます。概念をレシピより先に説明する構成を維持し、エンドツーエンドのチュートリアルが引き続き実行できるようにします。レシピが（変更された可能性のある）概念セクションと矛盾しないようにし、最初の成功を引き続き確認できるようにします。
5. ガイドのドキュメントにバージョンと変更履歴を記録します。ガイド独自のバージョンを上げます（ツールのバージョンやスキルのセマンティックバージョニングとは別です）。変更履歴の行（誰が／いつ／何を変更したか／理由。例：「SDK v3 に対応するため更新 — Client(key=) → Client.from_env()」）を追加します。
6. 置き換えられた内容や非推奨の内容を明示します。黙って削除するのではなく、バージョンと置き換え先を記載し、古いバージョンを使い続ける開発者が手順を確認できるようにします。

ルール

厳守事項（絶対に違反しないこと）：

• 説明を加え、api-referenceにリンクすること。カタログを再構成してはなりません。 詳細なオプションはapi-referenceを参照してください。ガイド内でパラメーター、型、エラーを再列挙してはいけません。
• Getting-startedでは、検証可能な初回成功まで導くこと。 実際の呼び出しを1回成功させるまでの、すばやく実行でき、コピー＆ペースト可能な手順を示し、最後に検証手順を設けてください。認証情報はハードコードせず、環境変数または設定ファイルから取得します。認証情報の入手先を示し、テスト環境／サンドボックスの利用を促してください。
• リファレンスより先に概念を説明すること。 レシピやリファレンスの前に、基本的な考え方を説明してください。
• エンドポイント別ではなく、目的別に構成すること。 最初に読むべき箇所を明示してください。
• Diataxisの各モードを適切に分類し、混在させないこと。 チュートリアルにリファレンスを詰め込まず、レシピに概念を埋め込まず、ハウツーとチュートリアルを融合させないでください。
• コードサンプルは実行可能で、現在のツールに即した正確なものにすること。 上流が示していない機能のサンプルは決して載せず、対象とするツールのバージョンを明記してください。
• トラブルシューティングは、ユーザー自身で解決できる範囲に見合った手順にすること。 よくある、把握可能なエラーをそれぞれ修正方法に結び付けてください。機能の少ないツールに「トラブルシューティング」という名前のセクションを無理に設けず、Getting-startedに組み込んでください。
• 既存の内容をその場で修正し、古くなった情報を一通り確認すること。 ツールに変更があったら、古くなったサンプル、レシピ、参照先をすべて探して修正し、ガイドのバージョンと変更履歴を更新し、置き換えられた内容にはその旨を記してください。ガイド全体を再生成してはいけません。
• 捏造しないこと。 エンドポイント、機能、インストールコマンド、コードパスを作り上げてはいけません。情報源がない場合は、明確に「仮定」と記したうえで示してください。
• 提供された上流資料を活用すること。白紙から始めず、入力を1つだけに固定しないこと。 想定される上流資料がない場合（たとえば、API以外のツールにapi-referenceがない場合）は、手元にある情報を使って作成し、不足があることを仮定として明記してください。
• 重複させず、組み合わせること。 セクション構成はテンプレートツールに従い、このスキルはその構成を埋めるための手法として使ってください。
• カタログではなく、エンドユーザー向けヘルプでもなく、エンジニアリング文書でもなく、説明的な文章にすること。

望ましい方針（必要に応じて変更可能）：

• 「包括的」は、出力の目標水準を示します。ツールとその種類に応じた適切な分量を保ってください。機能の少ないCLIではレシピをまとめ、概念の説明を簡潔にし、トラブルシューティングをGetting-startedに組み込みます。幅広いAPIプラットフォームでは、レシピ、Webhook、トラブルシューティング、移行に関する注記を充実させます。重視するのは文章量ではなく、初回成功と、本番環境で正しく連携できることです。
• ツールが複数のSDKを提供している場合は、複数言語のサンプルを優先してください（言語ごとに初回成功までの手順を用意）。APIの場合は、curlと少なくとも1つの言語を優先してください。
• 推奨パターンとして、カーソルベースのページネーションとジッターを加えたバックオフリトライを優先し、網羅的なオプションはリファレンスに委ねてください。

注意点

• ガイド内で API リファレンスを再掲載する。 シナリオを説明し、目的を絞ったレシピを示して、すべてのオプションについてはリンク先に案内します。
• Hello World 形式の入門ガイドにする。 最初の成功体験では、実際の価値に到達し、検証可能な確認も行う必要があります。そうでなければ、読者は自信を得られません。
• サンプルに認証情報をハードコードする。 セキュリティ上のアンチパターンを教えることになり、読者の環境では動作しません。毎回、環境変数または設定から読み取ってください。
• 明確な「ここから始める」がない。 説明もなくエンドポイントから始まるガイドは途中で読まれなくなります。入口を示し、学習の順序を案内してください。
• ハウツーとチュートリアルの区別が曖昧。 Diataxis で最もよくある失敗です。セクション 4 のレシピは参照用として保ち、チュートリアルは一つのビルドを導く内容にしてください。
• リファレンス資料をチュートリアルに持ち込む。 各ステップに必要なことだけを説明し、残りはリンクしてください。
• ツールの移行後にサンプルが古くなる。 最もよくあるメンテナンス上の失敗です。ツールを変更するたびに、削除または改名された機能がないか、すべてのサンプルとレシピを確認してください（ステップ 6）。古いサンプルは一見問題なく読めても、実行すると壊れます。
• 一般的なデバッグの助言を並べるトラブルシューティングセクション。 「ログを確認してください」ではなく、そのツールで頻繁に起きる、把握可能なエラーと具体的な解決策を対応させてください。
• 上流の情報が不足しているときに、エンドポイントや機能を捏造する。 代わりに、その不足を前提条件として明示してください。
• テンプレートの構成をそのまま言い換える。 各セクションは判断を加えて埋めてください。

対比例 — 一般的（もっともらしく見える） vs 採用可能（自己確認に使ってください）：

観点	一般的（却下）	採用可能（公開できる）
入門ガイド	「SDK をインストールして、呼び出しを実行します。」	「1. pip install acme を実行します。2. Dashboard → API keys から TEST キーを取得します。3. export ACME_KEY=... を実行します。4. チャージを作成する 6 行のスニペットを実行します。5. 期待される結果：{\"id\": \"ch_...\", \"status\": \"succeeded\"}。401 が返る場合はキーが誤っています → トラブルシューティングを参照してください。」
概念	「SDK にはクライアントがあります。」	「Client はキーと接続プールを保持します。インスタンスを一つ作成して再利用してください。各ドメイン名詞（Charge、Customer）は、クライアントを通じて操作するリソースです。」
レシピ	「メッセージを送信するメソッドがあります。」	「SMS を送信する — client.messages.create(to=..., body=...)。sid を持つ Message が返されます。すべてのパラメーター（メディア、スケジュール設定など）についてはリファレンスを参照してください。」
リファレンス（重複ではなくリンク）	ガイドに 40 個すべてのエンドポイントとパラメーター表を再掲載する	「エンドポイントごとのすべてのパラメーター、型、エラーはAPI リファレンスに記載されています。これが信頼できる情報源です。このガイドからは該当箇所にリンクします。」
トラブルシューティング	「動作しない場合はデバッグしてください。」	「429 Too Many Requests → レート制限に達しました。待機時間を置き、Retry-After に従ってください（ベストプラクティスを参照）。」
改訂	SDK v3 用にガイド全体を再生成する	該当するサンプルを編集し、すべての Client(key=) を Client.from_env() に置き換え、ガイドのバージョンと変更履歴を更新し、v2 のレシピに後継版があることを明記する
コードの正確性	API リファレンスに記載されていないエンドポイントを呼び出す	すべての呼び出しで、提示された API リファレンスまたは機能仕様に定義されたエンドポイントや機能を、記載されたツールのバージョンに対して使用する

記入した内容が左の列のようになっているなら — どのツールにも当てはまるだけで、実行可能な最初の成功体験も、実質的な概念もなく、カタログを貼り付けただけで、入口の案内もなく、ツールの現行バージョンに対応していないなら — まだ完成していません。

アンチパターン

• 「ガイドを完全にするため、すべてのエンドポイントを列挙します。」 それは api-reference の役割です。流れを説明して、リンク先を案内します。
• 「Hello-world は最初の呼び出しとして問題ありません。」 実際に価値のあることを行い、動作を検証します。
• 「サンプルを短くするため、キーをハードコードします。」 環境変数から読み込みます。
• 「レシピとチュートリアルは同じものです。」 Diataxis のモードが異なるため、分けておきます。
• 「これは user-guide でもあるので、技術に詳しくないユーザー向けに書きます。」 対象読者もドキュメントも異なります。
• 「api-reference の内容が薄いので、エンドポイントを創作します。」 その不足を仮定として明示します。
• 「ツールが v3 をリリースしたので、ガイドを再生成するだけです。」 その場で修正し、古くなったサンプルをすべて確認します。バージョンと変更履歴を更新し、旧版であることを明記します。
• 「調査は省きます。SDK の仕組みはわかっています。」 調査は、この製品の機能、シナリオ、規約を理解するための土台になります。
• 「アウトラインは自分で作成します。」 テンプレートツールと重複するため、その構成を使います。

出力

Step 5 の採用しやすさと正確性の基準を満たす包括的な開発者ガイド（目標別に構成され、「ここから始める」案内があること。getting-started で検証可能な最初の成功に到達できること。リファレンスの前に概念を説明すること。統合方法のガイドで引き継いだシナリオを網羅すること。エンドツーエンドのチュートリアルで実用的な小さなものを作ること。ベストプラクティスに根拠があること。過不足のないトラブルシューティング手順があること。Diataxis のモードが正しく分類され、分けられていること。api-reference と重複させず、リンクで案内すること。サンプルが実行可能で、現在のツールに即して正確であること。ツールのバージョン管理と移行について記載すること。修正時にはガイド自体のバージョンと変更履歴を維持すること。何も捏造しないこと）。成果物はテキスト形式です。番号付きのセットアップ手順、コードフェンスで囲んだインストールコマンド、コードフェンスで囲んだ統合コードサンプル（API を扱う場合は curl と 1 つ以上の言語）、画面やフローの文章による説明を含みます。手法と基準は媒体に依存しません。想定する読者は、ツールを採用し統合する開発者と、同じ 14 項目の基準を検証する reviewing-developer-guide です。このガイドは、引き継いだ上流資料（通常は feature-spec、api-reference、PRD）を利用し、下流の api-reference にリンクします。ガイドの構成はテンプレートツールから得られ、このスキルはコンテンツの品質を担います。

関連項目

• 開発者ガイドのテンプレートツール（例：content-template-gateway）— このスキルが内容を埋めるためのセクション構成を提供します。組み合わせて使い、アウトラインを繰り返してはいけません。
• 深掘り調査の機能 — DX ドキュメントの実践例（Stripe／Twilio／Auth0）、Diataxis、開発者向けドキュメントの品質基準を踏まえます。
• reviewing-developer-guide — 実行時のゲートです。完成したガイドが、同じ 14 項目からなる採用しやすさと正確性の基準を満たしているか検証します。作成者とゲートが同じ基準を共有することで、基準のずれを防ぎます。
• api-reference 作成スキル — このガイドが説明し、リンクで案内する、網羅的なエンドポイント／シンボルのカタログを作成します。再導出はしません。
• user-guide 作成スキル — 技術に詳しくないエンドユーザー向けの製品ヘルプです。このスキルとは対象読者もドキュメントも異なります（制作者は PRD の対象読者に応じて選択します）。
• feature-spec（説明する機能）、api-reference（レシピで利用するエンドポイント）、PRD（対象読者と価値）— 一般的な上流入力資料です。存在する場合は、user-flows と architecture-doc も含みます。

プログレッシブディスクロージャー

• references/structure-onboarding.md — 構造とオンボーディングの観点を深掘りします。開発者向けドキュメントの品質基準とDiataxisのモード、情報アーキテクチャ／最初に読むページ／読者の導線、スキャンのしやすさ／プログレッシブディスクロージャーと基本的なアクセシビリティ、6ステップのスタートガイド＋TTFC＋認証情報の取得／サンドボックス、レシピより先に概念を説明することを扱います。
• references/bestpractices-archetype-amend.md — 本番運用と変更の観点を深掘りします。ベストプラクティス集（認証／エラー／再試行／ページネーション／レート制限／Webhook／リソースの適切な管理）、症状→原因→解決策のトラブルシューティング手法、4つのツール類型ごとの補足、ドキュメントをコードとして扱い鮮度を保つ習慣、古くなった情報を洗い出す修正手順（Step 6）を扱います。
• references/sources.md — 手法と品質基準の調査出典です（Diataxis、DXドキュメント／情報アーキテクチャの実践、開発者向けドキュメントの品質基準、SDK／APIドキュメント、エラー処理、再試行／冪等性、ページネーション、レート制限、トラブルシューティング、バージョン管理／移行、ドキュメントをコードとして扱うこと／継続的に更新するドキュメントに関する指針）。指針の出典を確認する場合のみ読み込みます。

本文の上限

• description は1,024文字以下です（agentskills.ioの上限）。
• 本文は約500行／5,000トークン以下です。
• 詳細な内容は references/ に置き、必要に応じて読み込みます。