放置されたままの受信箱にならないフィードバックチャネルの構築

フィードバックチャネルは簡単に立ち上げられます。メールアドレスを追加するか、GitHub Issues を有効にするか、フォームをリンクするだけです。

最初のメッセージが届いてからが難しい部分です。

明確なワークフローがなければ、メンテナーはいくつかの独立した受信箱を確認することになります。報告者は質問の場所がわからず、プライベートメッセージは他の貢献者から検索できず、イシューは「誰かが対応しただろう」という曖昧な状態のまま放置されます。

解決策は別の通知先を増やすことではありません。1つの可視エントリーポイント、明確な所有権、および限定的な状態セットを持つ小さなルーティングおよびトリアージシステムです。

このチュートリアルは GitHub を中心にそのシステムを構築しますが、同じモデルは GitLab、チケットトラッカー、または共有サポートキューでも機能します。

ルーティング契約から始める

ツールを設定する前に、各種メッセージがどこに属するかを決めます。

実用的なルーティングテーブルは次のようになります。

メッセージの種類	宛先	公開範囲
再現可能なバグ	GitHub Issue	公開
機能提案	GitHub Issue または Discussion	公開
利用方法に関する質問	GitHub Discussion	公開
セキュリティ脆弱性	セキュリティポリシーの手順	非公開
アカウント、請求、または個人データ	連絡チャネル	非公開
アクションにつながる可能性のある一般的なフィードバック	連絡チャネル（許可を得てイシューに昇格）	最初は非公開

この分離は重要です。公開チャネルは再利用可能な知識を検索可能にし、非公開チャネルはイシューに投稿すべきでない情報のための逃げ口を提供します。

契約を SUPPORT.md に記載します。

# Support

## Bugs and feature requests

Open a GitHub issue. Search existing issues first and include a minimal reproduction when reporting a bug.

## Questions

Use GitHub Discussions for setup help and open-ended questions.

## Private messages

Use our private contact page for account details, personal information, or feedback you do not want to post publicly.

## Security vulnerabilities

Do not open a public issue. Follow the instructions in SECURITY.md.

## Review cadence

New issues are reviewed on Tuesdays and Fridays. This is a review target, not a guaranteed resolution time.

Enter fullscreen mode Exit fullscreen mode

README からこのファイルへリンクし、貢献者がリポジトリを閲覧して発見する必要がないようにします。

## Help and feedback

