backend-code-review

バックエンドコードのレビュー

このスキルを使用するタイミング

ユーザーが src/backend/ ディレクトリ内のバックエンドコード（例：.py）のレビュー、分析、または改善を依頼した場合は、いつでもこのスキルを使用してください。次のレビュー方法に対応しています。

• 変更保留中のレビュー：ユーザーが現在の変更のレビューを依頼した場合（変更内容を確認するため、コミット予定のステージ済みファイルまたは作業ツリー内のファイルを調べます）。
• コードスニペットのレビュー：ユーザーがコードスニペット（例：関数、クラス、モジュールの抜粋）をチャットに貼り付けてレビューを依頼した場合。
• ファイルに焦点を当てたレビュー：ユーザーが特定のファイルを指定して、そのファイル（1つ、または少数の明示されたファイル。例：src/backend/base/langflow/api/v1/flows.py）のレビューを依頼した場合。

次の場合は、このスキルを使用しないでください。

• フロントエンドコードまたはUIに関する依頼の場合（例：.tsx、.ts、.js、src/frontend/）。
• ユーザーがバックエンドコードのレビュー、分析、または改善を依頼していない場合。
• 対象範囲が src/backend/ の配下ではない場合（ユーザーが src/backend/ の外にあるバックエンド関連の変更のレビューを明示的に依頼した場合を除く）。

このスキルの使用方法

このスキルを使用する際は、次の手順に従ってください。

1. ユーザーの入力に基づいて、レビュー方法（変更保留中、スニペット、ファイルに焦点を当てたもの）を特定します。対象範囲を限定し、ユーザーが提供した、または明示的に参照した内容のみをレビューしてください。
2. レビューを実施する際は、チェックリストに定められたルールに従ってください。該当するチェックリストのルールがない場合は、代わりに一般的なレビュー規則を適用し、可能な限り最善を尽くしてレビューしてください。
3. 最終出力は、必ず必須の出力形式に従って作成してください。

このスキルを使用する際の注意事項：

• 実行可能な修正案や提案（コードスニペットを含む）を必ず提示してください。
• ファイルパスと行番号が確認できる場合は、可能な限り File:Line 形式で参照してください。確認できない場合は、特定できる最も具体的な識別子を使用してください。

チェックリスト

• db スキーマ設計：レビュー対象に src/backend/base/langflow/services/database/models/ 配下のコード／ファイル、または src/backend/base/langflow/alembic/versions/ 配下の Alembic マイグレーションが含まれる場合は、references/db-schema-rule.md に従ってレビューしてください
• アーキテクチャ：レビュー対象にルート／サービス／モデルのレイヤー構成、依存関係の方向、またはモジュール間での責務の移動が関係する場合は、references/architecture-rule.md に従ってレビューしてください
• サービスの抽象化：レビュー対象にテーブル／モデルの操作（例：select(...)、session.execute(...)、結合、CRUD）が含まれ、それが src/backend/base/langflow/services/ 配下のサービス内ではない場合は、references/repositories-rule.md に従ってレビューしてください
• sqlalchemy のパターン：レビュー対象に SQLAlchemy／SQLModel のセッション／クエリの使用、DB トランザクション／CRUD の使用、session_scope() の使用、または生 SQL の使用が関係する場合は、references/sqlalchemy-rule.md に従ってレビューしてください

一般的なレビュー規則

1. セキュリティレビュー

以下を確認します。

