dev-guide-generator

Dev Guide Generator

1 つのトピック → 完全な技術チュートリアル：体系化された SOP ワークフローを通じて、技術トピックを、前提条件、環境構築、主要な手順、よくあるエラーのトラブルシューティング、応用トピックを網羅した包括的なチュートリアルに変換します。チートシートも付属します。

クイックスタート

ユーザーが技術トピックまたは作業目標を提示するだけで、エージェントが次のワークフローに従って完全なチュートリアルを自動生成します。

User: Help me write a Docker beginner's tutorial
Agent: [Outputs complete technical tutorial + Cheatsheet following the SOP workflow]

SOP ワークフロー

フェーズ 1：トピックの範囲設定と対象読者の分析

目標：チュートリアルの技術的な主題、対象読者、範囲の境界を定義します。

手順：

1. トピックを解析する：ユーザーの入力から、中心となるテクノロジー、作業目標、期待される成果物を特定します
2. 確認の質問をする（重要な質問を最大 4 つ）：
   • 対象読者の技術レベルはどの程度ですか？（完全な初心者／多少の経験あり／経験豊富な開発者）
   • 読者はどのオペレーティングシステムを使用しますか？（macOS／Windows／Linux／いずれでも可）
   • チュートリアル完了後、読者は何ができるようになる必要がありますか？（具体的な成果物）
   • バージョンや技術スタックに関する制約はありますか？
3. ユーザーが確認を省略するよう求めた場合、次のデフォルトの前提で進めます：
   • 対象読者：基本的なプログラミング経験はあるものの、対象技術には不慣れ
   • 環境：macOS と Linux の両方を対象とし、必要に応じて Windows との違いを記載
   • 目標：最小限の動作する例を自力で完成できる

出力：チュートリアルのメタデータ概要（トピック、対象読者、目的、範囲を 150 語以内で記載）

---

フェーズ 2：前提条件

目標：チュートリアルを始める前に必要な知識とツールをすべて列挙し、知識の不足がないようにします。

手順：

1. 依存関係の分析：

   • チュートリアルに関係する技術的な概念をすべて列挙します
   • 各概念について、「チュートリアル内で説明する」か「事前知識として想定する」かを判断します
   • 判断基準：説明によって本題から 200 語以上脱線する場合は、前提条件として分類します

2. 前提条件のチェックリスト：

   • 「必須の知識」と「知っていると役立つ知識」の段階に分類します

   • 各項目に「必要な理由」を 1 行で添えます

   • 次の形式を使用します：

     **必須の知識**：
     - [概念]：[必要な理由]（推奨リソース）
     
     **知っていると役立つ知識**：
     - [概念]：[チュートリアルのどの部分に関係するか]
     

3. セルフチェックのルール：

   • 前提条件が 5 項目を超える場合は、チュートリアルの範囲を狭めるか、複数回に分けることを検討します
   • すべての前提条件に、一般公開されている学習リソースを用意する必要があります

出力：段階別の前提条件チェックリスト

---

フェーズ 3：環境のセットアップ

目標：再現可能な環境設定手順を用意し、読者が主要な手順を始める前にセットアップを完了できるようにします。

手順：

1. 環境の確認：インストールまたは設定するツールを、推奨バージョンとともにすべて列挙します

   • 形式：ツール名 バージョン要件（例：>= x.y）| 用途
   • 「必須」と「任意」のインストールを明確に区別します

2. インストール手順：各 OS のコマンドを示します

   • 各コマンドの前に、その処理内容を説明する一文を記載します

   • 公式に推奨されている方法、または一般的なパッケージマネージャーのみを使用します

   • 形式：

     **macOS**:
     # xxx をインストール（Homebrew を使用）
     brew install xxx
     
     **Linux (Ubuntu/Debian)**:
     # xxx をインストール（apt を使用）
     sudo apt update && sudo apt install -y xxx
     

3. 環境の検証：各ツールのインストール後に、検証コマンドと想定される出力を示します

   • 形式：

     # インストールを検証
     xxx --version
     # 想定される出力：xxx x.y.z
     

4. セルフチェックのルール：

   • すべてのインストールコマンドは、公式ドキュメントまたは一般的なパッケージマネージャーから取得します。サードパーティのスクリプトは使用しません
   • 実際の API キー、パスワード、トークン、その他の機密情報は記載しません
   • 設定ファイルを扱う場合は、プレースホルダー（例：YOUR_API_KEY）を使用し、実際の値の取得方法を説明します

出力：OS ごとのインストールおよび設定ガイドと検証コマンド

---

フェーズ 4：主要な手順

目標：各手順を個別に検証できるように、段階的な構成で主要な操作を説明します。

手順：

