ここでの説明とは、ユーザーの言葉による因果連鎖です。各主張がその理由を伴った短い文が、ユーザーがすでに使っている用語で構成され、一度で読める(必要なら音読できる)形で記述されます。
1. ユーザーの言葉を収集する
説明はユーザーが知っていること、そしてその知識が入力した言葉に表れているものに結びつきます。セッション内で初めてトピックを説明する前に、ユーザーがこれまでどのようにそのトピックについて話してきたかを読みます。
python3 <このスキルのフォルダ>/user_words.py <キーワード> [<キーワード> ...]
python3 <このスキルのフォルダ>/user_words.py --all-projects <キーワード> ...
これにより、ユーザーが以前のClaudeセッションで入力した、キーワードを含むメッセージが、現在のプロジェクトまたは全プロジェクトから新しい順に出力されます。キーワードはユーザーの質問とトピック(コンポーネント名、ツール、障害の対象)から選びます。現在の会話におけるユーザーのメッセージも追加します。
これらから、以下の3点を書き留めます。
- ユーザーの用語: 各事物に対してユーザーが使う言葉(「zweiter SSH-Weg」、「incoming IP」、「proxied」)。コードやドキュメントで別の名前が使われていても、正確にこれらを使用します。
- 既知の基盤: ユーザーが正しく述べたり使用したりしたこと。連鎖はそこで終わっても構いません。
- ギャップ: トピックに含まれるがユーザーが一度も使ったことのない用語。それぞれが新しい言葉です。
説明に必要なすべての用語が、ユーザーの用語または新しい言葉に分類されたら完了です。
2. 連鎖を書く
- 最初に問題を述べる。 最初の文で問題そのものまたは答えを述べます:「問題はXです。」ユーザーが直接的な質問をした場合(「なぜパスワードが必要なのですか?」)、最初の文がその質問に正確に答えます。
- すべての主張に理由を添える。 理由を同じ文内に「なぜなら」「ので」「によって」で結びつけます。理由なしで効果だけを述べると、リンクが切れたままになります。たとえば「すべての接続が127.0.0.1から来ている」だけでは何も説明になりませんが、「fail2banがIPごとにブロックするからである」と隣に置くことで説明になります。
- 既知の基盤まで連鎖させる。 理由をたどり、最後の理由が既知の基盤になるまで続けます。そこで止めます。
- ユーザーの用語で、メカニズムそのものを述べる。 実際のメカニズムを文字通り、ユーザーの用語で述べます。類推、イメージ、創作されたキャストは使いません。
- 新しい言葉は括弧で囲む。 新しい言葉は最初の出現時に、その直後にキーワードを括弧で囲んで付け、その後はそのまま使います。例:「HostKeyAlias(SSHオプション:known_hostsの別のエントリに対してホストキーを検証する)」。キーワードは文ではなく、単語です。
- 話し言葉の散文。 3~5文の短い宣言文で、一文につき一つのリンク、原因から結果への順序で構成します。音声読み上げに耐える平易な連続テキストです。説明内に見出し、表、箇条書きは使いません。
アーキテクチャの場合、連鎖は1つのリクエストまたは1つの変更の経路に沿って進みます。どの部分が動作し、何を次に渡し、なぜ次がそれで自分の役割を果たせるか(または果たせないか)を記述します。
3. 修正箇所を明示する
ユーザーの表現と前提はコードと事実に照らして検証され、すべてのずれが連鎖の後で、1行ずつ「あなたは…と言っていますが、正しくは…です。なぜなら…」として明示されます。
- コードが裏付けない表現: ユーザーが「パスキー」と言うが、それはキーチェーンエントリである場合。ユーザーが「ランナーがダウンした」と言うが、ランナーはコンテナであり、Dockerが失敗している場合。コードまたはツールが使用する名前を伝え、ユーザーの次の質問や次の検索ヒットに役立てます。
- 誤った前提: ユーザーが正しいと仮定しているが実際はそうでないこと(「そのパスワードは接続に必要だ」)。代わりに何が正しいのか、その理由を述べます。
修正する前にコードまたはシステムで確認します。記憶からの修正は推測です。その後、正しかった部分についてはユーザーの用語を引き続き使用します。
モデル
ユーザーが本来受け取るべき説明を、ユーザー自身の言葉で書き直した例(Cloudflareトンネル背後でfail2banがSSHを保護しない理由)。ここでの例はドイツ語ですが、説明はユーザーが書く言語で行います。
問題はパスワードによる2つ目のSSH経路です。Macのユーザー名とユーザーパスワードを使えば、誰でもブルートフォースで接続を確立できます。fail2banは保護しません。なぜなら、fail2banはIPベースのブロックであり、トンネルを通るため全員が同じincoming IPを持つからです。Cloudflareがproxiedしているからです。
完了条件
送信する前に、各文を確認します。
- 最初の文が問題を述べているか、または尋ねられた質問に答えていること。
- すべての主張に同じ文内で理由が添えられていること。
- 最後の理由がこのユーザーにとって既知の基盤であること。
- すべての用語がユーザーの用語か、または括弧付きの新しい言葉であること。
- ユーザーの質問の中の誤った表現と誤った前提がすべて、修正とともに明示されていること。
ユーザーがそれでも理解できない場合は、理由が欠けているリンクを1つ見つけ、そのリンクだけを1文で提供します。具体的な値(2つのIP、1つのリクエスト)はそのリンクを閉じるためにだけ、そこでのみ使用します。
次に何をすべきか(オプション、コマンド、推奨事項)は、説明の後に、説明から分離して、かつユーザーが尋ねたか行動に必要とされた場合にのみ続けます。