質問を書く前に、環境メモを1分で作っておく

エラーの画面を前に、質問を書き始めて手が止まる夜があります。何が起きたかは説明できても、「どのバージョンで」「どの OS で」と聞き返されそうな項目を、その場で一つずつ調べ直すことになるからです。

そこを1分で済ませるための小さなシェルスクリプトを、ここに置いておきます。先にお伝えしておくと、スクリプトが集めるのは「環境」だけで、「何を試して何が起きたか」は人が書くしかありません。両方をそろえて、はじめて質問が読まれる形になります。

返事が付きにくい質問には、足りないものが決まっています

質問を受ける側に回ったことを想像してみてください。「動きません」の一行だけの投稿に、答える側ができることはほとんどありません。聞き返すしかなく、聞き返しの往復が一度入るたびに、返事は遅くなります。

答える側が最初に知りたいのは、おおむね次の4つです。

知りたいこと	質問者が書くもの	スクリプトで集められるか
どの環境か	OS、シェル、各コマンドのバージョン	集められます
いつ起きたか	確認した日時	集められます
何が出たか	エラー文の末尾、ログの該当箇所	末尾だけなら集められます
何をしたら起きたか	再現の手順、直前の操作	集められません（人が書きます）

上の2行は機械に任せて、下の2行に時間を使います。これが、私がこの形に落ち着いた理由です。

環境メモを作るスクリプト

個人開発の作業机で、エラーのたびに uname や --version を打ち直しているのが面倒になり、まとめて出すだけのものを書きました。何を解決するかを先に言えば、貼る前に自分の環境を一度で並べて、うっかり混ざった秘密の文字列を伏せるためのスクリプトです。

#!/usr/bin/env bash
# 使い方: bash forum-report.sh [ログファイル]
# 質問に貼る「環境メモ」を標準出力に作る。ホームのパスとトークンらしき文字列は伏せる。
set -u
 
mask() {
  sed -E \
      -e "s#${HOME}#~#g" \
      -e 's#(ghp_|github_pat_|sk-|AIza)[A-Za-z0-9_-]{8,}#\1***#g' \
      -e 's#([Tt]oken|[Kk]ey|[Ss]ecret)=[^[:space:]]+#\1=***#g'
}
 
ver() {  # コマンドがあれば先頭1行だけ、無ければ「なし」
  if command -v "$1" >/dev/null 2>&1; then
    "$@" 2>&1 | head -n 1
  else
    echo "なし"
  fi
}
 
{
  echo "## 環境"
  echo "- OS: $(uname -srm)"
  echo "- シェル: ${SHELL:-不明}"
  echo "- agy: $(ver agy --version)"
  echo "- git: $(ver git --version)"
  echo "- node: $(ver node --version)"
  echo "- 確認した日時: $(date '+%Y-%m-%d %H:%M %Z')"
  if [ -n "${1:-}" ] && [ -f "$1" ]; then
    echo
    echo "## ログ（末尾 40 行）"
    echo '```'
    tail -n 40 "$1"
    echo '```'
  fi
} | mask

なぜこう書いたのかを、3点だけ補います。

出力全体を mask に通しています。 ログに混ざったトークンは、貼る人が目で探すより、最後に機械が一括で伏せたほうが取りこぼしが少なくなります。
ver は先頭1行だけを取ります。 バージョン表示が複数行のコマンドでも、メモが縦に伸びません。コマンドが無ければ「なし」と書くので、「入っていない」という事実も質問の材料になります。
ログは末尾40行に限っています。 全文を貼ると、肝心の数行が埋もれます。足りなければ、読み手が聞き返してくれます。

手元で動かして確かめたこと

このスクリプトは、サンドボックスの Linux 上で動かして確かめました。agy が入っていない環境だったので、agy の行は「なし」と出ています。つまり、Antigravity 本体が入っている環境でバージョンの一行がどう見えるかは、この確認では見ていません。ご自分の環境で一度実行して、出力を目で確かめてから使っていただければと思います。

ダミーのログを渡した結果は、次のとおりです。

error token=abc123 at /sessions/x
key=zzz ghp_ABCDEFGHIJKL1234 end

これが、次のように伏せられました。

error token=*** at /sessions/x
key=*** ghp_*** end

token= や key= の形も、ghp_ で始まる文字列も伏せられています。一方で、伏せられるのは形が決まっているものだけです。メールアドレス、社内のホスト名、顧客の名前、プロジェクトのコードネームは、このスクリプトでは消えません。貼る前に、目でもう一度なぞる時間は残してください。

自分の環境に合わせて、行を足す

スクリプトの ver 関数は、コマンド名と引数をそのまま渡す作りにしてあります。質問したい内容に応じて、行を一つ足すだけで済みます。たとえば Python が絡む症状なら、次の1行を node の下に入れます。

  echo "- python3: $(ver python3 --version)"

足すときの目安は、その症状に関係しそうなものだけです。何でも並べると、読み手が重要な行を探す手間が増えます。逆に、関係があるかどうか迷ったものは、入れておいたほうが後悔が少ないと感じています。聞き返される一往復は、一行足す手間よりずっと重いからです。

環境メモの上に、人が書く3行

メモを作ったら、その上に次の3行を足します。型だけ借りて、言葉は毎回自分のものに置き換えてください。

何をしようとしたか（目的を1文で）
どう操作したら、何が出たか（手順とエラー文の要点）
すでに試したこと（試して変わらなかった点を、短く）

3行目は、書き忘れやすい一方で、答える側にとっていちばん助かる行だと感じています。「再起動した」「バージョンを上げた」と書いてあるだけで、同じ提案の繰り返しを避けられます。

質問は、環境を機械に、経緯を人に。 私はこの分担を、投稿の前の確認事項にしています。

まとめるときに、先に決めておくこと

最後に、運用上の線引きを3つ書き残します。

貼り付けるのは、スクリプトの出力を目で読み終えたあとだけにします。
未公開のプロジェクトの話は、事象だけを抜き出した最小の例に書き換えてから投稿します。
解決したら、同じスレッドに「何が原因だったか」を1〜2行で戻します。次に同じ症状で来る方の、いちばんの手がかりになるからです。

まずはスクリプトを forum-report.sh という名前で保存して、次に何かが起きたときのために、一度だけ手元で動かしておいていただければ幸いです。

質問を書く前に、環境メモを1分で作っておく — 返事が付きやすい投稿のための小さなシェルスクリプト