1. 手順の計画：

   • 一連の操作を 5～10 個の手順に分割します（各手順では 1 つのサブ目標に焦点を当てます）
   • 依存関係に従って、手順を厳密に順序付けます
   • 各手順には、手順番号、タイトル、目的の説明を含めます

2. 手順の記述形式：

   #### Step N: [Step Title]
   
   **Objective**: [What state is achieved after this step]
   
   **Actions**:
   [Code block or operational instructions]
   
   **Explanation**:
   - [Line-by-line or section-by-section explanation of key parts]
   
   **Verification**:
   [What command to run / what result to check to confirm success]
   Expected output: [Specific expected result]
   

3. 記述ガイドライン：

   • コードブロックには言語を指定します（例：bash、python）
   • プレースホルダーには ALL_CAPS_WITH_UNDERSCORES 形式を使用します（例：YOUR_PROJECT_NAME）。初めて登場する箇所で説明します
   • 各コードブロックは 30 行を超えないようにします。長くなる場合は、セクションに分けて説明します
   • 相対ファイルパスを使用し、冒頭でプロジェクトルートディレクトリを明記します
   • すべての手順の最後に検証セクションを設けます

4. 段階的な複雑さ：

   • 手順 1～3：最小限の実行可能な例（Hello World レベル）
   • 中盤の手順：実用的な機能を段階的に導入します
   • 最後の 1～2 手順：すべてを組み合わせた完全な例にします

出力：操作、説明、検証を含む番号付きの手順リスト

---

フェーズ 5：トラブルシューティング

目標：読者が遭遇する可能性のある問題を予測し、エラーメッセージから解決策に直接たどり着けるようにします。

手順：

1. エラーの収集：技術的なトピックに基づいて、最もよくある 5～8 個のエラー状況を列挙します

   • 情報源：環境設定の誤り、バージョンの非互換性、権限の問題、入力ミス、ネットワークの問題など

2. エントリーの形式：

   **Error N: [Error message summary]**
   
   Full error message:
   [Actual error output]
   
   Cause: [One-sentence explanation of why this error occurs]
   
   Solution:
   [Specific fix commands or steps]
   
   Verify the fix:
   [What to run to confirm the issue is resolved]
   

3. 記述ガイドライン：

   • エラーメッセージは実在するものを使用します（捏造しないでください）
   • 解決策は実行可能な手順にします。「設定を確認してください」のような曖昧なアドバイスは避けます
   • 1 つのエラーに複数の原因が考えられる場合は、可能性の高い順に列挙します
   • 権限に関する問題では、安易に sudo や chmod 777 を勧めるのではなく、その権限が必要な理由を説明します

4. セルフチェックのルール：

   • セキュリティ上のリスクにつながる可能性のある操作（例：chmod 777、ファイアウォールの無効化）は、解決策に含めません
   • 問題を「解決」するためにセキュリティ機能を無効にするよう、読者に決して勧めません

出力：構造化されたトラブルシューティング表

---

フェーズ 6：高度なトピック

目標：基礎を終えた読者に次のステップを示し、初級から上級へ進むための学習パスを提供します。

手順：

1. 高度なトピックの推奨（3～5 個の分野）：

   • 各分野について、どのようなものか、学ぶ価値がある理由、適用できるシナリオを短い段落で説明します

   • 難易度を付記します：中級／上級

   • 書式：

     **分野 N：[トピック名]** | 難易度：[中級／上級]
     
     [短い段落]
     
     推奨リソース：
     - [リソース名]（[種類：ドキュメント／書籍／コース]）
     

2. 実践プロジェクトの提案：

   • 学んだ内容を使って、読者が自力で完了できる小規模なプロジェクトを 2～3 個提示します
   • 各プロジェクトには、プロジェクト名、1 文での説明、関連する概念を含めます

3. ベストプラクティスのヒント（3～5 項目）：

   • 本番環境とチュートリアル環境の主な違い
   • セキュリティ上の考慮事項
   • パフォーマンス最適化の方針

出力：高度な学習ロードマップ＋実践プロジェクトの提案＋ベストプラクティス

---

フェーズ 7：チートシート

目標：チュートリアルの要点を、日常的に使える 1 ページのクイックリファレンスにまとめます。

手順：

1. チートシートの構成：

   # [Technology Name] Cheatsheet
   
   ## Environment Info
   | Item | Command/Path |
   |------|--------------|
   | Install | `command` |
   | Version check | `command` |
   | Config file location | `path` |
   
   ## Common Commands
   | Action | Command | Description |
   |--------|---------|-------------|
   | xxx    | `xxx`   | xxx         |
   
   ## Common Code Snippets
   [Up to 5 frequently used code snippets, each no more than 10 lines]
   
   ## Quick Troubleshooting
   | Symptom | Possible Cause | Quick Fix |
   |---------|---------------|-----------|
   | xxx     | xxx           | `xxx`     |
   

