重要なポイント
- すべての本番Promptは最低限ワンライナーカード（目的、モデル、日付、作成者）が必要
- すべての変更されたPromptはバージョンブロックが必要
- すべてのテストされたPromptはテストスイートヘッダーが必要
- Promptと同じ場所に文書化を保存する — 別ドキュメントは放置される
- 変更理由（「なぜ」）が最も重要なフィールド
文書化されていないPromptがなぜチームを失敗させるのか
📍 In One Sentence
文書化されていないPromptは静かな回帰、重複、知識の損失によってチームを失敗させます — Promptごとに5〜10分の文書化で各々防げます。
💬 In Plain Terms
Promptに何をするか、なぜそのように書かれたかの記録がない場合、チームはそれを安全に変更したり、編集後に回復したり、コンテキストなしで新しいメンバーに引き渡すことができません。
文書化されていないPromptは3つの方法でチームを失敗させます：静かな回帰（何が変わったかの記録なし）、重複、知識の損失。 各失敗はPromptあたり5〜10分の文書化で防げます。
最もコストのかかる失敗は静かな回帰です。チームが本番Promptを修正して一つの問題を解決し、意図せず別の問題を引き起こし、比較する基準点がありません。
複数回使用する、共有インフラに保存する、または本番にデプロイするすべてのPromptを文書化します。
⚠️ 静かな回帰リスク
バージョンブロックとゴールデンサンプルなしでは、本番Promptを変更するチームには基準がありません。すべての編集は以前の状態についての推測です。
6つのPrompt文書化テンプレート
6つのテンプレートがPromptのライフサイクル全体をカバーします。 各テンプレートは10分以内に記入できるように設計されています。
- 1ワンライナーカード
Why it matters: 目的：再利用されるPromptの最小限の記録。フィールド：Prompt名、目的（1文）、対象モデル、作成日、作成者。 - 2バージョンブロック
Why it matters: 目的：変更されるPromptの履歴を追跡。フィールド：バージョン番号、変更日、作成者、変更内容（1文）、変更理由（1文）、テスト結果サマリー。 - 3テストスイートヘッダー
Why it matters: 目的：テスト作成前に受入基準を定義。フィールド：テスト目標、合格基準、ゴールデンサンプル（2〜3の入出力ペア）、既知の失敗モード。 - 4決定ログ
Why it matters: 目的：Promptテキストから明らかでない設計決定を記録。フィールド：決定事項、検討した代替案、この選択の理由、日付。 - 5変更理由
Why it matters: 目的：Promptが変更された理由を説明。フィールド：問題の説明、変更内容、期待される改善点、測定された結果。 - 6APIコンフィグブロック
Why it matters: 目的：本番で使用するモデルパラメータを記録。フィールド：モデル、temperature、max_tokens、top_p、stop_sequences、システムPromptバージョン、ユーザーPromptバージョン。
📌 テンプレート選択ガイド
新しいPrompt → ワンライナーカード。変更されたPrompt → バージョンブロック。テストされたPrompt → テストスイートヘッダー。設計決定が行われた → 決定ログ。失敗後に変更 → 変更理由。本番にデプロイ → APIコンフィグブロック。
Prompt文書化の保存場所
Promptと同じシステムにPrompt文書化を保存します。
- Git：ファイルとして保存されるPromptを持つエンジニアリングチームに最適。コミットメッセージがバージョンブロックとして機能します。無料。
- PromptHub：バージョン履歴、レビュアー署名、テスト結果ストレージを備えた専用Prompt管理。
- Notion：Promptをドキュメントとして管理するチームに適しています。バージョン管理とテスト統合なし。
- Braintrust：テストスイートヘッダーと評価結果をPromptバージョンと一緒に保存。
💡 文書化を共存させる
Promptとは別のシステム（Notion、Confluence、Google Docs）に保存された文書化は数日で陳腐化します。Promptと一緒に存在する文書化だけが最新の状態を保ちます。
よくある文書化の間違い
❌ 文書化が全くない
Why it hurts: 編集後にPromptを回復できず、チームはなぜPromptがそのように書かれたかを理解できない
Fix: 最低限ワンライナーカードテンプレートを使用する — 3フィールド、2分未満
❌ Promptとは別に保存された文書化
Why it hurts: Promptが変更されると文書化が陳腐化し、チームは更新を忘れる
Fix: 文書化をPrompt自体と同じファイルまたはGitコミットに保存する
❌ 「なぜ」フィールドの欠如 — Promptが何をするかのみ記述
Why it hurts: 将来の編集者は制約を知らず、安全にリファクタリングできない
Fix: すべてのテンプレートに「理由」フィールドを追加：なぜこの構造が選ばれたかについての1〜2文
❌ バージョンブロックがない
Why it hurts: 本番で動いているPromptが文書化されたバージョンと一致しているかを知る方法がない
Fix: すべての本番Promptファイルにバージョンと更新日を追加する
よくある質問
なぜPromptには文書化が必要ですか？
文書化されていないPromptはレビュー、監査、再現ができません。回帰を診断できず、既知の良い状態にロールバックできません。
最低限の文書化は何ですか？
ワンライナーカード：目的（1文）、対象モデル、作成日、作成者。2分で書け、最も一般的な失敗を防ぎます。
文書化はどこに保存すべきですか？
Promptと同じ場所に。GitはコードファイルのPromptに最適。PromptHubはバージョン履歴付き構造化ストレージを提供。
新しいPromptにはどのテンプレートを使うべきですか？
ワンライナーカードから始めます。本番 → バージョンブロック。複数のテスト → テストスイートヘッダー。非明白な設計決定 → 決定ログ。
文書化の更新頻度は？
Promptテキストが変更されるたびに更新します。すべての実質的な編集にバージョンバンプと変更理由を追加します。
これらのテンプレートをPromptHubで使用できますか？
はい。PromptHubはバージョンブロックとAPIコンフィグブロックのフィールドに直接対応するメタデータフィールドを保存します。