I built a Cloudflare Playbook. It’s for any indie developer who wants to ship products with AI coding. It covers:

• How to choose common Cloudflare services
• How to use Workers / Pages / D1 / R2 / KV / AI Gateway
• Whether the free tier is enough
• When to upgrade to $5 Workers Paid
• Biggest footguns when AI writes CF code
• How to configure Codex / Claude Code with Cloudflare Skill & MCP
• Which open source projects you can reference directly

My goal is simple: write code with AI, deploy globally with Cloudflare.

GitHub: https://github.com/realchendahuang/cloudflare-playbook
Read online: https://cloudflare-playbook.chendahuang.top

realchendahuang/cloudflare-playbook

Source: https://github.com/realchendahuang/cloudflare-playbook

Cloudflare Playbook

A practical guide to Cloudflare in the AI coding era — write code with AI, deploy globally with Cloudflare.

Read online: cloudflare-playbook.chendahuang.top

Overview

mermaid flowchart TD A[Cloudflare Playbook] --> B[Foundation: DNS / SSL / CDN / Rules] A --> C[Compute: Workers / Pages / DO / Workflows / Queues] A --> D[Data: D1 / KV / R2 / Hyperdrive / Vectorize] A --> E[AI: Workers AI / AI Gateway / Agents SDK] A --> F[Media: Images / Stream / Realtime / Browser] A --> G[Security: Turnstile / Access / WAF / Rate Limiting] A --> H[Observability: Log Explorer / Observability / Analytics] A --> I[AI Workflow: Skill / MCP / Wrangler] A --> J[Billing & Quotas: Free vs Paid] A --> K[Architecture Patterns: Common combos & trade-offs]

Table of Contents

• 1. Cloudflare Modules
• 2. AI Coding Workflow
• 3. Billing & Quotas
• 4. Open Source Projects
• 5. Pitfall Guide
• 6. Access in China
• Official Resources

1. Cloudflare Modules

Cloudflare’s capabilities can be grouped into seven categories: Foundation, Compute, Data, AI, Media, Security, and Observability. For each module, we explain when you’ll need it and where the pitfalls are.

Foundation

DNS

Authoritative DNS service that maps domain names to websites, APIs, email, etc.

After buying a domain, you usually change its NS (Name Servers) to Cloudflare so that Cloudflare takes over resolution. Then you configure A, AAAA, CNAME, MX, TXT records here – subdomains, email verification, CNAME flattening, DNSSEC all live here. Get DNS right first, then you can connect Pages, Workers, R2 custom domains.

SSL/TLS

HTTPS encryption between browser and Cloudflare, and between Cloudflare and your origin.

The little lock icon is managed here. After onboarding, edge certificates are usually issued and renewed automatically. If you have your own origin, pay attention to the encryption mode: Full (strict) requires a valid certificate on the origin; Flexible only encrypts browser-to-Cloudflare, which can lead to redirect loops or security warnings. For static sites and Workers projects, you rarely need to touch the certificate chain; only dig in when you have a self‑managed origin.

Cache / CDN

Global edge caching for static assets, pages, and some responses.

Cloudflare caches cacheable content at edge nodes so users retrieve files from a nearby location without hitting the origin every time. Static assets, images, built JS/CSS – these benefit most. Logged‑in user data, real‑time APIs, permission‑based responses should not be cached. For fine‑grained control, use Cache Rules to configure path, header, TTL, and bypass rules.

Rules

A rule system for redirects, caching, headers, origin overrides, and configuration overrides.

If you want to 301 redirect old domains to new ones, add security headers to certain paths, control caching strategies, rewrite URLs, or route different paths to different origins – look at Rules first. They handle edge‑layer request policies. Only reach for a Worker when the logic needs to read/write a database, call an external API, or make business‑state decisions.

Compute

mermaid flowchart TD Q1{"What kind of compute do you need?"} Q1 -->|"Short requests: API / Webhook / BFF"| W["Workers"] Q1 -->|"Frontend + API in one"| WSA["Workers Static Assets"] Q1 -->|"Pure static site / docs / blog"| P["Pages"] Q1 -->|"State coordination / WebSocket"| DO["Durable Objects"] Q1 -->|"Multi‑step flows that may fail/wait"| WF["Workflows"] Q1 -->|"Background async / peak shaving / batch"| QU["Queues"] Q1 -->|"System dependencies / long processes / native binaries"| CT["Containers"] Q1 -->|"Scheduled triggers"| CR["Cron Triggers"]

