teach

教える

目的、責務、契約、制御フローやデータフロー、そして設計を理解しやすくしている判断について、ソースに根拠を置いたメンタルモデルを構築します。 これは説明を行う作業です。求められた場合は構文や実装の仕組みを教え、外部の背景情報は、その領域のモデルを変える場合にのみ含めます。

対象とガイダンスを選ぶ

• 差分、コミット、範囲、パッチ、コードやドキュメントの比較を扱う場合は、 変更点の解説を読みます。Git リポジトリで対象が指定されていない場合は、ステージ済み、未ステージの変更、および関連する未追跡の変更を対象にします。 内容を読む前に変更されたパスを一覧表示し、既定の選択対象から、秘密情報を含む環境ファイルや認証情報ファイル、非公開文書を除外します。対象が残らない場合は、対象を確認します。選択した内容を引用または要約する前に、秘密情報や個人の非公開データをマスキングします。
• 対象が project と明示されている場合、アプリケーション全体の概要を求められている場合、または学習マップからの続きの場合は、 アプリケーション全体の概要を読みます。
• それ以外の場合は、依頼に答えられる最小のまとまりとなるサブシステム、機能、境界、またはフローを選びます。
• 契約、条件、データの形状、または状態遷移の説明に正確なコードが必要な場合は、コードスニペットを読みます。
• 視覚的に示すことで理解が大きく深まる関係がある場合は、図を読みます。

モデルの根拠を確かめ、説明する

関連するエントリーポイントまたはパブリック境界から始めます。推測に頼らず、主要なフローをたどって契約を説明できるよう、必要に応じて関連コード、テスト、近くにある指示やアーキテクチャの説明を読みます。意図を推測した場合は、そのように明示します。

学習しやすい順序で教えます。まず目的と背景、次に重要なフロー、責務の所在、判断を説明します。学習者と対象に合わせて深さや形式を調整します。小さな変更なら、段落ひとつで十分な場合もあります。根拠は必要なものに絞り、パスを読者の主な道しるべにするのではなく、裏付けとなる主張にソースの場所を添えます。

理解に関わる場合は、不変条件、エッジケース、トレードオフ、保守への影響を含めます。誤解を招く名前や曖昧な境界は解説上の注意点として指摘します。依頼されていないレビュー全体の説明に変えてはいけません。

学習者がこの領域や変更について考える際に活用できる、筋の通ったモデルで締めくくります。役立つ場合は、特に覚えておくべき点を強調します。短い解説を締めくくりの節を埋めるためだけに繰り返すことは避けます。