AI Prompt Engineering · レッスン

技術ドキュメントのプロンプト

Q: 「技術ドキュメントのプロンプト」で何を学びますか？

正確な技術文体で README ファイル、API ドキュメント、ハウツーガイドを作成するプロンプトを学びます。 ブラウザで直接実行するハンズオンコードでAI Prompt Engineeringを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

正確な技術文体で README ファイル、API ドキュメント、ハウツーガイドを作成するプロンプトを学びます。

「技術ドキュメントのプロンプト」はCoddyKit上の無料AI Prompt Engineeringレッスンです。これはレッスン3/4です。下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。これはAI Prompt Engineering学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 AI Prompt Engineeringコースには全4レッスンが含まれています。

技術文書は1つのジャンルです

技術文書は、独自の慣習を持つ明確な文章ジャンルです。文体より正確さ、物語性より構成、簡潔さより網羅性が重視されます。ブログ記事やメールに適したプロンプトでは、技術文書にふさわしくない文体が生成されます。

効果的な技術文書用プロンプトでは、文書の種類、想定する読者の知識レベル、その文書の種類における標準的な構成、文体の慣例を明示します。文体は通常、操作手順のガイドでは二人称、リファレンス文書では三人称を使います。

READMEファイル用プロンプト

READMEは、プロジェクトへの入口です。標準的な構成が確立されています。効果的なREADME用プロンプトでは、各セクションを指定します。

プロジェクト名と1行の説明
何をするものか：目的を2～3文で説明
前提条件：インストールしておく必要があるもの
インストール：コマンドを含む番号付きの手順
クイックスタート：最小限の動作例
設定：環境変数とオプション
コントリビューション：PRを提出する方法
ライセンス

プロンプトですべてのセクション名を示すと、完全なREADMEが生成されます。明示的に指示しなければ、記載されていないセクションは省略されます。

コードによるREADME用プロンプト

プロジェクトのメタデータを受け取る、構造化されたREADME生成プロンプトです。

import openai

client = openai.OpenAI(api_key='sk-...')

def generate_readme(project_name, description, language, dependencies,
                    install_steps, quick_start_example, config_vars, license_type):

    prompt = f'''Write a README.md for the following project.

Project name: {project_name}
Description: {description}
Language/stack: {language}
Dependencies: {dependencies}
Installation steps: {install_steps}
Quick start example: {quick_start_example}
Key configuration variables: {config_vars}
License: {license_type}

Structure the README with these sections in order:
1. Project title and badge line (GitHub stars, license)
2. One-sentence description
3. Features (3-5 bullet points)
4. Prerequisites
5. Installation (numbered steps with code blocks)
6. Quick Start (minimal working example in a code block)
7. Configuration (table: Variable | Description | Default)
8. Contributing (2-3 sentences)
9. License

Voice: second person imperative for steps ("Run...", "Install...").
Code blocks: use correct language identifiers.
Do not add placeholder content — only include sections where I provided information.'''

    response = client.chat.completions.create(
        model='gpt-4o-mini',
        messages=[{'role': 'user', 'content': prompt}]
    )
    return response.choices[0].message.content

APIドキュメント用プロンプト

APIドキュメントには、厳密な構成があります。各エンドポイントの項目には、HTTPメソッド、パス、説明、パラメーター、リクエストボディ、レスポンス形式、エラーコード、例が必要です。プロンプトでは、これらをすべて指定する必要があります。

「RESTエンドポイントのAPIドキュメントを書いてください。次の内容を含めてください：メソッド（POST）、パス（/api/v1/users）、説明、パラメーター表（名前、型、必須かどうか、説明）、リクエストボディのJSON例、成功時のレスポンス（200）のJSON例、エラー時のレスポンス（400、401、422）とそのJSON例。文体：三人称、現在形。パラメーターにはMarkdownの表を使ってください。」

各構造要素を明示的に指定する必要があります。モデルがドキュメントの標準を推測してくれることはありません。

ハウツーガイド用プロンプト

ハウツーガイドは手順に沿って進める形式です。読者を状態A（問題）から状態B（解決策）へ、番号付きの手順で導きます。ハウツーガイド用プロンプトに含める要素：

前提条件：開始前に満たしておく必要がある条件
到達点：読者が達成できること
手順：番号付きで、1つの手順につき1つの操作のみを記載すること。複数の操作を1つの手順に含めない
コード例：必要に応じて各手順に1つ記載し、使用言語を明記すること
検証：各手順が成功したことを読者が確認する方法
トラブルシューティング：特に難しい2〜3個の手順で起こりやすい失敗とその対処法

ドキュメント用プロンプトの技術的な正確性

技術文書には、ほかの多くのコンテンツよりも高い正確性が求められます。ドキュメント用プロンプトの正確性を高める方法を2つ紹介します。

実際のコードを提示する：実際の関数シグネチャ、設定項目、API仕様を貼り付けます。モデルが詳細を創作するのではなく、実際に存在するものを文書化できるようになります。

検証手順を依頼する：「各手順を書いた後に、ユーザーの環境またはシステムの動作について置いている前提を記載してください。公開前に確認すべき点には印を付けてください。」

AIが生成したドキュメントを、技術レビューなしで使用してはいけません。モデルは、存在しない内容や誤った内容でも、自信を持って文書化してしまいます。

ドキュメントのコード例の品質

コード例は技術文書で最も重要な要素です。コード例については、明示的に指示してください。