Workers

Cloudflare’s serverless runtime for running JS/TS, Wasm, and partial Python backend logic.

This is the core compute layer for AI coding. AI‑generated Hono APIs, auth hooks, webhooks, BFF, MCP servers, lightweight AI orchestration – all can go into Workers. It’s great for short requests and high‑concurrency edge logic. Don’t force image processing, large file transcoding, long‑running tasks, or native system dependencies into a regular Worker – use Workflows, Queues, R2, Containers, or external services instead.

Workers Static Assets

Serving static files from a Worker project, deploying frontend files and Worker code as one unit.

When AI generates a Vite, React, Vue, Svelte, static documentation site, or frontend project with an API, this flows naturally: HTML/CSS/JS/images are hosted as static assets, and dynamic logic like /api comes from the Worker. By default, requests for static files do not invoke the Worker; the Worker only runs when a static file isn’t found. Use this over splitting into two services when the frontend and backend are tightly coupled and you want a single Worker configuration to manage routing and APIs.

Pages

A deployment platform for frontend projects, focused on Git integration, preview deployments, and static site publishing.

Connect your GitHub/GitLab, push, and it builds and deploys. Ideal for landing pages, blogs, documentation sites, promo pages, and prototypes. Pages Functions are essentially Workers under the hood. If you need a “frontend + API + multiple bindings” all‑in‑one, Workers Static Assets is now the recommended approach. If you already have a Pages project and rely on preview deployments and Git workflow, sticking with Pages is fine.

Durable Objects

Stateful objects for strong‑consistency coordination, session state, and WebSocket scenarios.

Workers are stateless – each request might land anywhere. Chat rooms, collaborative whiteboards, online game rooms, counters, Agent sessions – these all need a “single authority”. A Durable Object instance can represent a room, user, document, or Agent with its own private persistent storage and WebSocket handling. It’s not a general‑purpose database for all your business tables; it’s more like a “state and coordination center” for a specific entity.

Workflows

Persistent multi‑step tasks for flows that can fail, wait, and retry.

AI‑generated business logic often isn’t a single request: first call an API, then write to the DB, then send an email, then wait for human approval, then publish the result. Workflows break a flow into durable steps, automatically retaining state, supporting sleep, waiting for external events, and retrying on failure. Order processing, data pipelines, user lifecycle emails, AI moderation flows – all good candidates. Ordinary synchronous APIs don’t need it.

Queues

Async message queues for guaranteed delivery, peak shaving, batching, and retries.

Some things shouldn’t make the user wait: sending emails, processing uploads, writing audit logs, batch syncing data, triggering background generation. Put messages into Queues, and a consumer Worker processes them at its own pace – batched, delayed, retried, with dead‑letter queues. Don’t use queues for endpoints that need to return a final result immediately; queues are for “I’ll take it and handle it later” tasks.

Containers

Run containers on Cloudflare for languages, libraries, and long processes that Workers can’t handle.

If an AI‑generated project depends on system libraries, long‑running processes, traditional HTTP services, or native binaries, Workers runtime may not fit – Containers become the natural choice. They complement Workers: Workers can serve as the edge entry and router, while containers handle heavy backend. The trade‑off is higher startup time, resource consumption, and cost compared to regular Workers. Don’t containerize a light API out of the box.

Cron Triggers

Schedule Workers on cron expressions.

Use Cron Triggers for hourly data syncs, daily D1 cleanup, periodic cache refreshes, or scheduled health checks against third‑party APIs. Cron Triggers only fire a Worker at a given time; if the triggered logic involves many steps, human approval, or recovery after failure, push the actual flow into Workflows.

Data

mermaid flowchart TD Q1{"What kind of data?"} Q1 -->|"Structured relational: users/orders/posts"| Q2{"Where is the database?"} Q2 -->|"On Cloudflare"| D1["D1 (SQLite‑compatible)"] Q2 -->|"Existing external PG/MySQL"| HD["Hyperdrive (connection pool + cache)"] Q1 -->|"Key‑value / config / cache"| Q3{"Need to read immediately after write?"} Q3 -->|"No / read‑heavy"| KV["KV (fast global reads)"] Q3 -->|"Strong consistency / high write frequency"| DO["Durable Objects (single‑entity atomic reads/writes)"] Q1 -->|"Files / images / videos"| R2["R2 (S3‑compatible object storage)"] Q1 -->|"Vectors / embeddings"| VZ["Vectorize (similarity search)"] Q1 -->|"Single‑entity state: rooms/sessions/counters"| DO2["Durable Objects Storage"] Q1 -->|"Event streams / log pipelines"| PL["Pipelines"]

