本ファイルは cloudflare/skills（Apache-2.0）を基に改変しています。詳細は リポジトリルートの ATTRIBUTION.md を参照。

Cloudflare Workers ベストプラクティス

Cloudflare WorkersのAPI、型、設定は更新される可能性がある。Workersコードの作成・レビューでは、事前学習の記憶ではなく最新資料の取得を優先する。

最新情報の取得先

Workersコードを書く・レビューする前に最新版を取得する。API signature、設定field、binding形状を、このSkillに埋め込まれた知識だけで決めない。正本は cloudflare Skill の「最新情報の取得先」(docs MCP 第一手段、不通時の復旧、workers-types / config-schema の取得方法)。ここには本Skill固有の取得先だけを書く。

取得先	取得方法	使う場面
Cloudflare docs (MCP)	cloudflare-docs MCPで workers best practices / API名を検索	既定の第一手段。rules、API reference、compatibility dates/flags
Workers best practices (Web)	https://developers.cloudflare.com/workers/best-practices/workers-best-practices/	MCP不通時。正式なrules、patterns、anti-patterns
Workers types の検証手順	references/review.md	取得した型でbinding access・handler signatureを照合する手順

最初に最新referenceを取得する

レビューや実装の前に、現在のbest practicesページと必要な型定義を取得する。プロジェクトのnode_modulesが古い場合は、公開済みの最新版を優先する。

# Fetch latest workers types
mkdir -p /tmp/workers-types-latest && \
  pnpm pack @cloudflare/workers-types --pack-destination /tmp/workers-types-latest && \
  tar -xzf /tmp/workers-types-latest/cloudflare-workers-types-*.tgz -C /tmp/workers-types-latest
# Types at /tmp/workers-types-latest/package/index.d.ts

補足reference

• references/rules.md — code examplesとanti-patternsを含む全best practice rules
• references/review.md — 型・設定・binding access patternの検証とreview process

Rules早見表

設定

Rule	要点
Compatibility date	新規projectはcompatibility_dateを当日に設定し、既存projectは定期更新する
nodejs_compat	多くのlibraryがNode.js built-insへ依存するためnodejs_compat flagを有効化する
wrangler types	wrangler typesでEnvを生成し、binding interfaceを手書きしない
Secrets	wrangler secret putを使い、configやsourceへsecretをhardcodeしない
wrangler.jsonc	非secret設定にはJSONC configを使う。新しい機能にはJSONのみ対応するものがある

RequestとResponse

Rule	要点
Streaming	大きさが不明または大容量のpayloadはstreamし、無制限のdataへawait response.text()しない
waitUntil	response後の処理にはctx.waitUntil()を使い、ctxをdestructureしない

Architecture

Rule	要点
Bindings over REST	KV、R2、D1、QueuesはCloudflare REST APIでなくin-process bindingを使う
Queues & Workflows	async/background処理をcritical pathから分離する
Service bindings	Worker間呼び出しはpublic HTTPでなくservice bindingを使う
Hyperdrive	外部PostgreSQL/MySQL接続には常にHyperdriveを使う

Observability

Rule	要点
Logs & Traces	configでobservabilityとhead_sampling_rateを有効化し、structured JSON loggingを使う

Code patterns

Rule	要点
No global request state	request固有dataをmodule-level変数へ保存しない
Floating promises	全Promiseをawait、return、void、またはctx.waitUntil()のいずれかで扱う

Security

Rule	要点
Web Crypto	security用途にはcrypto.randomUUID() / crypto.getRandomValues()を使い、Math.random()を使わない
No passThroughOnException	明示的なtry/catchとstructured error responseを使う

検出するanti-patterns

Anti-pattern	問題になる理由
無制限のdataにawait response.text()	128 MB制限に達するmemory exhaustion
source/configにsecretをhardcode	version control経由のcredential漏えい
token/ID生成にMath.random()	予測可能で暗号学的に安全でない
awaitもwaitUntilもない裸のfetch()	floating promiseにより結果やerrorが失われる
request stateをmodule-level mutable変数へ保存	request間data漏えい、stale state、I/O error
Worker内からCloudflare REST APIを呼ぶ	不要なnetwork hop、認証負荷、latency増加
error handlingにctx.passThroughOnException()	bugを隠し、debug不能にする
Env interfaceの手書き	実際のwrangler config bindingとdriftする
secret値の直接文字列比較	timing side-channel。crypto.subtle.timingSafeEqualを使う
ctxのdestructure（const { waitUntil } = ctx）	this bindingが失われ、runtimeでIllegal invocation
any on Env or handler params	binding access全体のtype safetyを失う
as unknown as Tのdouble-cast	実際の型不整合を隠す。designを修正する
platform base classへのimplements	legacy。this.ctx、this.envを失うためextendsを使う
platform base class内のenv.X	DurableObject、WorkerEntrypoint等をextendsするclassではthis.env.Xを使う

レビュー手順

1. Retrieve — 最新best practices、workers types、wrangler schemaを取得する
2. Read full files — diffだけでなくfile全体を読み、binding accessの文脈を確認する
3. Check types — binding access、handler signatures、any、unsafe castsを確認する（references/review.md参照）
4. Check config — compatibility_date、nodejs_compat、observability、secrets、bindingとcodeの一致を確認する
5. Check patterns — streaming、floating promises、global state、serialization boundariesを確認する
6. Check security — crypto、secret handling、timing-safe comparison、error handlingを確認する
7. Validate with tools — pnpm tsc --noEmitとno-floating-promises lintを実行する
8. Reference rules — 各ruleの正しいpatternをreferences/rules.mdで確認する

対象範囲

このSkillはWorkers固有のbest practicesとcode reviewを扱う。関連領域は次を使う。

• Durable Objects: durable-objects Skillをloadする
• Workflows: Rules of Workflowsを参照する
• Wrangler CLI commands: wrangler Skillをloadする

最終出力

レビュー結果は、重要度順に「対象file/line、観測した事実、該当rule、影響、最小の修正案、実行した検証」を日本語で報告する。問題がなければ、確認した範囲と未検証事項を明示する。

原則

• 断定前に取得する。 API、config field、patternに確信がなければ、指摘前に公式資料を取得する。
• 根拠を示す。 line number、tool output、docs linkを添える。
• 開発者がコピーする箇所を優先する。 examplesやdocsのWorkers codeは本番へコピーされる。
• 網羅性より正確性。 動く短いexampleは、errorを含む包括的なexampleよりよい。