how

成果物はメンタルモデルです。このサブシステムに新たに加わるシニアエンジニアを対象に、注釈付きのソースコードに踏み込まない範囲で説明します。記載するすべての主張は、実装にたどれるものにしてください。

1. 問いの整理

呼び出し元から受け取った質問、またはこのセッションで議論されているテーマから問いを設定します。範囲が曖昧な場合は、自分の解釈を一行で示してから進めます。

問いを観点に分けます。それぞれの観点は、サブシステムを切り分けたものです。単一のモジュールや関数なら観点は一つ、複数のファイルやサービスにまたがるサブシステムなら二〜四つにします。迷った場合は少なめにします。

各観点の出発点となるファイルまたはシンボルが示され、問いのすべての部分がいずれかの観点に含まれていれば完了です。

2. 調査

一つのメッセージで、観点ごとに一人の調査担当を割り当てます（subagent_type: Explore、検索範囲は very thorough）。各プロンプトには、references/explorer-brief.md のパス、問い、担当する観点を含めます。

各担当者の報告で、その観点がコードにたどれ、各コンポーネントおよび各フローの段階にファイルパスが示されていれば完了です。名前だけを挙げている報告は、調査担当を再割り当てしてください。

3. 説明

調査結果を一つのメンタルモデルにまとめます。調査担当者どうしの調査範囲が重なる場合は統合し、矛盾する場合は自分でコードを読んで解決します。/humanize に従って記述し、次の点に注意します。

• 実際の名前を挙げます。「サービスがクライアントに処理を委譲します」ではなく、「UserService が AuthClient.refresh() を呼び出します」と書きます。
• 複雑なものはその理由を説明し、単純なものは一文で説明します。
• フローが複数のコンポーネントをまたぐ場合、またはデータが段階ごとに形を変える場合は、Mermaid 図を作成します。

次のセクションを使用します。調査結果に該当する内容がない場合に限り、そのセクションを省略します。

• 概要：一〜二段落で説明します。それが何で、何を行い、なぜ存在するのかを説明します。読み進めるか判断できるだけの情報を含めます。
• 主要な概念：以降の説明の基盤となる型、サービス、抽象化を、それぞれ一行で定義します。
• 仕組み：最も長いセクションです。何がきっかけとなり、何がどのような順序で起きるのか、データがどこへ渡され、どこで判断が行われるのかを説明します。ファイルや関数への参照を含む文章で記述し、要点の説明に必要な場合に限りコードスニペットを使います。
• 関連ファイル：最初に開くべき二、三個のファイルと、それぞれの重要性を説明します。
• 注意点：新しく参加した人がつまずきやすい、見落としやすい調査結果を記載します。
• 未解決の疑問：調査担当者が追跡できなかった箇所を、推測で補わず、未知の点として示します。

すべての調査結果が、活用されるか、別の結果と統合されるか、ここから着手するシニアエンジニアにとって不要な詳細として除外されていれば完了です。