ds-explain

ds-explain

あるものが何で、どのように動き、なぜ現在の形になっているのかを、読者が自信を持って変更できるよう、分かりやすく説明します。

手順

1. 読者が知りたいことを把握します。会話を読み、これから変更するのか、レビューするのか、デバッグするのか、あるいは初めて触れるのかを確認します。読者が理解しておくべきことを3〜4点選びます。すでに知っていることは省きます。
2. 作業の規模を見極めます。単一の関数なら一度確認すれば十分です。多数のファイルにまたがるサブシステムなら、それぞれ異なる観点を担当する読み取り専用のサブエージェントを2〜4つ並行して使い、その後、一度の確認で内容をまとめられます。
3. 仕組みを確認します。実際のコードを読みます。エントリーポイントから処理結果まで、主要な実行経路をたどります。各状態をどこが管理しているか、境界がどこにあるかを記します。ファイルと行番号を引用します。
4. その形になった理由を確認します。コミット履歴、blame、PRの説明、関連するイシュー、コード付近のコメントを確認します。記録に書かれていることと推測を分け、推測は明確にそう示します。記録がなければ、その旨を伝えます。
5. 説明を書きます。まず一般的な言葉で簡潔に定義し、次にこのコードベースに結び付けます。実際に使ったときの動作を順に説明します。続いて理由、最後に例外的なケースを説明します。役立つ場合は、小さな図や表を使います。
6. 特定の項目について、さらに詳しく説明できることを伝えます。

次の場合は終了します

• 引用したコードと根拠のある理由を示して、読者の質問に答えたとき。
• または、理由を探すために3回調べても記録が見つからないとき。その場合は、理由は不明であると伝えます。

ルール

• コードを編集しないでください。
• 動作に関するすべての記述に、ファイルと行番号を示してください。
• 意図に関する推測を、事実として述べないでください。
• 関数を列挙するのではなく、仕組みを説明してください。