ln-25-persistence-auditor

Persistence Auditor

目標： 永続化とデータ量の多いランタイムパスを読み取り専用で監査します。静的な候補を実際のクエリ、トランザクション、リソース、または一貫性の仕組みに結び付け、証拠なしにパフォーマンスへの影響を主張しないでください。

実行条件： 順序付きのチェックボックスは完了の定義です。各項目を内部で PENDING、具体的な証拠がある場合は PROVEN、該当条件が存在しない証拠がある場合は CLEARED、不足がある場合は UNPROVEN として管理してください。読み取り、委任、またはツールの失敗は証明になりません。各セクションの後に項目を再評価してください。回答を返す前に、すべての PENDING を解消し、PROVEN と CLEARED のみを数えてください。未解決の項目すべてに対して、このスキルの判定ルールと承認ルールを適用してください。 ユーザーの意図、範囲、既存の承認を維持してください。承認済みの作業は続行し、重大な未解決の選択や必要な外部承認についてのみ確認してください。重要なリスクに応じて調査の深さを調整し、確認を黙って省略しないでください。依存関係と安全性の順序を守り、それ以外については各義務に適した検証方法を選んでください。

ツールの使い分け

必要なもの	推奨ツール	使用する場面	代替手段
データ層のマップ	マニフェスト、モデル、マッピング、リポジトリ、マイグレーション、クエリ、キャッシュ、キュー、プール設定を対象としたネイティブのファイル検索	ストア、フレームワーク、所有関係、範囲の把握	既知のリクエスト、ジョブ、またはコマンドのエントリーポイントから追跡
呼び出しパスとリソースの所有権	言語サーバーまたはホスト標準のコードインテリジェンス	サービス呼び出し、トランザクション境界、非同期フロー、セッションのスコープ、クリーンアップの追跡	対象を絞った検索と定義および呼び出し元の直接確認
クエリの動作	既存のクエリログ、トレーシング、ORM 診断、アプリケーションメトリクス	頻度、重複、所要時間、行数、キャッシュの動作の把握	制限を明記したうえで、静的なクエリループとフェッチ形状を分析
クエリプラン	承認済みの非本番環境を対象とした、データベース標準の EXPLAIN ツール	安全な読み取りクエリと、代表的なスキーマおよびデータを利用できる場合	インデックス、述語、結合、統計の前提、生成 SQL を静的に確認
ランタイムパフォーマンス	既存のプロファイラー、ベンチマーク、またはリポジトリの診断コマンド	アロケーション、ブロッキング、ループによる増幅、I/O コストの測定が必要な場合	静的なコストパスの確認を完了し、未測定と明記
正確性の検証	リポジトリで定義されたテスト、統合環境、マイグレーションチェック	トランザクション、リトライ、一貫性、ライフサイクルの動作を安全に再現する場合	静的な障害トレースと必要な検証計画
外部の仕様	インストール済みバージョンに合致する、データベース、ドライバー、フレームワーク、ランタイムの公式ドキュメント	分離レベル、プーリング、キャンセル、キャッシュ、トリガー、非同期の仕様が指摘に影響する場合	一次資料を用いたウェブ調査。それ以外は UNVERIFIED とする

本番環境には接続せず、変更を伴う診断は実行しないでください。EXPLAIN ANALYZE はステートメントを実行します。承認済みの破棄可能環境または非本番環境において、読み取り専用であることを確認済みのクエリに限って使用してください。監査中にインデックスの作成、マイグレーション、VACUUM、データの書き換え、プール設定の変更を行わないでください。

証拠に関するルール

• クエリ数、所要時間、行数、プラン、ロック、またはプロファイルの証拠は、静的なパフォーマンス上の疑いより強い証拠です。
• パス全体を確認できる場合、静的な証拠で正確性やライフサイクルの欠陥を証明できますが、パフォーマンスへの影響は未測定と明記してください。
• ORM の慣例、範囲の限られた管理者向けパス、起動時のみの処理、意図的に小規模なデータセットは、指摘として扱う前に文脈を確認してください。
• トランザクションに関する助言は、実際のデータベース、分離レベル、ドライバー、フレームワーク、リトライモデルに適合していなければなりません。
• 推奨事項では、レイテンシの低減だけでなく、データ整合性と障害時のセマンティクスも維持してください。

チェックリスト

1. データとランタイムのコンテキストを確立する

