code-review

コードレビュー

正確性とセキュリティのゲートです。確信度の高い指摘のみ報告してください。確実な問題だけを指摘します。曖昧な場合は「変更をリクエストする」とします。結束性、抽象化の粒度、循環依存、デッドコードといった構造上の懸念は構造レビューの対象です。ここでは正確性とセキュリティを担当します。

リポジトリに、スタックのルール（パッケージマネージャー、CSS フレームワーク、フレームワークのバージョン、UI ライブラリ）への準拠を確認する自動チェックがある場合、すでにチェック済みの内容を重ねて指摘しないでください。

対象範囲

• 入力： 1 つの差分、ブランチ、または PR です。読み取り専用の git および gh コマンドで対象範囲を確認します。
• 出力： Block Merge／Request Changes／Approve に分類した指摘の一覧です。各指摘にはファイル、行、1 文の理由を記載し、これとは別に Spec レポートを示します。
• 読み取り専用： このスキルはレポートを作成します。ファイルの編集、PR の作成、変更、デプロイは行いません。すべての出力は助言であり、確認は必要ありません。
• 境界： 個別の差分または PR のみを対象とします。構造上の観点（モジュールの結束性、抽象化の粒度、循環依存、デッドコードの導入、API サーフェスの肥大化、アーキテクチャへの適合性）を再検討しないでください。これらは構造レビューに委ねます。差分に明らかなセキュリティ上の問題があれば指摘しますが、網羅的な監査（OWASP の評価基準、依存関係の CVE、タイミング攻撃、権限昇格の経路）は試みず、専任のセキュリティ監査に委ねます。モジュールの深さや継ぎ目の配置に関する指摘であれば、コードベース設計レビューを推奨してください。レビュー依頼から、マージやキューの処理を推測して実行してはいけません。

2 つの軸

以下のチェックリストは Standards 軸（正確性、セキュリティ、リポジトリの衛生状態）です。これと並行して Spec 軸でも確認してください。すべての標準に従っていても誤った機能を実装する変更を見逃さず、課題の要求に合致していても規約に反する変更を見逃さないためです。

• すべての標準に従っているが、誤った機能を実装している：Standards は合格、Spec は不合格です。
• 課題の要求どおりだが、プロジェクトの規約に反している：Spec は合格、Standards は不合格です。

## Standards と ## Spec のそれぞれに報告してください。軸をまたいで指摘を統合したり、順位を付け直したりしないでください。

Spec 軸の手順

1. 固定点を特定します。 ユーザーが指定したものを固定点とします。コミット SHA、ブランチ、タグ、main、HEAD~5 などです。指定がない場合は質問してください。レビュー前に、それが解決可能であり、差分が空でないことを確認してください（git diff <fixed-point>...HEAD）。

2. 仕様の出典を特定します。 次の順に確認してください。

   1. コミットメッセージ内の Issue 参照（#123、Closes #45）を gh で取得します。
   2. ユーザーが引数として指定したパス。
   3. docs/、specs/ 以下にある、ブランチに一致する仕様ファイルまたは Issue 本文。
   4. 何も見つからない場合は質問してください。仕様がない場合は Spec 軸を省略し、「仕様はありません」と報告してください。

3. 仕様に関する指摘を報告します。

   • 仕様で求められているが、欠落している、または部分的にしか実装されていない要件
   • 差分に含まれているが、要求されていない動作（スコープの逸脱）
   • 実装されているように見えるが、実装が誤っている要件

   指摘ごとに、該当する仕様の行を引用してください。必須の動作が欠落する仕様上の不備は Block Merge です。スコープの逸脱は、ユーザーがすでに了承している場合を除き Request Changes です。

重要なチェックリスト（Standards 軸）

1. セキュリティとデータ分離