• SQL インジェクションの脆弱性（特に、文字列補間を使った生の text() クエリ）。結果：攻撃者がデータベース内のあらゆるデータを読み取り、変更、削除できる可能性があります。
• コンポーネントの HTTP 呼び出しにおけるサーバーサイドリクエストフォージェリ（SSRF）。結果：攻撃者がサーバーを使って内部ネットワークをスキャンしたり、クラウドのメタデータエンドポイントにアクセスしたりする可能性があります。
• コマンドインジェクション（特に、サブプロセスやシェルを実行するコンポーネント）。結果：攻撃者がサーバーのシェルアクセス権を得る可能性があります。
• 安全でないデシリアライゼーション（pickle、SafeLoader を使わない yaml.load）。結果：サーバー上で任意のコードが実行される可能性があります。
• ハードコードされたシークレット／認証情報。結果：シークレットが Git の履歴から漏えいし、完全に無効化できなくなります。
• 不適切な認証／認可（CurrentActiveUser 依存関係の欠落）。結果：認証されていないユーザーが保護されたエンドポイントにアクセスできる可能性があります。
• 安全でない直接オブジェクト参照（クエリに user_id によるスコープ指定がない）。結果：ユーザー A がユーザー B のフロー、変数、API キーを読み取り、変更できる可能性があります。
• ファイルストレージ操作におけるパストラバーサル。結果：攻撃者がサーバー上の任意のファイル（例：/etc/passwd、.env）を読み取る可能性があります。

2. パフォーマンスレビュー

以下を確認します。

• N+1 クエリ（特にループ内で session.execute() を呼び出す場合）。結果：フローが 100 件ある場合、DB クエリが 2 回ではなく 101 回になり、ページの読み込みが 50ms から 5s に遅くなります。
• 頻繁にクエリされる列にデータベースインデックスがない。結果：大規模なデータセットでテーブル全体のスキャンが発生し、クエリの性能が O(log n) から O(n) に低下します。
• メモリーリーク（上限のないキャッシュ、長時間稼働するサービスに保持された参照）。結果：数時間稼働した後にサーバーのメモリーが枯渇し、本番環境でポッドが再起動します。
• 非同期コード内のブロッキング処理（time.sleep()、同期 I/O、run_in_executor を使わない CPU バウンド処理）。結果：イベントループ全体が停止し、ブロッキング呼び出しが完了するまで同時に処理中のすべてのリクエストがハングします。
• 高コストな計算でキャッシュを利用できていない。結果：同じ結果の計算がリクエストごとに繰り返されます。
• ページネーションせずに大きな結果セットをすべてメモリーに読み込んでいる。結果：ユーザーのフローが 10K 件を超える場合に、メモリー使用量が急増し、応答が遅くなります。

3. コード品質レビュー

以下を確認します。

• Python 3.10～3.13 との前方互換性
• コードの重複（DRY 違反 — まったく同じビジネスルールが 3 箇所以上で重複している場合に抽出します）
• 多くの処理を行う関数（SRP 違反 — 関数の説明に「そして」が必要なら、分割します）
• 深いネスト／複雑な条件分岐（早期リターンとガード節を優先します）
• マジックナンバー／文字列（名前付き定数または列挙型に抽出します）
• 不適切な命名：意味が不明確な略語、誤解を招く名前、汎用的な名前（data、result、obj、temp）。関数名には動詞（get、create、validate）を使います。ブール値には接頭辞（is_、has_、can_、should_）を使います。
• エラーハンドリングの欠落（裸の except、例外の握りつぶし、通知されない失敗）
• 型カバレッジの不足（強い型付けを使用し、具体的な型がわかっている場合は Any を避けます）
• Python 3.10 以降のユニオン構文を使います（Union[X, Y] ではなく X | Y、Optional[X] ではなく X | None）
• 型注釈にのみ必要なインポートには TYPE_CHECKING ガードを使います（循環インポートを防ぎます）
• FastAPI DI には、プロジェクトのエイリアス（CurrentActiveUser、DbSession、DbSessionReadOnly）と Annotated[Type, Depends(...)] を使います
• Google スタイルの docstring（Ruff で強制）：公開関数には Args:、Returns:、Raises: セクションを記述します
• SOLID 原則への違反
• YAGNI 違反（現時点で要件がないのに、将来のニーズを想定したコード）
• 1 行が 120 文字を超えていないか（プロジェクトの Ruff 設定）
• 「何をするか」を説明するコメント（コメントではコードを言い換えるのではなく、理由だけを説明します）
• コメントアウトされたコード（代わりにバージョン管理を使います）
• 関数の動作を切り替えるブール値のパラメーター（代わりに、名前付き関数を 2 つに分けます）
• 不変の代替手段があるのに、共有された可変状態を使っていないか（変更するより、新しいオブジェクトを返す方法を優先します）

