how

仕組み

実際に動作するコードから、サブシステムについてシニアエンジニアとしての実践的な理解を組み立てます。注釈付きのソースコードにするのではなく、アーキテクチャと実行時の流れを説明します。

モードを選ぶ

• 「これはどのように動作しますか？」という質問では、Explainがデフォルトです。
• Placeは、「これはどこに配置すべきですか？」のような、所有者やレイヤーに関する質問に答えます。境界を提案する前に、関連するアーキテクチャをたどります。
• Critiqueは、アーキテクチャ上の問題点や改善すべき点についてもユーザーが尋ねている場合に適用します。設計を評価する前に、説明を完了します。

Explain ワークフロー

1. 質問の枠組みを定める

対象、求められる詳細度、可能性の高いエントリーポイントを特定します。対象が曖昧な場合は、会話とリポジトリの状況から最適な解釈を示します。解釈によって調査内容が異なる場合に限り、質問してください。

対象範囲を分類します。

• 狭い範囲： 1つのモジュール、ユーティリティ、関数、または限定された呼び出し経路。
• 広い範囲： 境界、サービス、永続化、または複数の独立したフローにまたがるサブシステム。

不確かな場合は狭い範囲から始め、説明のつかない境界が必要になった場合にのみ範囲を広げます。

完了条件： 対象、エントリーポイント、調査範囲が明確であること。

2. コードをたどる

狭い範囲の質問では、実装を直接たどります。広い範囲の質問では、状態、リクエストフロー、永続化、外部境界など、サブシステムを2〜4つの独立した観点に分けます。実行環境が独立した読み取り専用エージェントに対応している場合は、これらの観点を並行して調査します。対応していない場合は、順番に調べます。

委任して調査する場合は、references/explorer-prompt.mdを使用します。各観点について、エントリーから作用まで実際のシンボルと呼び出しをたどり、読んだファイルを記録し、推測で補わずに未解明の箇所を明示します。

完了条件： トリガーから観察可能な作用までの重要な各段階にコードの引用があり、追跡できていない各境界が未解決の質問として列挙されていること。

3. 実践的な理解をまとめる

調査結果間の重複や矛盾を整理します。調査結果に食い違いがある場合は、コードを読み直します。回答を自分で書く場合も委任する場合も、まとめの基準としてreferences/explainer-prompt.mdを使用します。

説明には、質問に必要なセクションのみを含めます。

• 概要： 目的と境界。
• 主要な概念： フローを理解するために必要な少数の型やサービス。
• 仕組み： トリガー、手順、データ変換、判断、作用。
• コードの配置場所： 新しいコントリビューターが最初に開くべきファイル。
• 注意点： 意外な挙動、未解決の箇所、扱いにくい部分。

コンポーネント間の相互作用やデータ変換が文章よりも視覚的に明確になる場合に限り、図を含めます。

完了条件： この領域に詳しくないシニアエンジニアが、すべてのファイルを開き直さなくても、エントリーポイントを特定し、主要な経路をたどり、サブシステムの境界を説明できること。

配置ワークフロー

まず、提案するコードが影響する挙動と境界をたどります。次に、候補となる配置先を次の観点から比較します。

• ドメイン上の責務と状態の所有権。
• 依存関係の方向とライフサイクル。
• 類似の挙動に関するリポジトリ内のパターン。
• 検証、エラー、副作用を担うべき境界。
• テストのしやすさ、およびリポジトリ内の根拠から予測できる次の変更。

配置先を1つ推奨し、なぜそこがその挙動を担うのかを説明します。また、何をインポートし、何を公開し、何を他の場所に残すべきかを示します。妥当な代替案を挙げ、それぞれが適合しにくい理由も説明します。実証された結合や繰り返し発生する複雑さを解消しない限り、新しいレイヤーは作成しないでください。

完了条件： 推奨案が現在の境界と類似コードを根拠としており、明確な所有者を1つ割り当て、最小限の統合手順を説明していること。

Critique ワークフロー

1. 説明を確立する

まずExplainワークフローを完了します。想定上の設計ではなく、実際に存在するアーキテクチャを評価します。

2. 独立した評価を集める

説明、関連ファイル、およびreferences/critic-prompt.mdをreferences/critique-rubric.mdとともに使用します。実行環境が並列レビューに対応している場合は、フレーミングバイアスを抑えるため、2名以上の独立した批評者を使います。対応していない場合は、ルーブリックを直接適用します。

この手法は、特定のエージェントプロバイダー、モデル、ランナーの設定に依存してはなりません。

**完了条件：**提案するすべての問題について、該当するコードを引用し、スタイル上の好みではなく実際に生じるコストを示していること。

3. 主担当者が判断する

各指摘を分類します。

• **対応する：**今すぐ修正する価値がある、実証されたアーキテクチャ上の問題です。
• **検討する：**実際の懸念事項ですが、コストや対処法がまだ不確かなものです。
• **記録する：**優先度の低いトレードオフ、または負債を示す目印です。
• **却下する：**誤り、根拠がない、または単なる好みの問題です。

最初に説明を提示し、その後に批評を続けます。アーキテクチャに問題がない場合、批評は空のままにします。

**完了条件：**重複する指摘が統合され、意見の相違が解決または明示され、残すすべての推奨事項に根拠、影響、適切な優先度が示されていること。