change-explainer

変更の解説

初めて読む人にも伝わるように説明してください。一般的なプログラミングと Git の知識はあるものの、プロジェクトやドキュメントの目的、分野、アーキテクチャ、用語、構成は知らないものとします。読者の背景が明示されている場合は、その記述を優先してください。

次の流れで段階的に説明してください。

全体 → 領域 → 具体的な問題 → 変更 → 仕組み

言語の構文、パッチの作成方法、編集した行すべてではなく、システムの変更内容を説明してください。

出力の条件

• 説明全体を Markdown で、最終回答に直接出力してください。
• HTML ページ、Markdown ドキュメント、図のファイル、.change-explainer/ ディレクトリ、その他の説明用成果物を作成、保存、開かないでください。
• ワークフローは読み取り専用にしてください。このスキルの実行が許可するのは調査のみであり、リポジトリや比較対象のドキュメントの編集ではありません。
• 説明用の成果物がないことに触れるのは、ユーザーの依頼の曖昧さを解消する場合に限ってください。
• 理解の助けになる場合にのみ、見出し、箇条書き、表、短いコード抜粋、簡潔なテキスト図を使用してください。生の HTML を出力したり、折りたたみ式 UI に依存したりしないでください。

説明の原則

1. 変更点の前に基準となる状態を示す。 変更を述べる前に、プロジェクトまたはドキュメントの役割、変更されたサブシステムまたはセクションの役割、そして全体の中での位置を説明してください。その基準となる状態を把握するために必要な範囲で、最も近い概要、アーキテクチャの案内、エントリーポイント、または周辺のセクションだけを読んでください。
2. 抽象的な説明より具体例を先に示す。 変更前の挙動とその問題点が分かる、現実的な実行例、リクエスト、または障害をひとつ示してください。読者がその状況を思い描けるようになってから、責務、ライフサイクル、契約などの抽象概念へ一般化してください。
3. 用語は必要性を示してから使う。 プロジェクト固有の名詞、略語、コード識別子を、使う前に定義してください。役割を先に説明し、次に名称を示してください。たとえば、「ランナーのビルド関数である buildProject」とし、いきなり「buildProject」とはしないでください。ひとつの概念には平易な用語をひとつだけ使い、ソースコード内の同義語は一度だけ対応づけてください。
4. 説明の軸はひとつに絞る。 挙動の変更を説明するうえで必要な考え方を、ひとつから四つ選んでください。補助的な編集にも触れつつ、移行範囲、機械的な変更、ドキュメント、テストの一覧を主題と同等に扱わないでください。
5. 読む順に理解を深める。 冒頭の要点と具体例だけでも、短い説明として理解できるようにしてください。仕組みやメンテナー向けの詳細は、回答の後半に配置してください。
6. 関係性は役立つ場合にのみ示す。 説明文より分かりやすくなる場合に限り、フロー、順序、構造、責務、比較を Markdown の表または簡潔なテキスト図で示してください。読者がすでに理解しているラベルを使ってください。
7. 根拠は説明に結びつける。 検証に実質的な助けとなる場合に限り、ソースの場所を示してください。場所だけをまとめた独立したセクションを作らず、関連する仕組みや保守上の注記に添えてください。
8. 説明と評価を分ける。 描写に徹してください。正確性、回帰、契約、セキュリティやデータ、長期的な設計に重大な問題がある場合に限り、懸念点を含めてください。推測した意図やトレードオフには、推測であることを明記してください。

回答の構成

固定のテンプレートを埋めるのではなく、変更の規模に合わせて回答を調整します。次の学習順序を維持してください。

1. 要点から始めます。 全体としてプロジェクトやドキュメントが何であるか、変更箇所がどこに当たるか、以前はどうだったか、現在はどうなったか、その違いがなぜ重要なのかを、2〜4文で説明します。読者が明確に専門家である場合は、プロジェクトの概要を簡潔にします。
2. 具体的な「変更前 → 現在 → 結果」のストーリーを1つ示します。 現実的な入力、リクエスト、ワークフロー、またはポリシーのシナリオを選びます。ごく小さな変更の場合は、冒頭の段落に含めてもかまいません。
3. 仕組みを説明します。 学習順に、概念上の変更を1〜4つ説明します。それぞれの仕組みを具体的なストーリーに結び付け、なぜ重要なのかで締めくくります。繰り返し登場する必須用語はこのセクションの前に定義し、個別に使われる用語はその場で定義します。
4. 必要に応じて、覚えておくことを示します。 説明が複雑な場合は、簡潔な 変更前、現在、理由 の項目を使います。ごく短い回答を繰り返すだけになる場合は省略します。
5. 役立つ場合のみ、レビュアーやメンテナンス担当者向けの詳細を加えます。 判断、互換性、テスト、トレードオフ、移行範囲、今後の編集ルールについて、主要な説明の後に取り上げます。重大な問題がある場合に限り、懸念事項 セクションを追加します。

小さな変更の場合は、概要 → 例 → 差分 → 根拠 の順序を維持しながら、回答を簡潔にします。大きな変更の場合は、簡潔な概要の後に、ファイルごとではなく動作ごとにまとめたセクションを設けます。

ワークフロー

1. 比較対象を特定します。 指定された差分、コミット、範囲、PR パッチ、またはファイルの組み合わせを使います。Git リポジトリで対象が指定されていない場合は、git status --short、ステージ済みおよび未ステージの差分、関連する未追跡ファイルを使って、コミットされていない作業を確認します。作業ツリーに変更がない場合、またはディレクトリが Git リポジトリではない場合は、対象を尋ねます。
2. 初見の読者向けの土台を作ります。 まず差分を確認し、次に必要最小限の概要、アーキテクチャまたはセクション構成、エントリポイント、周辺の実装や説明文、テストや裏付けとなる証拠を確認します。次の点に答えます。この全体は何をするのか。この箇所は何をするのか。以前はどうだったのか。現在はどうなったのか。読者、ユーザー、メンテナンス担当者にとって、なぜ重要なのか。
3. 説明の軸を選びます。 すべての差分を考慮しつつ、動作や意味の変更を説明する、最も重要なアイデアを1〜4つに絞ります。補足的な差分はメンテナンス情報にまとめます。
4. このやり取りに合わせて下書きします。 まず平易な言葉で結果を伝え、その後は変更に見合った構成だけを加えます。主な説明は、ソースファイルのパスがなくても理解できるようにします。
5. 初見の読者向けチェックを行います。 冒頭、具体的なストーリー、概念を示す見出し、記憶のための要点だけを読んで確認します。すべての名詞、頭字語、識別子が、一般的なプログラマーにとって馴染みのあるものであるか、同じ文で定義されているか、前の箇所で定義されている必要があります。目に見える箇所だけで、先ほどの5つの問いに答えられるようになるまで修正します。
6. 直接回答します。 説明を最終回答として提示します。補足資料は作成せず、開かないでください。

コミュニケーションルール

• 主な説明では差分を網羅することより理解と記憶しやすさを優先し、補足情報は回答の後半で維持します。
• アーキテクチャ名や比喩を持ち出す前に、得られた具体的な機能や解消された不具合を示します。
• 段落は短くし、各段落で新しいアイデアを導入するのは1つまでにします。
• ユーザーがレビュー形式を求めている場合に限り、レビュー用語を使います。