• すべてのクエリでテナント／組織によるフィルタリングが行われていること（マルチテナントの場合）
• すべてのクエリで論理削除されたレコードが除外されていること（該当する場合）
• テナント間のデータアクセスがないこと
• 保護対象のルートに認証ガードがあること
• 意図しない公開エンドポイントがないこと：各ルートの認証方針が意図どおりであること
• DTO／スキーマによる入力検証があること
• コミットまたはログにシークレット、トークン、認証情報が含まれていないこと

2. TypeScript

• any 型は禁止です。適切なインターフェースまたは名前付き型を *.types.ts で定義してください
• 型ガードなしで unknown をそのまま使用しないでください（そのままの unknown は遅延された any です）
• 説明コメントなしで as X キャストを使用しないでください
• インターフェース／props は専用ファイルに定義し、コンポーネントやサービスのファイル内にインラインで定義しないでください
• すべての関数に戻り値の型を指定してください
• console.log は使用しないでください。プロジェクトのロガー（LoggerService、pino、winston）を使用してください
• 説明コメントなしで @ts-ignore または @ts-expect-error を使用しないでください

3. パターンへの準拠

• 既存のコードベースのパターンに従ってください（問題として指摘する前に、実際の例を3つ以上確認してください）
• 相対インポートよりパスエイリアスを使用してください

4. データベース

• すべてのクエリにテナント／組織のフィルターを含めてください（該当する場合）
• すべてのクエリに論理削除のフィルターを含めてください（該当する場合）
• 大きなドキュメントにはプロジェクションを使用してください
• クエリパターンに対応するインデックスが存在することを確認してください
• 差分内に N+1 クエリがないことを確認してください
• 失敗時に DB が中途半端な状態になり得る、連続した await db.update() 呼び出しは、トランザクションでラップするか、単一のアトミックな書き込みにまとめてください

5. エラー処理

• try/catch ブロックを設けてください
• 汎用の Error ではなく、フレームワーク固有の例外を使用してください
• ロガーサービスを通じてエラーを記録してください
• クライアントには汎用的なメッセージを返してください（内部情報を公開しないでください）

6. テスト

• ユニットテストが存在し、パスすること
• すべてのパブリックメソッドをテストすること
• エラーケースをテストすること
• テストではコードが実行されることだけでなく、動作を検証すること（実質のないスナップショットテストは禁止）

7. フロントエンド

• 非同期呼び出しを行う useEffect では、クリーンアップ処理を実装してください（AbortController）
• ローディング状態とエラー状態を処理してください
• インタラクティブな要素を追加する場合は、ARIA ラベルを含むセマンティック HTML を使用してください

8. API

• 適切な HTTP ステータスコードを使用してください
• リクエスト／レスポンスには DTO を使用してください
• プロジェクトで API ドキュメント用デコレーター（例：@ApiOperation ／ @ApiResponse）を使用している場合は、それらを追加してください
• API の利用者に内部のスタックトレースが漏れないようにしてください

9. 開発環境の回帰

他のエンジニアのローカル開発ループを気付かれないまま壊す変更：

• 環境変数の名前変更または追加： .env.example ／ .env.template は更新されていますか？ 名前の変更は告知されていますか（移行メモ、変更履歴、または PR の説明など）？
• シークレットの読み取り方法の変更： 実行時にアクセスする新しいシークレットが、文書化されたセットアップ手順に含まれていない場合。または、ランブックを更新せずに、アクセス先を別のプロバイダー／Vault の経路に変更した場合
• ポートまたはネットワークの再マッピング： README／セットアップドキュメントと依存するすべての設定ファイルを更新せずに、サービス、開発サーバー、または docker-compose のポートを変更した場合
• 新たに必須となるセットアップスクリプト： アプリの起動前に実行が必要なマイグレーション、シード、または一度限りのブートストラップが追加され、PR の説明またはセットアップガイドに記載されていない場合
• ビルドフローの変更： 必須のビルド手順の追加、出力ディレクトリの変更、または既存の開発／ビルドの契約を壊す package.json の pre/post スクリプトの追加があり、明確な移行メモがない場合