D1

Cloudflare’s managed serverless SQL database, with SQLite‑compatible syntax.

When AI generates an application, structured data like users, orders, articles, and configuration can go into D1 first. It integrates naturally with Workers and Pages, and works with Drizzle ORM or raw SQL. Keep in mind: D1 is best for relational data in small to medium‑sized apps and edge applications – it’s not a full Postgres replacement. Index your queries; don’t let a single SELECT scan the whole table. If you need high‑concurrency writes, complex transactions, or Postgres/MySQL‑specific features, use Hyperdrive to connect an external database.

KV

Global key‑value store, ideal for read‑heavy, low‑latency data.

Config, short‑link mappings, feature flags, cached results, small JSON payloads at the edge – all fit KV. The key point is “fast global reads”, not “strong consistency immediately after write”. Don’t put inventory, balances, flash‑sale slots, or real‑time counters in KV; use D1 or Durable Objects for those.

R2

S3‑compatible object storage for files, images, videos, attachments, backups, and datasets.

In AI coding, whenever you handle user uploads, image hosting, exported files, or backups, think R2 first. It’s S3‑compatible, so many existing SDKs and tools can talk to it directly. R2 is for objects, not tables; store file metadata, permissions, and business relationships in D1, and file bodies in R2. For image transformations or video playback, pair with Images, Stream, or a Worker.

Hyperdrive

Edge connection pool and query acceleration layer for external Postgres/MySQL.

If your database is on Supabase, Neon, RDS, or self‑hosted Postgres/MySQL and you don’t want to migrate, but Worker connections are slow or connection limits are a concern – use Hyperdrive. It pools connections at the Cloudflare edge and can cache query results, reducing the cost of cross‑region database access. It’s not a new database; it’s middleware that helps Workers connect to your existing database more efficiently.

Vectorize

Cloudflare’s vector database for storing embeddings and performing similarity searches.

Used for RAG, semantic search, and similarity recommendations: first chunk documents, convert to embeddings, store in Vectorize; then when a user asks a question, find the most similar vectors and feed the relevant text to an LLM. Vectorize stores vectors and metadata, not raw document files – originals can go in R2 or D1. Both Free and Paid tiers have quotas; check the latest pricing for details.

DO Storage

Persistent storage attached to each Durable Object instance.

Every Durable Object can have its own storage for saving its state – room members, collaborative document snapshots, Agent sessions, connection status, counters. Its value is “single‑entity strong consistency + local state”, not replacing D1 for global reporting or storing large files.

Secrets Store

Centralized management of secrets and sensitive configuration.

API keys, webhook secrets, database passwords, third‑party service tokens – don’t put them in code or scatter them across project configs. Secrets Store centralizes these sensitive values for binding to Workers and other services. For normal projects, Worker secrets may suffice; for team collaboration, shared secrets across services, audit trails, and rotation, use Secrets Store.

Pipelines

Data pipelines that continuously write event streams and logs to target storage.

For continuously generated data like app events, behavioral logs, or analytics events that need stable delivery to R2 or elsewhere for post‑analysis, look at Pipelines. It’s data infrastructure, not a regular business database. Small projects may not need it at launch; introduce it when terms like logs, events, and data lake actually surface.

AI

mermaid flowchart TD Q1{"What AI need?"} Q1 -->|"Call LLM / embedding / classification"| WAI["Workers AI"] Q1 -->|"Unified management of multiple model providers"| AIG["AI Gateway"] Q1 -->|"RAG / semantic search"| Q2{"Build yourself or managed?"} Q2 -->|"Self‑built, full control"| VZ["Vectorize + Workers AI"] Q2 -->|"Quick setup, less hassle"| AIS["AI Search"] Q1 -->|"Stateful Agent / multi‑turn conversation"| SDK["Agents SDK"]

Workers AI

Cloudflare’s serverless AI inference platform.