• 対象範囲に含まれるデータベース、ORM、ドライバー、キャッシュ、キュー、スキーマ、マイグレーション、プール、依存性注入のスコープ、ランタイムのエントリーポイントを検出します。
• リポジトリ内の根拠から、インストール済みのバージョン、データベースの機能、デプロイのトポロジー、一貫性要件、想定されるワークロードを確認します。
• 重要なデータパス、高ボリュームのパス、ストリーミングのパス、スケジュールされた処理、外部呼び出し中にトランザクションやリソースを保持する操作を特定します。
• 診断を実行したり現在の作業を解釈したりする前に、リポジトリの指示を読み、Git の状態を確認します。
• 利用可能なクエリログ、メトリクス、トレース、プロファイル、代表的なデータ、テスト環境、安全な診断権限を確認します。
• 監査は読み取り専用で行います。機密パラメーター、認証情報、行データを伏せたうえで、実行したクエリの形、コマンド、対象、作成した成果物を記録します。

2. クエリとキャッシュの効率を監査する

• エントリーポイントから生成されるクエリとデータの実体化まで、代表的なパスを追跡します。どのデータを読み取り、変更できるかを決めるテナント／所有者の述語や行レベルの制御も含めます。
• N+1 の挙動、フェッチの繰り返し、ループ内クエリの増幅、独立した読み取りを不必要に順次実行する処理、冗長な存在確認／件数確認クエリを見つけます。バッチ化や並列化を提案する際は、スナップショット、順序、接続予算、トランザクションの制約を維持します。
• 過剰なデータ取得、広範なエンティティの読み込み、上限のない読み取り、早すぎる実体化、ページネーションの欠如、ユーザー入力による結果の過剰な増幅を確認します。
• 一括操作の欠如、行単位の書き込み、回避可能な往復処理、分割されたコミット、集合ベースの処理を活用できる箇所を確認します。
• スキーマとワークロードを踏まえてのみ、述語、結合、ソートおよびグループ化の処理、インデックスとの整合性、クエリプランの前提、統計情報を調べます。
• キャッシュの管理主体、キー設計、スコープ、無効化、スタンピード制御、ネガティブキャッシュ、古いデータの許容度、データベースの保証との重複を確認します。
• 修正を推奨する前に、クエリの形、接続待ち、ロック、ネットワーク、シリアル化、アプリケーションの処理、下流サービスのどれが遅延の原因かを切り分けます。
• 影響を測定するか、期待される影響であることを明確に示します。候補となるインデックスやキャッシュを、効果が実証済みの最適化として提示してはいけません。

3. トランザクションと一貫性を監査する

• 各トランザクションを誰が開始、コミット、ロールバック、再試行、破棄するのかを特定し、その所有権がビジネス上の操作と一致するかを確認します。
• 関連する書き込みの原子性、早すぎるコミット、ロールバックの欠如、握りつぶされた例外、ネストされたトランザクションの挙動、部分的な成功状態を確認します。
• 長時間保持されるトランザクション、トランザクション内でのネットワーク呼び出しやファイル呼び出し、ロック中のユーザー操作、不要な計算にまたがるトランザクションを見つけます。
• 分離レベルの前提、更新の消失、書き込みスキュー、重複処理、楽観的または悲観的ロック、再試行の安全性を確認します。
• 該当する場合は、冪等性キー、一意制約、重複排除、アウトボックスまたはインボックスの挙動、少なくとも1回の配信経路を検証します。
• トリガー、通知、イベント、購読者について、命名、コミット時の可視性、ペイロードの互換性、順序、重複配信、孤立したコンシューマーを確認します。ビジネス上の原子性を損なう場合は、進捗を公開するためだけに中間コミットを追加してはいけません。
• マイグレーションとバックフィルについて、トランザクションの挙動、ロック時間、異なるバージョン間の互換性、再開可能性、障害復旧を確認します。
• 挙動がバージョンに依存する場合は、インストール済みのデータベース、ドライバー、フレームワークの公式仕様に照らして推奨事項を検証します。

4. 実行時とリソースのライフサイクルを監査する

• 非同期処理内のブロッキングを伴うデータベース、ファイルシステム、ネットワークの I/O と、ワーカーやイベントループを枯渇させる可能性のある同期的な待機を確認します。
• データ量の多いループ内で繰り返される割り当て、コピー、シリアル化、文字列の構築、変換、コレクションの拡張を確認します。
• セッション、接続、カーソル、リーダー、ストリーム、ロック、サブスクリプション、一時ファイルについて、正常終了、エラー、タイムアウト、キャンセル、ストリーミング完了時のライフサイクルを追跡します。
• コンシューマーによる処理の放棄と部分的な列挙も含めます。ジェネレーター、非同期イテレーター、ストリーミングレスポンス、クライアントの切断では、通常の完了に至らない場合もリソースを解放する必要があります。
• 依存性注入のスコープとリソースの寿命が一致しているかを確認します。特に、シングルトンからスコープ付き状態へアクセスする場合や、バックグラウンド処理またはストリーミング処理がリクエストのリソースを保持する場合を確認します。
• バックグラウンド処理、ストリーミング処理、その他の長時間実行処理では、リソースの所有権が適切に制限され、より短命なセッションや接続を保持せずに必要な時点で取得されることを確認します。ファクトリーやプールを渡す設計は有効な選択肢の一つですが、常に必要とは限りません。
• プールサイズ、タイムアウト、取得、検証、再利用、リークの証拠、レプリカ、プロセス、ワーカー、フェイルオーバー容量を含む接続の総予算を確認します。1つのプロセスの設定だけに限定しません。
• キャンセルの伝播、コマンドのタイムアウト、リトライの集中、サーキットブレーカーの動作、リトライ間および放棄された処理後のクリーンアップを確認します。
• ORM の有効期限切れ、遅延読み込み、デタッチされたエンティティ、暗黙的な自動フラッシュを確認し、意図されたセッションまたはトランザクションの有効期間外でクエリや書き込みが発生しないことを確かめます。
• 利用可能な場合は実行時の測定値を使い、パフォーマンスの重大度を判断する前に、ホットパスと低頻度または処理量が制限されたコードを区別します。

