mcpField
W
workers-best-practices

workers-best-practices

github.com/tejas-kaleクラウド・DevOps038 回インストール3 日前に更新
リポジトリ

workers-best-practices について

workers-best-practicesは、Cloudflare Workersのコードを書く人やレビューする人向けのスキルです。最新のドキュメント、型、設定スキーマを取得してからルールを適用し、根拠のある指摘を報告します。

主な機能

  1. 01最新のWorkersドキュメントと型の取得
  2. 02作成・レビュー規則の適用
  3. 03TypeScriptとPromise lintの確認
  4. 04根拠と重要度を添えた指摘

活用シーン

  1. 01最新のWorkers APIに沿ったコード作成
  2. 02Workerファイルのアンチパターン確認
  3. 03型、バインディング、設定の検証

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/tejas-kale/skills --skill workers-best-practices

インストール後、Claude Code で/workers-best-practicesを入力して読み込まれたか確認します。

同梱ファイルreferences/review.mdreferences/rules.md

詳細

Workers のベストプラクティス

Workers API、設定フィールド、バインディングの形状に関する組み込み知識は古くなっています。まず取得してください。断言する API シグネチャ、設定フィールド、バインディングの形状はすべて、このセッションで取得したソースに基づく必要があります。ソースを引用できない情報は報告しないでください。

1. 取得する

1 行も書いたりレビューしたりする前に取得してください。node_modules で固定されているバージョンより、最新の公開バージョンを優先してください。

# Latest workers types → /tmp/workers-types-latest/package/index.d.ts
mkdir -p /tmp/workers-types-latest && \
  npm 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
ソース場所用途
ベストプラクティスのページhttps://developers.cloudflare.com/workers/best-practices/workers-best-practices/標準的なルールとアンチパターン
Workers の型定義上記の npm packAPI シグネチャ、ハンドラーの型、バインディングの型
Wrangler の設定スキーマnode_modules/wrangler/config-schema.json設定フィールド、バインディングの形状、許可される値
Cloudflare のドキュメント検索、または https://developers.cloudflare.com/workers/API リファレンス、互換性の日付とフラグ

型定義、設定スキーマ、ベストプラクティスのページがすべてコンテキストに揃ったら完了です。

2. ルールを適用する

references/rules.md は、設定、リクエスト処理、アーキテクチャ、可観測性、コードパターン、セキュリティ、テストなど、すべてのルールの唯一の信頼できる情報源です。それぞれに正しいパターンと、それに置き換わるアンチパターンが記載されています。これを読んでから、ルール一式に取り組んでください。

  • 作成 — 該当するセクションのすべてのルールが、作成するコードで満たされていることを確認します。
  • レビュー — バインディングへのアクセスやグローバル状態は文脈の中でのみ正しく読み取れるため、差分だけでなくファイル全体を読んでから、各ルールを照らし合わせます。

references/rules.md のすべてのルールを適用するか、該当しないと判断したら完了です。明らかなルールだけに合格した時点では完了ではありません。

3. 検証して報告する

npx tsc --noEmit を実行し、no-floating-promises の lint も実行してください。ツールで確認できるルールは目視ではなく、ツールで確認します。

レビューでは、references/review.md にレビュー固有の参照情報が記載されています。型と設定の検証、シリアライズの境界、説明用コードと実行可能コードの評価方法、リスクレベル、指摘事項の形式が含まれています。指摘事項をまとめる前に読んでください。

すべての指摘事項にファイル名と行番号、根拠の引用、重要度が記載されたら完了です。

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

繰り返し見られるものを一覧にしています。それぞれの詳細は references/rules.md を参照してください。

アンチパターン重要な理由
上限のないデータに対する await response.text()メモリ枯渇 — 上限は 128 MB
ソースコードや設定にシークレットをハードコードするバージョン管理を通じた認証情報の漏洩
トークンや ID に Math.random() を使う予測可能で、暗号学的に安全ではない
await や waitUntil を使わない fetch()浮遊プロミス — 結果が破棄され、エラーが握りつぶされる
リクエスト状態にモジュールレベルの可変変数を使うリクエスト間でのデータ漏洩、古い状態、I/O エラー
Worker 内から Cloudflare REST API を呼び出すネットワークホップ、認証処理、レイテンシーの増加
エラー処理に ctx.passThroughOnException() を使うバグが隠れ、デバッグが不可能になる
Env インターフェースを手書きする実際の wrangler 設定バインディングとのずれが生じる
シークレットを文字列で直接比較するタイミングサイドチャネル — crypto.subtle.timingSafeEqual を使用する
ctx を分割代入する（const { waitUntil } = ctx）this のバインディングが失われ、実行時に「Illegal invocation」が発生する
Env やハンドラーパラメーターに any を使うすべてのバインディングアクセスで型安全性が失われる
as unknown as T で二重キャストする実際の型の不整合が隠れる — 設計を修正する
プラットフォームの基底クラスに implements を使うレガシーな方法 — this.ctx と this.env が使えなくなる。DurableObject、WorkerEntrypoint、Workflow では extends を使う
プラットフォームの基底クラス内で env.X を使うthis.env.X を使う必要がある

対象範囲

Workers 自体が対象です。プラットフォーム全体（Durable Objects、Workflows、Wrangler コマンド、KV/D1/R2）については、cloudflare アンブレラ スキルを読み込んでください。そこにある references/ には、製品ごとのファイルが用意されています。

コメント

Markdown 対応