Call Cloudflare‑hosted models from Workers, Pages, or REST API for LLM, embedding, text classification, speech‑to‑text, image understanding, etc. The advantage is simple deployment and auth, with smooth integration to Workers, Vectorize, and AI Gateway. Note that the model list and capabilities change; don’t assume everything from OpenAI/Anthropic is available here. For complex reasoning, advanced multimodal, or strong model needs, you might still need external models.

AI Gateway

Unified gateway for AI APIs – observability, caching, rate limiting, and cost control.

If you’re using multiple providers like OpenAI, Anthropic, Workers AI, Groq, Mistral, don’t scatter API calls in your code; plug them through AI Gateway. It logs requests, tracks latency and errors, provides caching, rate limiting, retries, fallback, and cost management. For AI applications, this layer is invaluable: not the model itself, but the control panel and circuit breaker for model calls.

Vectorize

Vector database, see Data section.

The retrieval layer for AI Q&A systems. Store original texts in R2 or D1, embeddings in Vectorize; on query, retrieve and feed to the model.

AI Search

Cloudflare’s managed AI search capability.

If you want to quickly add semantic search and Q&A to a website, docs, or knowledge base, look at AI Search. It’s easier than stitching Workers AI + Vectorize + a crawler yourself, but offers less flexibility. For full control over chunking, indexing, recall, and answer logic, build your own using Workers AI + Vectorize.

Agents SDK

Framework for building stateful AI Agents, built on Durable Objects.

For multi‑turn conversations, tool calls, Agent memory, real‑time WebSocket, and scheduled tasks, Agents SDK is more comfortable than manual state management. Each Agent can have its own state and storage – suitable for customer support assistants, personal assistants, automation bots, and collaborative AI tools. If you only need a single LLM call, you don’t need the Agents SDK.

Media

mermaid flowchart TD Q1{"Media need?"} Q1 -->|"Image processing / variants / optimization"| IMG["Images"] Q1 -->|"Video playback / transcoding / distribution"| STM["Stream"] Q1 -->|"Real‑time audio/video / conferencing / live"| RT["Realtime"] Q1 -->|"Screenshot / PDF / headless browser"| BR["Browser Rendering"]

Images

Image hosting, optimization, variants, and edge transformation.

If your project has user avatars, product images, cover photos, or content illustrations, Images handles upload, storage, compression, cropping, format conversion, and on‑the‑fly resizing. R2 is more like a general file bucket for raw objects; Images is more like an image delivery pipeline for page‑facing display. For just a handful of static images, static assets or R2 suffice; for large volumes, many sizes, and automatic optimization, use Images.

Stream

Video storage, encoding, playback, and distribution.

Upload a video; Stream handles transcoding, adaptive bitrate, hosted player, and global distribution – perfect for courses, product demos, UGC videos, member‑only content. It solves “stable video playback”, not just storing an mp4 file. If you just want users to download raw video, R2 is more direct. For in‑page playback, transcoding, multiple resolutions, and viewing experience, use Stream.

Realtime

Real‑time audio/video and low‑latency communication.

This group corresponds to the “Realtime” section in the Dashboard, including Realtime Kit, TURN servers, Serverless SFU, MoQ relay, etc. You’ll encounter it when building multi‑party conferencing, voice rooms, live streaming with co‑hosts, or real‑time interaction. For general WebSocket collaboration, start with Workers + Durable Objects; only move to Realtime when you need audio/video pipelines, NAT traversal, SFU relay, and low‑latency media transport.

Browser Rendering

Call a headless browser from Workers for rendering, screenshots, and automation.

Use Browser Rendering when you need to convert a web page to a screenshot, generate a PDF, run page rendering checks, or capture the final DOM of a page you can access. It’s for “needs a real browser environment” tasks, not for simple HTML concatenation, and should not be used to bypass logins, paywalls, or site restrictions. If you can generate the content server‑side with templates, don’t reach for browser rendering.

Security

mermaid flowchart TD Q1{"Security need?"} Q1 -->|"Bot detection / CAPTCHA replacement"| TS["Turnstile"] Q1 -->|"Internal tool authentication"| ACC["Access"] Q1 -->|"SQL injection / XSS prevention"| WAF["WAF"] Q1 -->|"Request frequency limits"| RL["Rate Limiting"] Q1 -->|"Large‑scale attack mitigation"| DDoS["DDoS Protection (on by default)"] Q1 -->|"API schema validation / mTLS"| APS["API Shield"]

Turnstile

Cloudflare’s CAPTCHA alternative for verifying real users.

