mastraudit

Mastraudit

Mastra の作業全体を通じて、実装時に高くつくミスを防ぐためのガイドとしてお使いください。既存の名称は、明示的に依頼された監査にも対応しています。

コードを変更する前に

1. 実行時の所有者と実際のバージョンを特定します。 CLI、ストレージ、エンジンアダプターを含め、呼び出し元のパッケージからパッケージを解決します。マニフェストの範囲指定、カタログの項目、ディレクトリ一覧は、インストール済みのバージョンを示すものではありません。そのバージョンに組み込まれたドキュメントと型に加え、設定済みのローカルベンダーミラーにある対応ページを読みます。最近更新されたミラーでも、より新しいリリースについて説明している場合があります。ローカルの情報が不足している場合は公開ドキュメントを使い、その不足を明記します。
2. 実際の先例を読みます。 既存の公開ブリッジ、ストレージプロバイダー、モデルポリシー、ドメイン操作に従います。実行経路が、通常のエージェント、耐久性のあるワークフロー、Studio チャット、HTTP、stdio MCP のどれかを特定します。それを構築するものと、公開する登録処理をたどります。所有権とインポートの変更については、構成を読みます。
3. コントラクトと上限を決めます。 有用な出力、明示的な失敗状態と完了状態、各ステップをまたぐ参照、出力、ステップ数、経過時間、再試行回数の上限を定めます。エージェントには判断に必要な操作を与えます。決定論的なワークフロー全体をラップすると、エージェントとの比較が循環的になる場合があります。ツールまたは構造化出力についてはコントラクトを、状態を伴う処理については実行を読みます。
4. 実行前に受け入れ確認の経路を選びます。 変更するジャーニーを1つ挙げ、観測可能な結果を定めます。まず、テストやインポートによる副作用を確認します。監査のみの範囲で許可されるのは、ソースの調査と安全なローカルチェックです。モデルの呼び出し、ワークフローの登録、ストレージへの書き込み、デプロイは許可されません。テスト、評価、完了の主張を行う前に、エビデンスを読みます。

これは短い実装上の判断であり、新たな計画書ではありません。プロジェクトでトラッカー項目を使っている場合は、エビデンスを担当の項目に記録します。

同じソース、インストール済みバージョン、実行環境に対して、確立済みの事前確認を再利用します。依存関係、インポート、設定、実行経路が変わった場合は、該当するコントラクトを再確認します。すでに確認済みのドキュメントを読み直したり、保存のたびに成功済みのゲートを再実行したりする必要はありません。

構築中

• ドメインの動作と正規スキーマはそれぞれの本来の場所に維持し、Mastra でそれらを連携させます。型チェックでは検証できない接着部分を調査します。登録キー、生成されたスキーマ、出力の射影、コールバックの配信、ストレージの注入、再開時の転送、モデル設定が該当します。
• 該当するインストール済みスキャナーを再利用します。実行前に、そのシグネチャーとカバレッジを確認します。スキャナーの出力は、実際の呼び出し元とサポート対象のコントラクトに照らして確認するまでは手掛かりにとどまります。利用できるスキャナーがない場合は、カバレッジの不足を明記します。存在しないパッケージエクスポートを捏造してはいけません。
• 依存関係を変更したり、フォールバックを追加したり、プロバイダーを責めたりする前に、最小限の再現方法を確立します。まずリクエストサイズ、有効な設定、ID、ソースのバージョン、永続化された状態を確認します。一度に変更する原因は1つにします。
• Studio では、時間を区切った実行の前に、所有者と安定したランタイム期間を調整します。オリジン、ホットリロード、古いバンドル、ローカル stdio、インラインアプリについては、Studio と MCPを読みます。
• 実証されたサイレント障害は、共有境界にある最小限で有用なガードに置き換えます。元の問題が起きたケースで失敗することを確認してから、そのガードを信頼します。焦点を絞ったチェックに通ったというだけで、広範なテストスイートを実行するのは避けます。

問題が発生した場合

症状	最初に調査する内容
空のオブジェクト、無視されるツール、拒否されるスキーマ	ネイティブの結果、生成されたプロバイダーのスキーマ、tools／構造化出力との互換性をcontractsで確認します。
手順が遅い、検索が繰り返される、以前の情報が見つからない	測定されたプロンプト／結果／スナップショットのサイズと、プロセッサーが保持する範囲をexecutionで確認します。
進捗が失われる、書き込みが重複する、再開できない	チェックポイント、ID、冪等性、永続状態をexecutionで確認します。
ユニットテストが予期せず接続または書き込みを行う	インポート時の初期化、環境変数の優先順位、ドライバーのガードをevidenceで確認します。
Studio の読み込みに失敗する、バンドル処理が停止する、実行結果が失われる	プロセス、オリジン、依存関係グラフ、再読み込みウィンドウをStudio and MCPで確認します。
HTTP では修正が機能するが、既存の MCP セッションでは機能しない	トランスポートのIDとプロセスの開始時刻をStudio and MCPで確認します。
インライン HTML は機能するが、エージェントのUIは機能しない	ツールのメタデータ、リソース、結果のエンベロープ、ゲストとホストのハンドシェイクをStudio and MCPで確認します。
スコアは合格しているが、回答が要件を満たさない	独立した期待値、必須要件、永続化された実験の証拠をevidenceで確認します。

完了と判断する前に

許可された証拠のうち、最も適切なもので変更した経路をテストします。ユーザーに表示される機能は想定されたホストで操作し、永続化される機能は保存された出力と復旧境界を確認します。こうした確認が許可されていない場合は、不足している受け入れ証拠を明記します。

簡潔な判定、変更内容、インストール済みバージョン、テストしたソース／ランタイムの正確な情報、対象を絞った証拠、残る課題を記載します。ソースの確認、ランタイムでの実行、永続化、ホストとのインタラクション、公開、デプロイは、それぞれ別の主張として扱います。明示的な監査では、確認済みの指摘事項を失敗時のコストに応じて「ブロッキング」「修正すべき」「要記録」に分類します。それぞれにfile:line、影響、修正方法を記載します。省略した確認項目については、カバレッジマップも含めます。

明記された受け入れ条件を満たしたら終了します。新たに見つかった無関係な問題は、際限なく追加確認を続けるのではなく、トラッカーに記録します。