data-systems-coding-lens

データシステムのコーディングレビュー

このスキルを使って、コーディング作業に実践的なデータシステムのレビューを取り入れます。目的は理論を説明することではありません。本番環境のバグになる前に、障害につながる要因を見つけることです。

すべてのレビューの基盤となり、以下のチェック項目でも繰り返し登場する重要な概念が2つあります。信頼できる唯一の情報源：各事実を永続的に管理する唯一の場所を明確にします。そうすれば、派生したコピー（キャッシュ、インデックス、読み取りモデル）は常にそこから再構築できます。冪等性：再試行または再生される可能性がある書き込みは、2回目も必ず同じ結果になる必要があります。金銭、メール、ジョブ、レコードが重複してはなりません。レビューでは、この2つをそれぞれ明示してください。

最初の確認

まず、状態の境界を特定します。

1. どのデータが作成、読み取り、更新、削除、キャッシュ、派生、または出力されますか？
2. 信頼できる唯一の情報源はどこですか？
3. どの処理経路が同期、非同期、再試行、再生されますか？また、どの処理経路がユーザーに表示されますか？
4. どの不変条件が破れると機能が正しくなくなりますか？その条件はコードのどこで検証されていますか？
5. どの障害が気づかれにくく、コストが高く、または修復しにくいですか？

タスクが小さい場合は、この確認を簡潔に済ませ、実装に組み込みます。共有データ契約や本番データに触れるタスクでは、編集を始める前に回答を書き留めてください。

単純なUI文言、スタイル調整、単発スクリプト、ドキュメントのみの編集、ローカルで使い捨てるユーティリティを過度に複雑に扱わないでください。こうしたケースでは、永続データ、バックグラウンド処理、または本番運用上のリスクに変更が関係する場合に限り、この観点を適用してください。

実装の観点

コードを変更するときは、以下の領域を順に確認します。

データモデルと契約

スキーマの構造、NULL 許容性、列挙型の拡張、識別子の安定性、タイムゾーン、所有権、一意性、後方互換性を確認します。

以下を確認してください。

1. 古いライターと新しいリーダーは共存できますか？
2. 新しいライターと古いリーダーは共存できますか？
3. ロールバックの手段はありますか？
4. 移行時のデフォルト値は既存データに対して安全ですか？
5. API 契約はクライアントやジョブにとって十分に明確ですか？

クエリとストレージの経路

クエリのカーディナリティ、インデックスの網羅性、ページネーション、ソートの安定性、キャッシュキー、キャッシュの無効化、トランザクションの範囲、ロックの動作を確認します。

以下を確認してください。

1. ユーザー数、テナント数、行数、イベント数、または時間の増加に伴って、何が増えますか？
2. コードによって、1つのリクエストが意図せず複数回のデータベース往復になっていませんか？
3. データの増加に伴い、クエリプランが大きく悪化する可能性はありませんか？
4. 再試行時の書き込みは冪等ですか？
5. 同じ操作が自身と競合する可能性はありますか？

信頼性と障害

再試行、重複メッセージ、部分的な書き込み、タイムアウト時の動作、不正なメッセージ、デッドレター処理、ユーザーが利用できる復旧手段を確認します。

プロセスのリソースも確認します。ファイル、ハンドル、ロック、トランザクション、サブスクリプション、タイマー、ソケットは、それぞれ明確な所有者と、成功時、失敗時、キャンセル時のクリーンアップ手段が必要です。

以下を確認してください。

1. 2つの書き込みの間でクラッシュした場合、どうなりますか？
2. 外部サービスが成功した後、ローカルの書き込みが失敗した場合、どうなりますか？
3. ローカルの書き込みが成功した後、外部サービスがタイムアウトした場合、どうなりますか？
4. 再試行によって金銭、メール、通知、ジョブ、またはレコードが重複する可能性はありますか？
5. 運用担当者は、障害をどのように検知し、修復しますか？
6. 正確性が暗黙の時間順序に依存していませんか？順序を明示する状態、キュー、ロック、トランザクション、冪等性キー、またはバージョンチェックを導入し、暗黙の依存を解消してください。

分散システムの振る舞い

複数のプロセス、ワーカー、リージョン、データベース、キュー、キャッシュ、または外部システムがある場合に使用します。トポロジー、つまり各プロセスがどの Burns パターン（サイドカー、シャード、散布／集約、選出かシングルトンか、ワークキュー）を形成するかは、distributed-systems-patterns で扱います。このセクションでは、そうした選択に伴うコードレベルの障害モードを扱います。

順序に関する前提、古い読み取り、読み取り後の書き込みの要件、リーダー選出、リース、クロックへの依存、整合性レベル、トランザクション境界、調整を確認します。

次の点を確認してください。

1. 正しさを保つために、単一のグローバルな順序が必要ですか？
2. このユーザーフローでは、結果整合性を許容できますか？
3. どの操作に強い整合性が必要で、どの操作は後から調整できますか？
4. 2 つのアクターが同じエンティティを同時に更新すると、どうなりますか？
5. 派生状態を再構築できる信頼できる情報源はありますか？

進化と保守

デプロイ順序、フィーチャーフラグ、バージョン管理されたペイロード、スキーマ移行、バックフィル、再構築、可観測性、クリーンアップ計画を確認します。

次の点を確認してください。

1. この変更を複数回に分けてデプロイできますか？
2. 移行を一時停止して再開できますか？
3. 永続的な入力から派生データを再構築できますか？
4. ログ、メトリクス、トレースがあれば、実際の本番環境の経路をデバッグできますか？
5. ロールアウト後に、どの古いコード、データ、フラグ、ジョブをクリーンアップする必要がありますか？

design-gate では、呼び出し元が定める標準的なゲート結果を使用します。これにより、単独での出力と編集の手順に置き換わります。レンズ固有の結論は、安定した指摘 ID を付けて、指摘または review_focus に記載します。インタビューでは、既存の意思決定記録に判断項目を追加します。

出力パターン

実装作業では、役立つ場合はコーディング前に短い注記を追加します。

Data systems lens:
State touched:
Invariant:
Main risk:
Verification:

コードレビューでは、具体的な指摘から始めます。

Finding:
Why it matters:
Failure case:
Suggested fix:
Verification:

アーキテクチャ設計や計画では、次の簡潔な意思決定記録を使用します。

Decision:
Source of truth:
Consistency requirement:
Failure handling:
Migration path:
Observability:
Open question:

検証のデフォルト

実際の境界を通る検証を優先します。

1. 不変条件と冪等性を対象とする単体テスト。
2. データベース、キュー、キャッシュ、外部 API の境界を対象とする統合テスト。
3. 既存のデータ形式を用いた移行チェック。
4. 競合状態と重複作業を対象とする並行性テスト。
5. カーディナリティがリスクとなる場合の負荷チェックまたはクエリプランチェック。
6. ログ、メトリクス、トレース、修復シグナルの可観測性チェック。

最終回答の要件

このスキルによって作業内容が変わった場合は、最終回答で最も価値の高いチェックに触れます。簡潔にまとめます。

I also checked the data systems risk: [state or invariant], [main mitigation], [verification].