【コピペ可】Discord Bot納品テンプレ｜要件定義・設定・受入テスト・引継ぎを1セットで

「Botが動きました」で納品を終えると、翌日に止まります。

発注者はトークンの場所を知らない。開発者しか再起動できない。どの権限が必要か説明できない。エラーが出ても、仕様なのか不具合なのか判断できない。こうした状態は、デモには合格しても納品には合格していません。

Discord Botの納品完了は、コードを渡した瞬間ではなく、発注者側で次の5つを確認できた時です。

• 何をするBotか、対象外は何かが文章で分かる

• 設定値と権限の根拠を確認できる

• 正常系・異常系・権限不足を受入テストできる

• 秘密情報を安全に引き継ぎ、必要なら無効化できる

• 障害時の停止・復旧・問い合わせ先を判断できる

この記事では、この完成状態を作るための「要件定義書」「設定票」「権限・Intents表」「受入テスト票」「秘密情報引渡し票」「運用・障害対応票」「保守範囲・完了判定」を、コピペできる形で1セットにします。

この記事が役立つ人

• Discord Botを受託開発して、初めて納品する人

• 外注したBotを、何を確認して受け取ればよいか分からない発注者

• 個人開発から保守契約へ移る前に、責任範囲を整理したい人

• 「動くが、誰も運用できないBot」を引き継いで困っている管理者

• テストや秘密情報の受け渡しをDMだけで済ませたくない人

反対に、この記事は特定ライブラリの実装チュートリアルではありません。Discord.js、discord.py、Deno、Goなど、実装言語にかかわらず使える納品設計を扱います。

先に結論：納品物はコードではなく「判断できる状態」

発注者が毎回開発者へ聞かないと判断できないなら、運用は引き継がれていません。

納品物を次の7点に分けると、抜けを発見しやすくなります。

1. 要件定義書：何を実現し、何をしないか

2. 設定票：どの環境で、どのIDと設定を使うか

3. 権限・Intents表：なぜその権限とイベント購読が必要か

4. 受入テスト票：何をもって合格とするか

5. 秘密情報引渡し票：誰が発行・保管・無効化するか

6. 運用・障害対応票：止め方、戻し方、連絡条件

7. 保守範囲・完了判定：納品後に含む作業と含まない作業

この分け方の利点は、「仕様変更」「不具合」「設定ミス」「権限不足」を同じ箱に入れないことです。原因ごとに担当と対応時間を変えられます。

無料部分だけで押さえる4原則

1. 要件は機能名ではなく、入力・対象・結果で書く

「問い合わせ対応Bot」だけでは、受入条件を作れません。

悪い例：問い合わせに対応する

良い例：
入力：/ticket category:<選択肢> summary:<100文字以内>
対象：許可したGuild内の指定カテゴリ
結果：非公開チャンネルを1件作成し、申請者と担当Roleだけ閲覧可能にする
失敗時：権限不足を本人だけに表示し、チャンネルは作成しない

入力、対象、結果、失敗時の4つがあれば、仕様とテストをつなげられます。

2. 権限は「招待URLに入れた値」ではなく実環境で確認する

Discordでは、OAuth2のスコープと、Guild・チャンネルにおけるBotの権限は別の層です。公式ドキュメントも、アプリが必要とする権限だけを要求するよう案内しています。

納品時は次を分けて記録します。

• インストールに使うスコープ（例：`bot`、`applications.commands`）

• Botロールへ付与するGuild権限

• チャンネルごとの上書き

• Botロールの階層位置

• コマンドを使えるRole、User、Channel

• Gateway Intentsと、その利用理由

Administratorを付ければ動く、は受入条件ではありません。最小権限で成功し、権限を1つ外した時に安全に失敗することまで確認します。

3. Botトークンはパスワードとして扱う

Discord公式はBotトークンをパスワード同様に扱い、公開しないよう明記しています。

そのため、納品物のソースコード、README、画面キャプチャ、ログ、チャット履歴へ本番トークンを残しません。納品時は、発注者自身が本番トークンを発行し、指定した秘密管理先へ登録する方法が基本です。

.env.example には変数名だけを書く
DISCORD_BOT_TOKEN=
DISCORD_CLIENT_ID=
DISCORD_GUILD_ID=

本番値は書かない

開発者が一時的に本番値へ触れた場合は、納品完了前に発注者が再発行し、旧値が無効になったことを確認します。

4. 正常系だけでは合格にしない

最低でも、次の4種類を1ケースずつ通します。

• 正常系：許可された人が正しい入力で実行する

• 入力異常：空欄、上限超過、存在しないID、重複実行

• 権限異常：未許可Role、未許可Channel、Bot権限不足

• 運用異常：再起動、外部API失敗、429、設定値欠落

DiscordのGatewayでは、必要なIntentsを指定しないと対応イベントを受け取れません。特権IntentsはDeveloper Portalでの有効化が必要で、条件によって承認も必要です。「開発環境では動いたが本番ではイベントを受け取れない」を防ぐため、設定票と受入テストを結びつけます。

10分で使う方法

1. この記事末尾の付録ファイルを複製する

2. 未確定欄へ `TBD` と期限・担当者を書く

3. 各機能を「入力・対象・結果・失敗時」へ分解する

4. 権限とIntentsを機能ごとにひも付ける

5. 正常・入力異常・権限異常・運用異常のテストを作る

6. 発注者がテストし、証跡URLと判定を記録する

7. 秘密情報を発注者管理へ移し、旧値を無効化する

8. 未解決事項が0件、または合意した残課題だけになったら完了署名する

未確定事項を空欄のままにしないことが重要です。`TBD / 担当 / 期限 / 影響` の4点を残せば、忘れた項目ではなく管理中の項目になります。

無料サンプル：受入条件を1件だけ完成させる

例として、FAQコマンドの受入条件を作ります。

機能ID：CMD-FAQ-01
目的：利用者が定型質問の回答を自分で確認できる
入力：/faq question:<登録済み候補>
実行者：Guild内の全メンバー
実行場所：#help と #faq
成功条件：2秒以内に回答を本人だけへ表示する
記録：質問ID、Guild_ID、User_ID、成否、処理時間
失敗条件：未登録候補は候補一覧を返し、内部エラーを表示しない
対象外：自由文検索、DM、添付ファイル解析

ここまで書けば、発注者は「期待と違う」を感想ではなく項目で伝えられます。

以下の有料部分では、この考え方を全機能へ展開できるテンプレート一式と、20件の受入テストひな形、秘密情報の引継ぎ、保守範囲、完了判定までまとめます。内容をそのまま案件フォルダへ保存し、不要な行を削って使えます。