- [Report a bug](https://github.com/OWNER/REPOSITORY/issues/new/choose)
- [Ask a question](https://github.com/OWNER/REPOSITORY/discussions)
- [Send a private message](https://example.com/contact)
- [Read the support policy](SUPPORT.md)
- [Report a security issue](SECURITY.md)

Enter fullscreen mode Exit fullscreen mode

すべてのプレースホルダーを置き換え、サインアウトした状態でリンクをテストしてください。メンテナーだけが機能するルートは、使えるエントリーポイントではありません。

イシューピッカーをフロントドアにする

GitHub のイシューテンプレート設定により、人々がイシューを作成する前に正しい宛先に誘導できます。

.github/ISSUE_TEMPLATE/config.yml を作成します。

blank_issues_enabled: false
contact_links:
  - name: Ask a question
    url: https://github.com/OWNER/REPOSITORY/discussions
    about: Get help with setup, configuration, and usage.
  - name: Send a private message
    url: https://example.com/contact
    about: Share account details, personal information, or private feedback.
  - name: Report a security vulnerability
    url: https://github.com/OWNER/REPOSITORY/security/policy
    about: Follow the private security reporting instructions.

Enter fullscreen mode Exit fullscreen mode

ブランクイシューを無効にするのは、提供されたテンプレートが一般的な経路をカバーしている場合にのみ有用です。そうでなければ、構造が障壁になります。

次に .github/ISSUE_TEMPLATE/bug.yml を追加します。

name: Bug report
description: Report a reproducible problem
title: '[Bug]: '
labels:
  - 'status: needs-triage'
body:
  - type: markdown
    attributes:
      value: |
        Thanks for reporting a problem. Remove secrets and personal data before submitting.

  - type: textarea
    id: description
    attributes:
      label: What happened?
      description: Describe the actual and expected behavior.
    validations:
      required: true

  - type: textarea
    id: reproduction
    attributes:
      label: Minimal reproduction
      description: Provide steps, a small repository, or a code sample.
    validations:
      required: true

  - type: input
    id: version
    attributes:
      label: Version
      placeholder: 'v2.4.1'
    validations:
      required: true

  - type: textarea
    id: environment
    attributes:
      label: Environment
      description: Include the operating system, runtime, browser, and relevant dependencies.

  - type: checkboxes
    id: checks
    attributes:
      label: Submission checks
      options:
        - label: I searched existing issues.
          required: true
        - label: I removed secrets and personal data.
          required: true

Enter fullscreen mode Exit fullscreen mode

このフォームはバグを再現するために必要な証拠を求めますが、原因の診断を報告者に求めません。診断はメンテナーの仕事です。

意図的に小さなステートマシンを使う

ラベルは「次に何が起こるか」に答えるものであり、イシューのあらゆる属性を記述するものではありません。

次の状態から始めます。

• status: needs-triage — まだルーティングの判断が行われていない。
• status: needs-info — 報告者が特定の情報を提供する必要がある。
• status: accepted — 問題または提案は有効だが、スケジュールは未定。
• status: duplicate — 別のイシューが正規のスレッドである。
• status: out-of-scope — リクエストがプロジェクトの範囲外である。

オープン中のすべてのイシューには、正確に 1 つのステータスラベルが必要です。技術、コンポーネント、優先度のラベルは別途追加できますが、ワークフローの状態を置き換えるものではありません。

トリアージは再現可能なチェックリストになります。

1. status: needs-triage キューを開く。
2. 秘密情報や個人情報が投稿されていた場合は直ちに削除する。
3. 重複がないか確認する。
4. 報告がこのリポジトリに属するかを確認する。
5. 必要に応じて再現を試みる。
6. 1 つのステータスラベルを適用する。
7. コメントに次のアクションを記載する。
8. 誰かが実際に責任を引き受けた場合にのみオーナーをアサインする。

例として、有用な needs-info 応答は具体的です。

Thanks for the report. We need the smallest configuration that reproduces this and the exact runtime version. Please add those details within 14 days; otherwise, we will close the issue and reopen it when the information is available.

Enter fullscreen mode Exit fullscreen mode

これは単に「詳細が必要です」と書くよりもアクションにつながります。

即時サポートを装わず、定期的なサイクルを選ぶ

サポートワークフローには、指名されたオーナーとレビュースケジュールが必要です。継続的な監視は必ずしも必要ありません。

小規模プロジェクトでは、週 2 回の定期トリアージで十分な場合もあります。現在のメンテナーまたはローテーションを非公開のチーム文書に記載し、SUPPORT.md にはレビューの周期のみを公開します。

各パスでは少なくとも以下を確認します。

is:issue is:open label:"status: needs-triage"
is:issue is:open label:"status: needs-info" updated:<2026-07-10
is:issue is:open no:assignee label:"status: accepted"

Enter fullscreen mode Exit fullscreen mode

2 番目のクエリのハードコードされた日付を、応答ウィンドウの締め切りに置き換えてください。保存した GitHub 検索やプロジェクトビューにより、これらのキューを再訪しやすくなります。

メッセージ量ではなく、ワークフローの健全性を測定します。

• 未トリアージの最古アイテムの経過時間
• ワークフロー状態のないアイテム数
• オーナーのいない accepted イシュー数
• ルーティング判断待ちのプライベートメッセージ数

これらは運用上のシグナルであり、パフォーマンス目標ではありません。プロセスが停止している箇所を示します。

プライベートチャネルを 2 つ目のバックログにしない

プライベートチャネルは受付ルートであり、通常のプロダクト作業の永続的な記録システムではありません。

すべてのプライベートメッセージにこのルールを適用します。

1. 非公開で返信：アカウント詳細、個人データ、その他の機密事項を含む場合。
2. 既存のパブリックスレッドにリダイレクト：回答がすでに文書化されている場合。
3. パブリックイシューに昇格：一般的に有用な作業を特定し、送信者が同意した場合。
4. 明示的にクローズ：アクションを取らない場合。

フィードバックを昇格するときは、元のメッセージをコピーせず、再構成します。識別情報を削除し、観測可能な問題を記述します。

## Problem
Users configuring the client without a default region receive an unclear error.

## Expected outcome
The configuration validator should identify the missing field and point to the relevant documentation.

## Source
Private feedback, shared publicly with permission and anonymized.

Enter fullscreen mode Exit fullscreen mode

パブリックイシューが正規のスレッドになります。以降の更新は受信箱と GitHub に分割されるのではなく、そこに属します。

よくある失敗パターン

すべてのルートが「contact us」と表示される

これにより、バグ、質問、セキュリティレポート、プライベートな詳細が同じキューに送られます。メッセージを作成する前に、ユーザーにルーティングの選択肢を示してください。

自動化がサポートの外観を作り出す

即時のボット応答は、報告書が人間によってレビューされたことを意味しません。確認応答を自動化する場合は、実際のレビューの周期を明記し、作業がスケジュールされたことを示唆しないようにします。

ラベルが判断を変えずに蓄積される

イシューに 12 個の記述的ラベルが付いていても次のアクションがない場合、タクソノミーは役に立っていません。1 つのワークフロー状態を必須にし、オプションのラベルは最小限に保ちます。

プライベートフィードバックがプロジェクトに戻らない

有用な報告がダイレクトメッセージの中に消えてしまうことがあります。プライベートチャネルのトリアージパスごとに「昇格、リダイレクト、返信、またはクローズ」を追加します。

メンテナーが暗黙のうちに利用できなくなる

共有受信箱は、誰もが「誰かが見ているだろう」と仮定すると機能しません。チームが 2 人であっても、現在のオーナーまたはローテーションを割り当てます。

セキュリティレポートが一般的な連絡ルートを使う

脆弱性の手順は SECURITY.md に記載し、プロジェクトに適する場合は GitHub のプライベート脆弱性報告を有効にします。報告者に通常のパブリックフォームを通じてエクスプロイトの詳細を送るよう求めないでください。

ホスト型連絡ページの実装

プライベート受付ページを自分で構築・運用したくない場合は、Knocket が 1 つの実装例です。共有可能な連絡ページを作成し、その URL を README と上記の contact_links 設定に配置し、GitHub をパブリック作業の正規の場所に保ちます。訪問者はアカウントを作成せずに会話を開始でき、メッセージは Telegram にもルーティング可能で、引用返信を訪問者に返せます。

連絡ページプロバイダーに関係なく、ワークフローのルールは同じです。オーナーを任命し、定期的にキューをレビューし、機密情報を保護し、適切なフィードバックを許可を得てパブリックイシューに昇格します。

メンテナンスチェックリスト

月に一度、システム自体を確認します。

• プライベートブラウザウィンドウで README とイシューピッカーのすべてのリンクを開く。
• SUPPORT.md に現在のレビューの周期が記載されていることを確認する。
• セキュリティルートが一般連絡先と区別されていることを確認する。
• 未トリアージおよび未アサインのキューを確認する。
• 廃止されたラベルとテンプレートを削除する。
• プライベート会話のサンプルを確認し、それぞれにルーティング判断が下されていることを確認する。
• 内部の指名オーナーまたはローテーションを更新する。

優れたフィードバックチャネルは、人々が連絡できる方法の多さで定義されるのではなく、すべてのメッセージが判断に至るかどうかで定義されます。

議論

あなたのプロジェクトでは、パブリックイシューとプライベートフィードバックをどのように分離していますか？報告が放置された受信箱にならないよう、メンテナーのローテーション、定期トリアージセッション、または他の仕組みを使っていますか？

---

Disclosure: I work on Knocket, so treat it as one implementation example rather than a neutral recommendation.