「主要な概念ごとに、動作するコード例を1つ含めてください。例は自己完結型にしてください。読者がコピーして貼り付け、そのまま実行できるようにします。」
「正しい使い方と、よくある間違いの両方を示してください。その間違いで失敗する理由を説明するコメントも追加してください。」
「コード例では、'foo'、'bar'、'test'ではなく、現実的な変数名とデータを使用してください。」
「言語：Python 3.11。型ヒントを使用してください。ネットワーク呼び出しのエラー処理を含めてください。」

コード例について明示的に指示しないと、モデルは実際には実行できない不完全な疑似コードの断片を生成することがあります。

ドキュメントの語り口とスタイル

技術文書には、ほかの種類の文章とは異なる固有の語り口があります。

手順では二人称の命令形：「設定をクリックしてください。APIタブを選択してください。キーを入力してください。」
リファレンスドキュメントでは三人称：「authenticate()メソッドは、24時間有効なBearerトークンを返します。」
現在形：「この関数は返します…」とし、「この関数は返すでしょう…」とはしない
曖昧な表現を避ける：「このコマンドを実行してください」とし、「このコマンドの実行を検討してもよいでしょう」とはしない
用語を統一する：同じ概念には文書全体で同じ用語を使用し、類義語に置き換えない

変更履歴とリリースノート用プロンプト

変更履歴とリリースノートには、プロンプトに組み込むべき定型の形式があります。

「バージョン2.3.0のリリースノートを書いてください。形式：バージョン見出し、リリース日、続いて3つのセクション。『追加』（新機能）、『変更』（既存機能の変更）、『修正』（バグ修正）。各項目は1行で、能動態を使い、動詞で始めてください。対象読者：このライブラリを組み込む開発者。トーン：正確かつ中立的にし、マーケティング表現は使わないでください。変更内容は次のとおりです：[実際の変更内容の一覧]。」

実際の変更内容を入力データとして提供すると、正確性を確保できます。変更内容がなければ、モデルはもっともらしく聞こえる架空のリリースノートを創作してしまいます。

ドキュメントの完全性チェック

技術文書を生成した後、完全性チェック用のプロンプトを実行します。

import openai

client = openai.OpenAI(api_key='sk-...')

def check_documentation_completeness(doc_text, doc_type='how-to guide'):
    checklist = {
        'how-to guide': [
            'Prerequisites stated?',
            'Expected outcome stated?',
            'Each step is a single action?',
            'Code examples included where relevant?',
            'Validation step for each major action?',
            'Common errors addressed?'
        ],
        'readme': [
            'One-line description present?',
            'Installation steps numbered with commands?',
            'Quick start example included?',
            'Configuration variables documented?',
            'License specified?'
        ]
    }

    items = checklist.get(doc_type, [])
    check_prompt = f'Review this {doc_type} and answer each question (Yes/No + brief note):\n'
    for item in items:
        check_prompt += f'- {item}\n'
    check_prompt += f'\nDocument:\n{doc_text[:2000]}'

    response = client.chat.completions.create(
        model='gpt-4o-mini',
        messages=[{'role': 'user', 'content': check_prompt}]
    )
    return response.choices[0].message.content

さまざまな読者に向けた専門用語の翻訳

技術文書は、技術に詳しい読者と詳しくない読者の両方を対象にすることがよくあります。実用的なプロンプトのパターンを紹介します。

「このドキュメントを2層構成で書いてください。第1層は、技術に詳しくない読者向けの3文の概要（何をするものか、なぜ重要か、いつ使うか）にしてください。第2層には、完全な技術仕様を記載してください。2つの層の間には、明確な視覚的区切りを入れてください。これにより、技術に詳しくない管理職は概要だけを読んで止めることができ、技術者は概要を飛ばして仕様を読めます。」

1つの文書で両方の読者に不十分に対応しようとするよりも、2層構成のドキュメントのほうが役立ちます。

理解度チェック：技術文書用プロンプト

50個のエンドポイントのAPIドキュメントを生成するプロンプトを書いています。最も重要な品質要件は、モデルがAPIについて想像した内容ではなく、APIが実際に行うことをドキュメントに正確に反映させることです。正確性を確保するには、どの方法が最適でしょうか。

まとめ：技術文書用プロンプト

技術文書は、正確さ、構成、そして手順では二人称の命令形を必要とする独立したジャンルです。効果的なプロンプトでは、ドキュメントの種類、必要なセクション名、コード例の要件（自己完結型、現実的な変数名、言語バージョン）、文書の語り口の規則を指定します。

正確性を確保するための最も重要な方法は、実際のコード、API仕様、または設定データを必ず入力として提供することです。モデルに技術的な詳細を創作させてはいけません。AIが生成したドキュメントを公開する前に、必ず人間による技術レビューを行ってください。

最後のレッスンでは、創作およびストーリーテリングのコンテンツにプロンプト技法を適用します。

よくある質問

「技術ドキュメントのプロンプト」レッスンは無料ですか？

はい。「技術ドキュメントのプロンプト」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、AI Prompt Engineeringコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 AI Prompt Engineeringコースには全4レッスンが含まれています。

「技術ドキュメントのプロンプト」で何を学びますか？

正確な技術文体で README ファイル、API ドキュメント、ハウツーガイドを作成するプロンプトを学びます。ブラウザで直接実行するハンズオンコードでAI Prompt Engineeringを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

AI Prompt Engineeringを始めるのに経験は必要ですか？

事前経験は必要ありません。CoddyKitのAI Prompt Engineeringは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。これはレッスン3/4です。

「技術ドキュメントのプロンプト」レッスンにはどのくらい時間がかかりますか？

ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。

このAI Prompt Engineeringレッスンでコードを書いて実行できますか？

はい。すべてのAI Prompt Engineeringレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。

このコースのすべてのレッスン

← AI Prompt Engineeringに戻る