4. ファイル構成のレビュー

以下を確認します。

• コード行数が約500行を超える本番ファイル（インポート、型、docstringを除く）。600行を超えるファイルは危険信号であり、責務ごとに分割する必要があります。理由：500行を超えるファイルは、統計的に欠陥率が高く、レビューにも時間がかかります。これは、複数の責務を担っていること（SRP違反）を示しています。Langflowでは、DatabaseServiceのようなサービスがこの制限を超えて大きくなった場合、CRUD操作を専用モジュールに切り出す必要があります。
• 1000行を超えるテストファイル。超える場合は、論理的なグループごとに分割します。
• 1つのファイルに、異なる責務を持つ関数が5つを超えていないこと（AGENTS-example.mdに従います）。
• 各ファイルに、存在する理由と変更する理由がそれぞれ1つだけあること（SRP）。
• 汎用的なファイル名を使わないこと：単独のファイルとしてのutils.py、helpers.py、misc.py、common.py。理由：utils.pyという名前のファイルは、無関係な関数の寄せ集めになりがちです。数か月で、書式設定、検証、解析、HTTP呼び出しを扱う50個以上の関数が集まり、SRPに違反します。関数のグループごとに、その責務にちなんだ名前のファイル（formatting.py、validation.pyなど）に配置します。

5. テストのレビュー

以下を確認します。

• 新しいコードパスのテストカバレッジ不足
• 動作ではなく実装の詳細をテストしているテスト
• 不安定なテストパターン（時間依存、実行順序依存、外部サービス依存）
• 非同期テストでのpytest.mark.asyncioの適切な使用
• 過剰なモック（プロジェクトの規約に従い、実際の統合を優先します）
• カバレッジ目標：80％（許容される最低ライン：75％）
• テストのアンチパターン：嘘つき（成功するが、主張された動作を検証しない）、鏡（コードの動作をそのままアサートする）、巨人（セットアップが50行以上）、モックまみれ（モックのセットアップだけをテストする）、実装の監視者（実装に密結合している）、順番待ち（実行順序に依存する）、不安定（結果に一貫性がない）

正常系のテストは土台ですが、それだけでは不十分です。 実際の欠陥を見つけるため、テストではコードに対して次のような検証も行う必要があります。

• 予期しない入力：None、""、[]、{}、0、-1、UUID("00000000-0000-0000-0000-000000000000")
• 境界値：最大長の文字列、上限とちょうど同じ値、上限を1つ超える値、項目数がゼロの場合、最大項目数
• 不正なデータ：必須フィールドの欠落、予期しない追加フィールド、型の誤り、無効な形式
• エラー状態：データベースが停止した場合はどうなるか。外部APIが500を返した場合はどうなるか。ユーザーが存在しない場合はどうなるか。
• 起きてはならないこと：ユーザーAがユーザーBのフローにアクセスできないことを検証します。削除済みのフローが404を返すことを検証します。無効なendpoint_nameが422で拒否されることを検証します。
• エラーメッセージと型：単に失敗することだけでなく、正しい例外と正しいメッセージで失敗することを検証します。
• 同時実行：2つのリクエストが同時に同じフローを更新しようとした場合にどうなるかを検証します。

現在のソースコードの動作ではなく、要件や仕様に基づいてテストを作成してください。 これにより、コードが期待される動作と乖離している場合にバグを見つけられます。

テストが失敗した場合： まず、テストではなくコードに誤りがないかを確認してください。理由を理解せずに、現在のコードに合わせて失敗したアサーションを黙って変更してはいけません。

