メンタルモデル
アクター、境界、通信を通じてシステムを説明します。
出力契約：図が最優先
完成したメンタルモデルの説明には、必ず回答自体に図を含める必要があります。 読者の方向付けのために短い一文を書き、その後すぐに以下のいずれかを含めてください：
- フェンス付きの
mermaidブロック（sequenceDiagramとautonumberを使用したデフォルトの形式）。 - 埋め込まれたレンダリング済みD2画像（レンダリングが利用可能で、D2がリクエストされた場合）。
その後、フローとその進化を簡潔な散文で説明します。図は長い説明を書く前に作成し、視覚要素が最後に削除されないようにします。 この契約は、明示的に呼び出されたメンタルモデルの議論を継続する短い回答やフォローアップの説明にも適用されます。質問の明確化だけでは図は必要ありません。ユーザーが明示的に図を不要とリクエストした場合は、そのリクエストに従います。
ASCII矢印、箇条書き、表、通常のコードブロック、図へのリンク、後で描くという約束、レンダリングされていないD2ソースは、この契約を満たしません。ユーザーに図が必要かどうかを尋ねないでください。レンダラーが利用できない場合でも、Mermaidソースを出力してください。チャットがレンダリングできないからといってテキストに置き換えないでください。Mermaidコードブロックには図生成ツールは必要ありません。
必要な回答形式の例（アクターを実際のコンテキストに適応させてください）：
ブラウザがAPIにデータの保存を要求します。APIはデータベースへのアクセスを所有します。
```mermaid
sequenceDiagram
autonumber
participant ブラウザ
participant API
participant データベース
ブラウザ->>API: フォームデータを保存
API->>データベース: 受け付けたデータを保存
データベース-->>API: 保存済みレコード
API-->>ブラウザ: 成功レスポンス
```
フォームはブラウザで開始されます。APIを追加することでリモート保存が可能になり、データベースを追加することで保存されたデータが個々のリクエストを超えて存続できるようになります。
明示的な呼び出し
このスキルは、ユーザーが明示的に /mental、$mental、またはメンタルスキルの使用を直接リクエストした場合にのみ使用してください。説明の一般的なリクエストはこのスキルを起動しません。これは説明のリクエストとして扱い、説明対象のシステムの実装、インストール、公開、変更の許可としては扱いません。
呼び出しに続くトピックを使用するか、会話から推測してください。トピックを合理的に推測できない場合にのみ、1つの焦点を絞った質問をしてください。
説明の構築
- モデルを会話と利用可能な証拠に基づかせます。既存のコードベースの場合は、関連する関係性を確立するために必要なエントリポイントまたは設定のみを検査します。観測された事実と仮定を区別します。サービス、成功したデプロイ、検証された動作をでっち上げないでください。
- 最小限の有効なシステムから始めます：ローカルで実行する1つのスクリプト、ページを表示するブラウザ、リクエストに応答するサービス。インフラを導入する前に、すでに機能しているものを説明します。
- 議論中のシステムに向かって進みます。意味のある各段階で、新しいニーズ、それを満たすために追加されたアクターまたは接続、およびアクションがどのようにシステムを通過するようになったかを説明します。これらは説明の段階であり、歴史的な時系列に関する主張ではありません。ユーザーが実際のプロジェクトの進化について尋ねた場合は、利用可能な履歴を使用し、ギャップを特定します。
- アクターはコンテキストに応じて選択します：人、プロセス、サービス、ストレージ、レジストリ、キュー、または外部プロバイダー。各アクターに具体的な役割を与えます。関連するアクターをマシン、プロセス、またはネットワーク境界でグループ化します（位置が理解に影響を与える場合）。
- 1つの具体的なアクションをアクター間で順に追跡し、呼び出し元に結果が返されるところまで含めます。各境界を越えるものをラベル付けします：ソースコード、パッケージアーカイブ、HTTPリクエスト、JSONレスポンス、イベント、または保存されたデータ。セットアップと配布をランタイム通信から分離します（両方が重要な場合）。
- 混乱を解消する場合にのみ区別を説明します。たとえば、パッケージ名は何を取得するかを選択し、コマンド名は何を実行するかを選択し、引数はそのコマンドへの入力になります。ブラウザ/APIの例では、コードの配信と後続のAPIリクエストを区別します。
用語集やコンポーネントのカタログよりも、関連する散文による短い進行を優先します。ユーザーが現在の相互作用のみを望んでいる場合は、長い進化を強制せずにそのフローを示します。コマンドとスニペットはモデルの基盤となるべきです。フラグの一覧、実装のウォークスルー、無関係な代替案は避けてください。キャッシュによるダウンロード回避や、作業終了前に届く非同期確認など、モデルを変更する詳細は保持します。
図の正確性
このスキルで生成されるすべての回答には、少なくとも1つのMermaid図またはレンダリングされたD2画像が含まれている必要があります。デフォルトではフェンス付きの mermaid ブロックを使用します。これはレンダリングツールが不要で、レンダリングが利用できない場合でもソースが読み取り可能です。
- 番号付きのシーケンス図を優先します：Mermaid図は
sequenceDiagramで始め、その後にautonumberを続けます。呼び出し、メッセージ、応答の順序を可視化します。参加者を読みやすい左から右の順序で導入します。 - 応答もリクエストと同様に番号付けし、読者が完全な相互作用を追跡できるようにします。散文で番号付きのステップを追跡し、図との参照を一貫させます。番号付けは図示されたシナリオを示すものであり、並行処理が常に1つの固定された順序で実行されるという主張ではありません。並行処理、代替案、またはオプションのステップがモデルを変更する場合は、
par、alt、またはoptを使用します。 - 進化を説明する場合は、意味のある各段階に対して別々の小さな番号付きシーケンスを使用します。参加者名は安定させ、どのアクターまたはメッセージが追加されたかを説明します。
- フローチャートは、トポロジーまたは構造が主な問題であり、シーケンス図ではそれが不明瞭になる場合、またはユーザーがリクエストした場合にのみ使用します。相互作用を示すD2画像の場合は、シーケンスレイアウトを優先し、メッセージに明示的に番号を付けます。
- 具体的なアクター名と、アクションまたはデータでラベル付けされた方向性のある矢印を使用します。ラベルのない矢印や、何も説明しない装飾的なボックスは避けてください。
- 各図は説明対象の相互作用に焦点を絞ります。異なるフェーズや混雑したシステムは、小さな図に分割します。段階的な図では、新しく導入されたアクターと接続をマークします。
- ラベルはシンプルに保ち、句読点を含むフローチャートラベルは引用符で囲みます。ノード参照、矢印の方向、サブグラフ、およびフェンス付きの構文を送信前に確認します。
- パッケージレジストリはコードを配布します。ユーザーのCLIを実行するものとして描かないでください。データベースはデータを保存します。それが実際のシステムの機能でない限り、データベースが通常のアプリケーションリクエストを開始するものとして描かないでください。
- ユーザーがD2を好み、レンダラーが利用可能な場合は、結果をレンダリングして検査し、画像を埋め込みます。D2ソースだけでは画像要件を満たしません。レンダリングが利用できない場合は、Mermaidを使用し、フォールバックを簡単に説明します。モデルを説明するためだけにレンダラーをインストールしないでください。
図の後に、具体的なアクションの短いウォークスルーを続けます。モデルが明確になった時点で終了します。実装タスクや汎用的な要約を追加しないでください。
送信前の確認
回答自体を検査します：フェンス付きの mermaid ブロックまたは埋め込まれたレンダリング済みD2画像が含まれていますか？どちらも存在しない場合、説明は不完全です。送信前に図を追加してください。Mermaidシーケンス図の場合は、autonumber が存在することを確認します。その矢印が散文と一致し、具体的なアクターとラベル付きの通信を使用して少なくとも1つの実際の相互作用を追跡していることを確認します。
例
例が説明の調整に役立つ場合は、references/examples.md を参照してください。npm配布、フロントエンド/バックエンド呼び出し、サービス間呼び出し、非同期ジョブが含まれています。アプローチを実際のコンテキストに適応させ、それらのアクターをすべての説明にインポートしないでください。