Login, signup, comments, forms, trial signups – all can use Turnstile. Its approach is to assess risk in the background as much as possible, only prompting the user when necessary. Integration: place the widget on the frontend, validate the token server‑side. If you only put the widget frontend but don’t verify the token backend, it’s useless.

Access

Access control in Zero Trust for internal tools and backends.

If you build an admin panel, internal data dashboard, or temporary ops tool and don’t want to write your own login system, use Access. It performs authentication and policy evaluation before the request reaches the origin or Worker, and can connect to Google, GitHub, SAML, OIDC, etc., as identity providers. For AI‑coded internal tools, this is the easiest “guard at the gate” solution.

WAF

Web Application Firewall that blocks common attacks before they reach your application.

WAF uses managed rules, custom rules, and rate limiting to handle SQL injection, XSS, malicious scanning, abnormal paths, known vulnerability exploitation. AI‑generated code may have basic security issues – WAF provides an edge safety net, but doesn’t replace code fixes: authentication, permission checks, and parameter validation still belong in the application.

Rate Limiting

Limits request frequency by path, IP, header, or request characteristics.

Login endpoints, SMS verification, public APIs, AI model call endpoints, upload endpoints – all should consider rate limiting. It prevents malicious abuse, crawlers exhausting your quota, or a single IP overloading your Worker. Rate limiting is not a business permission system; it solves “too frequent access”, not “does this person have permission”.

DDoS Protection

Network‑ and application‑layer DDoS protection on Cloudflare’s edge network.

Cloudflare automatically absorbs and mitigates large attack traffic at the edge, with detection and rules at the HTTP layer. Most small projects don’t need dedicated configuration; when you are actually under attack, the key is to confirm that the domain is proxied through Cloudflare, the origin IP is not exposed, and cache and WAF policies aren’t dropping legitimate traffic.

API Shield

A collection of API security capabilities including schema validation, mTLS, discovery, and abuse detection.

For formal public APIs, mobile APIs, or partner APIs, use API Shield for OpenAPI schema validation, client certificates, API discovery, and risk analysis. Requests that don’t match the schema can be blocked at the edge, reducing anomalous traffic reaching Workers or origins. This leans toward formal API governance; early‑stage small projects may not need it. Its value grows as the API stabilizes and the number of callers increases.

Observability

mermaid flowchart TD Q1{"What to observe?"} Q1 -->|"Request issues, check logs"| LE["Log Explorer"] Q1 -->|"Verify configuration is working correctly"| TR["Trace"] Q1 -->|"Worker metrics and error rates"| OBS["Observability"] Q1 -->|"Push logs to external systems"| LP["Logpush"] Q1 -->|"Site traffic and frontend performance"| WA["Web Analytics"] Q1 -->|"Custom business event analytics"| AE["Analytics Engine"]

Log Explorer

Built‑in log search tool in the Cloudflare Dashboard.

When production requests go wrong, start here. Log Explorer lets you search by time, path, status code, Ray ID, service type, etc. – useful for determining whether the error occurred at the Cloudflare edge, in Worker code, cache rules, WAF, or at the origin. Good for ad‑hoc debugging; for long‑term retention and external analysis, use Logpush.

Trace

Simulate how a request passes through Cloudflare’s configuration.

If you want to know which rules a URL hits, whether it’s cached, whether it triggers a Worker, or if security rules affect it – use Trace. It’s for verifying why configuration behaves a certain way, not a full application APM. When you encounter “why isn’t this path redirecting/caching/forwarding as expected”, Trace is more reliable than eyeballing rules.

Logpush

Continuously push Cloudflare logs to external destinations.

For long‑term log retention, SIEM integration, or pushing to R2/S3/BigQuery/Splunk for analysis, use Logpush. It solves “logs need to leave Cloudflare and enter my data system”. Small projects don’t need to set this up from day one; enable it when you actually need compliance auditing, long‑term trends, or cross‑system debugging.

Web Analytics

Privacy‑friendly site traffic and frontend performance analytics.

Use it to track page views, referrers, countries, devices, Web Vitals, and frontend performance. It doesn’t rely on traditional third‑party ad tracking models and can be added via a JS snippet even to websites not proxied through Cloudflare. Great for landing pages, documentation sites, blogs, and product pages. For deeper growth analytics, consider specialized tools later.

Observability

Run‑time visibility for Workers and Pages.