開発環境の回帰が告知されていない場合は、マージをブロックしてください。文書化されていても、記載場所が適切でない場合は変更を依頼してください。

10. 機能フラグ／ゲートの漏れ

ゲートで制御する予定の機能が、フラグなしまたは一部のみフラグで制御された状態でリリースされるケース：

• 明らかな漏れ： PR の説明ではフラグで制御されるとされている新しいルート、コンポーネント、または API エンドポイントで、フラグチェックがない場合、または UI にしか適用されず API ハンドラーには適用されていない場合
• 見つけにくい漏れ： 正常系のパスにはフラグチェックがあるものの、同じサービスメソッドを呼び出すエラーハンドラー、バックグラウンドジョブ、または管理者専用パスにはない場合
• 常時有効な定数： 実際のフラグ評価の代わりに const ENABLE_NEW_CHECKOUT = true を使用している場合。これは整理されることがなく、フラグサービスを迂回します
• 削除計画なしに導入されたフラグ： フラグ削除のための関連 issue または TODO コメントがない場合。フラグ名から想定される有効期間が明確に分かるようにしてください
• ロールアウト設定の不整合： PR でフラグが定義されているものの、ロールアウト率／ターゲティングルールが未設定、またはデフォルトで 100% になっていて、ゲート制御の目的が損なわれている場合

未リリースの機能をすべてのユーザーに公開するフラグの漏れは、マージをブロックする理由となります。削除チケットの不足は「変更を依頼」としてください。

承認基準

マージをブロック

• セキュリティ上の問題が存在する
• テナント／組織によるフィルタリングが不足している（必要な場合）
• any 型、または型ガードのない単独の unknown
• テストが失敗している、または新しいパブリックメソッドのテストがまったくない
• ビルドが失敗している
• フィーチャーフラグの漏えいにより、未リリースの機能が公開されている
• 事前告知のない開発者体験のリグレッション（環境、ポート、またはビルドの契約が壊れている）
• トランザクションを使わない、複数段階の非アトミックな DB 更新

変更をリクエスト

• 環境変数の追加やセットアップスクリプトの要件に関するドキュメントが不足している
• diff から明らかなパフォーマンス上の懸念がある（N+1、インデックスの不足）
• パターン違反がある（UI ライブラリをすでにインポートしているファイルで、生の HTML を使用している）
• クリーンアップ用の issue／TODO を設けずにフィーチャーフラグを導入している
• 振る舞いではなく、実行されたことだけを検証する中身のないテスト

承認

• すべてのセキュリティチェックに合格している
• テストに合格し、実際の振る舞いを検証している
• コードベースのパターンに従っている
• 開発者体験への影響が記載されている
• フィーチャーフラグにクリーンアップ計画がある
• 仕様の評価軸に合格している、または仕様が存在しないためスキップされている

契約

入力：

• レビュー対象となる単一の diff、ブランチ、または PR。スコープの把握には読み取り専用の git／gh コマンドを使用します。

出力：

• 「マージをブロック」「変更をリクエスト」「承認」に分類した指摘事項の一覧。それぞれにファイル、行、1 文の理由を含めます。
• チェックリストと併せて仕様レポートを作成します。元となる issue に照らし、要件の不足、スコープクリープ、誤った実装を記載します。一方の評価軸で他方を覆い隠さないよう、2 つの軸は分けてください。

作成／変更：

• なし。このスキルは報告を行うものであり、ファイルを編集したり PR を作成したりしません。

外部への副作用：

• 読み取り専用の git および gh の呼び出しのみです。変更もデプロイも行いません。

確認の要否：

• ありません。すべての出力は助言です。

委任先：

• ありません。このゲートの範囲外の指摘については、構造、セキュリティ、またはコードベース設計のレビュー（インストールされている場合は、上流の pstack ワークフローなど）を推奨します。