2. 執筆ガイドライン：

   • チートシート全体が印刷した A4 用紙 2 ページ以内に収まるようにします
   • コマンドはすべて、完全な状態でコピー＆ペーストして使えるようにします
   • 説明文は含めず、「何をするか → どうするか」の対応関係だけを記載します
   • 項目は使用頻度の高い順に並べます

出力：1 ページのチートシート

---

フェーズ 8：ドキュメントの組み立てと出力

目標：前の 7 つのフェーズの出力を組み立て、完全なチュートリアルドキュメントを作成します。

チュートリアルドキュメントのテンプレート：

# [Technical Topic] Complete Tutorial

> Last updated: [Current date] | Applicable version: [Version number]
> Difficulty: [Beginner/Intermediate/Advanced] | Estimated time: [N hours/minutes]

## Tutorial Overview

[Phase 1 metadata summary — what the reader will be able to do after completion]

## 1. Prerequisites

[Phase 2 prerequisites checklist]

## 2. Environment Setup

[Phase 3 installation and configuration guide]

## 3. Core Steps

[Phase 4 numbered step list]

## 4. Troubleshooting

[Phase 5 troubleshooting table]

## 5. Advanced Topics

[Phase 6 advanced roadmap and hands-on projects]

## 6. Cheatsheet

[Phase 7 cheatsheet]

## Appendix

- Glossary (if domain-specific terminology is used, list in a table: Term | Definition)
- Reference links (official documentation, community resources, etc.)

ドキュメントの出力要件：

• すべてのコードブロックで言語を指定します
• すべてのコマンドは、そのままコピー＆ペーストして実行できるようにします（行番号、プロンプト、その他の不要な情報は含めません）
• すべてのプレースホルダーは YOUR_XXX 形式を使用し、初出時に説明します
• 設定ファイルに実際のキーやトークンを含めてはいけません
• 日付には実際の現在の日付を使用します

---

フロー制御ルール

対話モードの選択

ユーザーの入力の詳細度に応じてモードを選択します。

ユーザーの入力	モード	動作
技術名のみ（例：「Docker チュートリアル」）	ガイドモード	フェーズ 1 の質問を実行し、続行する前に回答を待ちます
具体的な目標（例：「Docker で Node.js アプリをデプロイする」）	セミオートモード	手順を同時に計画しながら、重要な質問を 1～2 個尋ねます
詳細な説明（対象者、環境、目標を含む）	フルオートモード	フェーズ 2 から直接出力を開始します
ユーザーが「そのまま書いて／質問しないで」と言う	クイックモード	デフォルトの想定に基づいて、チュートリアル全体を出力します

品質チェックリスト

最終的なチュートリアルを出力する前に、各項目を確認します。

• 前提条件のチェックリストが完全で、知識の抜けがない
• 環境設定の各コマンドに確認手順がある
• すべての主要な手順に「操作＋説明＋確認」が含まれている
• 手順の依存関係が正しい（まだインストールされていないツールを使用する手順がない）
• 具体的で実行可能な解決策を含む、よくあるエラーが少なくとも 5 つある
• リソースの推奨を含む高度な分野が少なくとも 3 つある
• チートシートが自己完結しており、よく使うコマンドとトラブルシューティング情報が含まれている
• すべてのコードブロックで言語が指定されている
• ハードコードされたキー、トークン、個人用パスがない
• セキュリティ上の脆弱性を招く可能性のある提案（例：chmod 777）がない
• 有料 API やサブスクリプション限定のツールに依存していない（そのツール自体がチュートリアルの対象である場合を除く）

反復的な改善

ユーザーがチュートリアルに関するフィードバックを提供した場合:

1. そのフィードバックがどのフェーズに関連するかを特定します
2. そのフェーズから再実行します
3. すべての下流のコンテンツに更新を連鎖させます（たとえば、環境の変更は後続のステップやチートシートにも反映させる必要があります）
4. ステップ番号の連続性を維持します

ユースケース

このチュートリアルジェネレーターは、以下の種類の技術チュートリアルに適しています:

• ツールの使用方法: Git、Docker、Kubernetes、Vim などのツールのチュートリアル
• 環境構築: 開発環境、CI/CD パイプライン、サーバー設定など
• プログラミング入門: 言語の入門、フレームワークのクイックスタート、ライブラリの使用方法など
• 運用マニュアル: デプロイ、監視、ログ記録、バックアップと復元など
• データ処理: データベース操作、ETL ワークフロー、データ分析ツールの使用方法など