explaining-code

コードの説明

特定の変更やコードについて、初めて読む人向けに簡潔または詳しく説明します。

サブシステム全体の仕組み（アーキテクチャ、データフロー、ファイル構成）についての質問の場合は、Skill ツールで explaining-architecture を呼び出してください。そのスキルがインストールされていない場合は、質問の範囲に沿って、選択された詳しさで説明してください。Skill ツールがない場合は、スキル呼び出しのルールに従ってください。

入力

リクエストには、省略可能な詳しさを示すトークンに続いて、対象が含まれます。対象は、PR 番号または URL、ファイルパス、関数名またはクラス名、ブランチ名、あるいは概念です。

対象が指定されておらず、会話からも明らかでない場合は、作業を中止してください。 説明する対象を一度だけ尋ね、ユーザーの回答があるまで作業を行わないでください。ドキュメントの記述ではなく、コードの動作を説明し、食い違いがあればドキュメントとコードに関するルールに従って報告してください。

詳しさ

• 簡潔（既定）：以下の「簡潔」のセクションに従ってください。
• 詳しく（ELIE）：先頭のトークンが elie または eliet の場合、あるいは ELIE、「エンジニア向け」または「レビュー担当者向け」の説明、「詳細な」説明、または完全な説明を求められた場合に選択されます。詳しい説明を読み、「簡潔」のセクションではなく、そちらに従ってください。

対象を読み取る前に、詳しさを示すトークンを取り除いてください。

簡潔

• この領域について前提知識のない開発者にも伝わる、1文の要約から始めてください。
• 抽象的な言葉（「コンポーネント」「モジュール」など）ではなく、具体的な名詞（「注文履歴ページ」「ログイン画面」など）を使ってください。
• 日常的なたとえは、自然に当てはまる場合に限って使ってください。
• その後、暗黙の疑問に答える3〜6文を続けてください。変更前の状況、変更内容、理由を説明します。
• 簡潔な回答全体は、冒頭の要約とそれに続く文を合わせて最大7文とし、見出し、太字のラベル、箇条書きは使わず、1段落または2段落にまとめてください。回答前に文数を数えてください。
• 追加の説明は、求められた場合に限って書いてください。
• 避けられない用語や頭字語は、初出時にインラインで正式名称を示して定義してください。例：「SLA（サービスレベル契約）チェッカー」。
• 仕組みではなく、何をするか、なぜそうするかを説明してください。
• テスト、レビュアー向けの注記、リスク、エッジケース、アルゴリズム、比較、ヘッダー、ステータスコード、関数名などの実装の詳細は省いてください。これらは詳しい説明に含めます。
• 役立つ場合は、詳しい説明も提供できることを最後に1行で伝えてください。
• 変更されたファイルをすべて列挙するのではなく、その影響を要約してください。
• 質問の範囲に合わせて説明してください。1つの関数について尋ねられた場合は、システム全体ではなく、その関数を説明してください。
• 対象に応じて文の順序を調整してください。PR の場合は変更前から変更後の順に説明し、概念の場合は1段落にまとめてもかまいません。モジュールの概要の場合は、責務を文章で示してもかまいません。

PR についての簡潔な説明の例：

検索ページが最近の検索結果を1分間記憶するようになったため、同じ検索を繰り返すとすぐに読み込まれます。以前は、数秒前に同じクエリを実行した場合でも、検索のたびにデータベースへ問い合わせていました。現在は、まず結果キャッシュ（最近の結果を一時的に保存したメモリ内のコピー）を確認し、結果がなければデータベースに問い合わせます。掲載内容はまれにしか変わらないため、この PR では結果が最大1分間古くなることを許容しています。