After your API is live, check request volume, error rates, latency, exception logs, and deployment version performance here. Workers Logs, Invocation Logs, metrics, and traces all fall under this line. It answers “how is the code running?”; Log Explorer is more about “what happened at the request and edge layer”.

Analytics Engine

Custom metrics and event analytics engine within Workers.

If you want to write business events in a Worker – button clicks, API latency, model call cost, user behavior – and then aggregate with SQL, look at Analytics Engine. It’s great for high‑cardinality event analytics, not as a transactional database, nor for storing records that require per‑row strong‑consistent queries.

2. AI Coding Workflow

The biggest pitfall when AI writes Cloudflare code isn’t syntax – it’s that the AI doesn’t know what Cloudflare offers and where the boundaries are. The solution is simple: first give the AI a “manual” and a “toolbox” for Cloudflare, so it can look up official docs and understand binding patterns, then move on to coding and deployment.

Setup in Three Minutes

Using Codex (OpenAI official client):

cd your-cloudflare-project
codex

Inside Codex, type /plugins, search for Cloudflare, press Enter to install. Done. This automatically installs Cloudflare Skill, MCP, and integration – no manual steps needed.

Using Claude Code (Anthropic official client):

cd your-cloudflare-project
claude

Inside Claude Code, enter these two lines in sequence:

/plugin marketplace add cloudflare/skills
/plugin install cloudflare@cloudflare

Done. Same effect as Codex.

What Each Thing Is For

Skill = Instruction Manual
Helps the AI understand how to develop with Cloudflare. It covers Workers, Pages, R2, D1, KV, Queues, Durable Objects, Agents SDK, Wrangler, Email, etc. Once installed, the AI won’t treat you like a regular Node.js project.

MCP = Connector
Lets the AI connect to your Cloudflare account and official docs. After the plugin is installed, the following MCPs are registered automatically – you don’t need to add them one by one:

• Docs MCP: allows the AI to query official docs (always on for daily work)
• Cloudflare API MCP: allows the AI to operate your account (enable when deploying or changing configuration)
• Observability MCP: allows the AI to view live logs (enable when debugging)
• Workers Builds MCP: allows the AI to view build records
• Browser Run MCP: allows the AI to open a browser for testing

Wrangler = The actual command‑line tool that does the work
Skill and MCP help the AI understand; Wrangler is what actually runs and deploys on your machine. Install it in your project:

npm i -D wrangler@latest

The three most common commands:

npx wrangler dev        # Run locally
npx wrangler deploy     # Deploy to production
npx wrangler tail       # View live logs

Universal Approach

If you don’t want plugins or are using an agent other than Codex/Claude Code (e.g. OpenCode, Pi), you can install the official Skill package with one command:

npx skills add https://github.com/cloudflare/skills

This repo is maintained by Cloudflare and supports Claude Code, OpenCode, OpenAI Codex, Pi, and other mainstream agents.

Starting a New Project from Scratch

If you haven’t even created a project yet, start with:

npm create cloudflare@latest -- my-worker

Follow the prompts. After creation, go into the project, install Wrangler and the plugin, and start letting the AI write code.

What to Feed the AI When Something Goes Wrong in Production

The AI can open Observability MCP to view logs and Browser Run MCP to check the Dashboard, but it doesn’t know what you see in production. Before asking it to debug production issues, give it the following:

• The full URL that failed
• Time and timezone of occurrence
• HTTP status code (like 522, 1101)
• cf-ray or Ray ID from the response header – this is Cloudflare’s unique identifier for that request; the AI can use it to precisely locate the request in logs
• Whether it only happens in a specific region, ISP, browser, or authentication state
• The last deployment commit and Cloudflare deployment/version
• Whether the request hit cache, WAF, Rate Limiting, Access, or a Worker

Quick way to get response headers locally:

curl -I https://example.com/path

If you don’t know which layer an error code belongs to, see the error code index table at the start of Section 5. The AI might see 522 and directly modify Worker code, but 522 is actually an origin issue – when feeding context, also tell it which layer the error code belongs to, which saves a lot of detours.

One‑Line Summary

Install plugin first → helps AI understand Cloudflare
Add Wrangler next → lets AI actually execute
Docs MCP on by default → allows AI to query documentation
Only enable API MCP when modifying account → allows AI to deploy and change config

Common Architecture Patterns

