workers-code-review

Cloudflare Workers の API、型、wrangler の設定に関する知識は古くなっている可能性があります。Workers のコードレビューでは、事前学習よりも情報の取得を優先してください。

参照先

ローカルにあるリポジトリのコピーを使用してください。型を取得するために npm pack を実行したり、パッケージをインストールしたりしないでください。

参照元	場所	用途
Wrangler の設定スキーマ	node_modules/wrangler/config-schema.json	設定フィールド、バインディングの形式、許可される値
Workers の型	node_modules/@cloudflare/workers-types/index.d.ts	API の使用方法、ハンドラーのシグネチャ、バインディングの型
Cloudflare のドキュメント検索	cloudflare-docs 検索ツールを使用するか、このリポジトリ内のファイルを読む	API リファレンス、互換性の日付／フラグ、バインディングのドキュメント

型、設定フィールド、API シグネチャを確認する必要がある場合は、これらのファイルを直接読んでください。このフォルダー内のガイドには検証する内容が記載されています。パッケージの取得方法は記載されていません。

レビュープロセス

1. コンテキストを把握する

差分や断片だけでなく、ファイル全体を読んでください。周辺のロジックを踏まえると、単独では誤っているように見えるコードが正しい場合があります。

• コードの目的を特定します。完全な Worker なのか、スニペットなのか、設定例なのかを確認してください。
• git の履歴を確認します：git log --oneline -5 -- <file>
• コードが依存するバインディング、型、パターンを把握します。

2. コードを分類する

すべてのコードブロックは、次の 3 つのカテゴリのいずれかに該当します。それぞれのカテゴリのコンテキストに沿ってレビューしてください。

カテゴリ	定義	期待される内容
説明用	概念を示すもので、ロジックの大半にコメントを使用しています	正しい API 名、現実的なシグネチャ
実演用	機能するものの未完成で、適切なコンテキストに配置すれば動作します	構文が有効で、API とバインディングへのアクセスが正しいこと
実行可能	単独で完結しており、変更なしで実行できます	コンパイルでき、実行でき、インポートと設定が含まれていること

3. ツールで検証する

型チェックとリンティングを実行してください。ツールの出力は意見ではなく、根拠です。

npx tsc --noEmit                    # TypeScript errors
npx eslint <files>                  # Lint issues

設定ファイルについては、最新の wrangler 設定スキーマ（取得方法は wrangler-config.md を参照）に照らして検証し、すべてのフィールド、バインディングの型、値が適合していることを確認してください。

4. ルールとの照合

型システムのルールについては workers-types.md、設定の検証については wrangler-config.md、正しい API パターンについては common-patterns.md を参照してください。

クイックリファレンス：

ルール	詳細
バインディングへのアクセス	モジュールのエクスポートハンドラーでは env.X を使用し、プラットフォームのベースクラスを継承するクラスでは this.env.X を使用します。common-patterns.md を参照してください。
any を使わない	バインディングの型、ハンドラーパラメーター、API レスポンスに any を使用してはいけません。適切なジェネリクスを使用してください。
型システムの不正な回避	as unknown as T、正当な理由のない @ts-ignore、安全でない型アサーションを指摘してください。workers-types.md を参照してください。
設定とコードの整合性	wrangler 設定内のバインディング名は、コード内の env.X の使用箇所と一致している必要があります。wrangler-config.md を参照してください。
必須の設定フィールド	wrangler 設定スキーマと照合してください。どのフィールドが必須かを推測してはいけません。
簡潔な例	例では中核となるロジックに焦点を当ててください。コードの説明を妨げるボイラープレートは最小限に抑えてください。
未処理の Promise	すべての Promise は await するか、return するか、void で処理するか、ctx.waitUntil() に渡す必要があります。common-patterns.md を参照してください。
シリアル化	Queue、Workflow のステップ、DO ストレージの境界を越えるデータは、構造化クローンでシリアル化できる必要があります。common-patterns.md を参照してください。
ストリーミング	大きなペイロードやサイズが不明なペイロードはバッファリングせず、ストリーミングしてください。サイズに上限のないデータに対する await response.text() を指摘してください。
エラー処理	最小限でよいので必ず実装してください。null を返す可能性がある戻り値の null チェックと、基本的な fetch のエラー処理を行ってください。冗長な try/catch で本題を妨げないでください。