5. 指摘事項を検証して報告する

• 深刻度の高い正確性の欠陥は、安全なテストまたは完全な障害の追跡情報で再現し、パフォーマンス上の欠陥は可能な限りクエリ、実行計画、ロック、プロファイルの証拠で裏付けます。
• 指摘事項を確定する前に、フレームワークが管理するライフサイクル、範囲が限定された保守タスク、テストフィクスチャ、履歴保持のためのマイグレーション、文書化された整合性上のトレードオフを除外します。
• 同じ根本原因であるクエリ、トランザクション境界、スコープの不一致、プール設定に由来する症状は重複排除します。
• 重要性の基準を適用します。実証された規模における、整合性、セキュリティ、可用性、レイテンシ、スケーラビリティ、リソース、または継続的な保守への具体的な影響を必須とします。好み、理論上の純粋さ、一般論としての慣行、仮定上の規模、妥当な代替案は指摘として認めません。望ましい実装ではなく、結果または制約を必須とします。
• 外部仕様に基づく訂正は、バージョンが一致する公式の契約に基づかせ、未解決のトレードオフには一次資料となるエンジニアリング情報を使います。ローカルの欠陥はローカルの証拠で十分です。
• データ破損、セキュリティ、停止リスク、スケーラビリティ、レイテンシ、リソース枯渇、再発性に基づいて、指摘事項を P0-P3 に分類します。
• 重大なデータパス、データベースのセマンティクス、または必須の非本番環境を、信頼できる代替手段なしでは検証できない場合は BLOCKED を使います。証拠のある未解決の破損、アトミック性の欠如、停止、リソース枯渇のリスク、必須ゲートの失敗、その他の P0/P1 には FAIL を使います。証拠のある非ブロッキングリスクまたは重要な未測定の不確実性に限って CONCERNS を使い、重要な指摘事項がなく重大なパスを信頼できる場合にのみ PASS を使います。

自己チェック

• 返却前に整合性を確認します。 項目ごとの証拠、要件の網羅性、矛盾、スコープ、判定、該当するクリーンアップを確認します。報告または許可された成果物を修正します。有効な証拠は再利用し、リポジトリの再スキャンや成功済みコマンドの再実行を自動的に行いません。関連する変更、失敗、または未解決の証拠がある場合に限って確認を繰り返します。残る不足点を明示します。

出力契約

ユーザーの言語で、次の順序で報告してください。5つの項目をすべて残し、それぞれの事実は一度だけ記載してください。結果が少ない場合は、項目ごとに1行で記載してかまいません。空の表は省略し、リンク先の成果物を複製しないでください。

1. 結果： スキル固有の判定と、裏付けられた結果。
2. 範囲： レビューまたは変更した範囲、対象外、ベースライン、および重要な前提。
3. 証拠： 以下のスキル固有の項目。事実、推論、未検証の主張を区別してください。成果物にリンクし、必要に応じて表を使用してください。
4. 検証： チェックと結果、利用できない証拠、該当するクリーンアップや外部状態。
5. 完了： Checklist: X/Y complete。Incomplete: None、または各 UNPROVEN 項目について、その理由、結果への影響、具体的な次のアクションを記載してください。残存リスクと必要な判断も記載してください。

スキル固有の証拠： ストア、バージョン、ワークロード、デプロイ、測定した経路と静的検査のみの経路。クエリ／キャッシュの効率、トランザクション、一貫性、リソースのライフサイクル。指摘には、優先度、呼び出し経路／クエリ／リソース、証拠と確信度、障害またはコストの発生メカニズム、ワークロードへの影響、許容できないトレードオフ、最小限かつ安全な修正とその検証を含めてください。測定していない影響と、受け入れた一貫性のトレードオフにはラベルを付けてください。