6. 可観測性のレビュー

以下を確認します。

• lfx.log.loggerの非同期ロガーを、aを先頭に付けたメソッド（adebug、ainfo、awarning、aerror、aexception）で使用します。print()や標準ライブラリのloggingは使用しないでください。
• タイトなループ内ではなく、重要な判断箇所や境界でログを記録します。
• ログに含める情報：操作名、関連ID、結果（成功／失敗）、必要に応じて所要時間
• ログレベルを適切に使用します：ERROR（破損しており、対応が必要）、WARN（機能は低下しているが、復旧可能）、INFO（重要なイベント）、DEBUG（診断用。本番環境では無効）
• PIIは一切許容しません：メールアドレス、ユーザー名、電話番号、トークン、パスワードは決してログに記録しないでください。承認された識別子（user_id、flow_id、session_id）のみ使用します。
• print()文は使用しません。これらは本番ログに出力されます。
• ログメッセージで例外を文字列として表現する場合は、{e!s}を使用します。

7. コミット前の検証

変更のレビューでは、作成者が次のコマンドを実行していることを確認してください。

• make format_backend（Ruff によるフォーマット）— フォーマットの不統一は差分を見づらくし、コードレビューで本当の変更を見落とす原因になります。まずフォーマットし、その後にレビューしてください。
• make lint（MyPy による型チェック）— lint 時に見つかる型エラーは、本番環境で実行時クラッシュが発生してから修正する場合に比べて、修正コストが 10 分の 1 です。Langflow のサービスでは、Service 基底クラスを介したダックタイピングを使用しています。MyPy は不一致を早期に検出します。
• make unit_tests（pytest）— テストが失敗する場合、その変更によって既存の動作が壊れています。テストが失敗したままマージしてはいけません。コードとテストのどちらに問題があるのかを調査してください。

必須の出力形式

このスキルが呼び出されたとき、応答は次のいずれかのテンプレートに厳密に従う必要があります。

テンプレート A（指摘事項がある場合）

# Code Review Summary

Found <X> critical issues need to be fixed:

## 🔴 Critical (Must Fix)

### 1. <brief description of the issue>

FilePath: <path> line <line>
<relevant code snippet or pointer>

#### Explanation

<detailed explanation and references of the issue>

#### Suggested Fix

1. <brief description of suggested fix>
2. <code example> (optional, omit if not applicable)

---
... (repeat for each critical issue) ...

Found <Y> suggestions for improvement:

## 🟡 Suggestions (Should Consider)

### 1. <brief description of the suggestion>

FilePath: <path> line <line>
<relevant code snippet or pointer>

#### Explanation

<detailed explanation and references of the suggestion>

#### Suggested Fix

1. <brief description of suggested fix>
2. <code example> (optional, omit if not applicable)

---
... (repeat for each suggestion) ...

Found <Z> optional nits:

## 🟢 Nits (Optional)
### 1. <brief description of the nit>

FilePath: <path> line <line>
<relevant code snippet or pointer>

#### Explanation

<explanation and references of the optional nit>

#### Suggested Fix

- <minor suggestions>

---
... (repeat for each nits) ...

## ✅ What's Good

- <Positive feedback on good patterns>

• 重大な問題、提案、任意の軽微な指摘、良い点がない場合は、そのセクションを省略してください。
• 問題の数が 10 を超える場合は、「重大な問題／提案／任意の軽微な指摘が 10 件以上見つかりました」と要約し、最初の 10 件のみを出力してください。
• セクション間の空行を詰めないでください。読みやすさのため、そのまま維持してください。
• コードの変更が必要な問題がある場合は、構造化された出力の後に、修正を適用するかどうかを尋ねる簡潔な質問を追加してください。例：「提案した修正を適用して、これらの問題に対処しますか？」

テンプレート B（指摘事項がない場合）

## Code Review Summary
✅ No issues found.