5. リスクの評価

リスク	該当する要素
HIGH	認証、暗号処理、外部呼び出し、値の移転、検証の削除、アクセス制御、バインディングの設定ミス
MEDIUM	ビジネスロジック、状態の変更、新しい公開 API、エラー処理、設定の変更
LOW	コメント、ログ出力、フォーマット、軽微なスタイル変更

HIGH リスクの分析を優先して深く行ってください。重要な処理経路については、影響範囲を確認してください。このコードを参照している他のファイルはいくつありますか？

セキュリティロジックのエスカレーション：暗号処理、認証、タイミングに依存するコードでは、API 呼び出しが正しいことの確認だけで終わらないでください。セキュリティ特性を損なう周辺ロジックの欠陥も調べてください（例：timingSafeEqual の呼び出しは正しくても、長さが一致しない場合に早期リターンする）。common-patterns.md の「Security」セクションを参照してください。

指摘すべきアンチパターン

アンチパターン	重要な理由
Env またはハンドラーパラメーターに any を使う	後続のすべてのバインディングアクセスで型安全性が損なわれます
as unknown as T による二重キャスト	実際の型の不整合が隠されます。根本的な設計を修正してください
説明のない @ts-ignore / @ts-expect-error	エラーがひそかに隠されます。抑制する場合は、それぞれに理由をコメントで記載してください
有限でないデータをバッファリングする（ストリームに対する await res.text()、await res.json()）	大きなペイロードでメモリが枯渇します。ストリーミングを使用してください
ハードコードされたシークレットや API キー	env バインディングと wrangler secret を使用してください
すべてのリクエストで blockConcurrencyWhile を使う	初期化時にのみ使用してください。すべての同時リクエストがブロックされます
単一のグローバル Durable Object	ボトルネックが生じます。調整単位ごとにシャーディングしてください
DO 内のメモリー上だけの状態	エビクション時に失われます。SQLite ストレージに永続化してください
設定に DO マイグレーションがない	新しい DO クラスにはマイグレーションエントリーが必要です。ない場合、デプロイが失敗します
浮遊するプロミス（await を付けない step.do()、fetch()）	ひそかなバグの原因になります。結果が破棄され、Workflow の耐久性が損なわれ、エラーが無視されます
境界を越えるシリアライズ不可能な値（step／queue 内の Response、Error）	コンパイルは成功しても、実行時に失敗します。境界を越える前にプレーンデータを取り出してください
プラットフォームの基底クラスを extends せず implements する	古いパターンです。基底クラスからの this.ctx、this.env へのアクセスが失われます

指摘しないもの

• リンターで強制されていないスタイル
• コードが正しく明確である場合の「もっときれいにできる」
• 根拠のない理論上のパフォーマンス上の懸念
• 例のスコープ外の未実装機能
• 変更されていないコードに以前から存在する問題

出力形式

**[SEVERITY]** Brief description
`file.ts:42` — explanation with evidence (tool output, type error, config mismatch)
Suggested fix: `code` (if applicable)

重要度：CRITICAL（セキュリティ、データ損失、クラッシュ） | HIGH（型エラー、誤った API、設定の破損） | MEDIUM（検証不足、エッジケース、古いパターン） | LOW（スタイル、軽微な改善）

最後に重要度別の件数をまとめてください。問題が見つからなかった場合は、その旨を明記してください。

原則

• 確実性を重視してください。 指摘する前に調査してください。API、バインディングパターン、設定フィールドを確認できない場合は、まずドキュメントまたはスキーマを取得してください。
• 根拠を示してください。 行番号、ツールの出力、スキーマフィールド、型定義を参照してください。
• 網羅性より正確性を重視してください。 エラーのない包括的な例よりも、動作する簡潔な例のほうが優れています。
• 既存のパターンを尊重してください。 コードベースですでに確立されている規約は、明らかに有害でない限り指摘しないでください。
• 開発者がコピーするものに注目してください。 ドキュメント内のコードは本番環境に貼り付けられます。その前提で扱ってください。