Below are the most common architecture combinations on Cloudflare, with applicable scenarios and trade‑offs.

Pattern 1: Worker + D1 + R2 (Full‑Stack App)

flowchart LR
    Client --> Worker
    Worker --> D1["D1: metadata/users/orders"]
    Worker --> R2["R2: files/images/attachments"]
    Worker --> KV["KV: config/cache"]

Applicable: SaaS prototype, content management, API service. D1 stores structured data and business relationships, R2 stores file bodies, KV caches frequently read configuration. This is the most natural combination when AI generates a full‑stack project.
Trade‑off: D1 is not Postgres; for complex transactions and high‑concurrency writes, consider Hyperdrive connecting to an external database.

Pattern 2: Workers Static Assets + Worker (Frontend + Backend)

flowchart LR
    Client -->|"Static asset request"| SA["Static Assets: HTML/CSS/JS/images, free and unlimited"]
    Client -->|"/api/* dynamic request"| W["Worker: API/auth/business logic"]
    W --> D1
    W --> R2

Applicable: React/Vue/Svelte frontend + API backend. Static asset requests are free and don’t count toward Worker quota; only dynamic requests consume Worker allowance.
Trade‑off: Frontend and backend are tightly coupled in the same Worker project – good for small teams and fast iteration. Larger teams may need separate services.

Pattern 3: Worker + Durable Objects + WebSocket (Real‑Time Collaboration)

flowchart LR
    C1["Client A"] -->|WebSocket| DO["Durable Object: room/session state"]
    C2["Client B"] -->|WebSocket| DO
    C3["Client C"] -->|WebSocket| DO
    DO --> SQLite["DO SQLite Storage"]

Applicable: Chat rooms, collaborative editing, online games, real‑time dashboards. Durable Objects provide single‑instance strong consistency and WebSocket support; Hibernation mode can significantly reduce long‑connection cost.
Trade‑off: A single DO handles about 500–1000 req/s; high concurrency requires sharding by entity. Not suitable as a general‑purpose database.

Pattern 4: Worker + Queues + Workflows (Async Processing)

flowchart LR
    API["Worker API"] -->|"send message"| Q["Queues: buffer/peak shaving"]
    Q --> Consumer["Consumer Worker"]
    Consumer -->|"start"| WF["Workflows: multi‑step persistent flow"]
    WF --> D1
    WF --> Email["Email Sending"]

Applicable: Order processing, data pipelines, AI moderation flows, user lifecycle emails. Queues act as entry buffer and peak shaver; Workflows handle multi‑step processing, retrying only the failed step.
Trade‑off: Higher architectural complexity; simple synchronous APIs don’t need this mechanism.

Pattern 5: Worker + AI Gateway + External Models (AI Application)

flowchart LR
    Client --> Worker
    Worker --> AIG["AI Gateway: observability/cache/rate limiting"]
    AIG --> OA["OpenAI"]
    AIG --> AN["Anthropic"]
    AIG --> WAI["Workers AI"]
    Worker --> VZ["Vectorize: RAG retrieval"]
    VZ --> R2["R2: document storage"]

Applicable: AI chat, RAG Q&A, multi‑model routing. AI Gateway unifies invocation, caching, and cost across multiple model providers; Vectorize handles semantic retrieval; R2 stores original documents.
Trade‑off: Workers AI’s model capabilities are limited – complex reasoning and multimodal scenarios still require external models.

AI Coding Cloudflare Common Pitfalls

When AI generates Cloudflare code, the most frequent mistakes aren’t syntax errors but ignorance of Cloudflare runtime constraints. Here are high‑frequency pitfalls and the correct practices:

1. Writing Workers with Node.js mindset
AI often generates code like require('fs'), express(), http.createServer() – Workers are not Node.js; they have no filesystem or native HTTP server. The correct approach is to use Web standard APIs (fetch, Request, Response) and Workers‑native frameworks like Hono.

2. Treating bindings as environment variables
AI may generate process.env.MY_KV to access KV or D1. Cloudflare bindings are passed via the env parameter – correct: env.MY_KV.get(key) or env.DB.prepare(sql).

3. Ignoring floating promises
AI often leaves async calls unawaited (e.g., KV.put(), fetch()). In Workers, operations with unhandled promises are silently discarded. Every async operation must either be awaited or passed to ctx.waitUntil().

4. Storing request state in global variables
AI might declare `let cache =