{
  "id": "codex-rules-for-cloudflare-workers",
  "type": "rules",
  "category": "rules",
  "locale": "es",
  "url": "/es/rules/codex-rules-for-cloudflare-workers",
  "title": "Reglas de Codex para Cloudflare Workers",
  "description": "Reglas de Codex para proyectos de Cloudflare Workers que previenen el uso de la API de Node.js, aplican patrones de enlace y mantienen a los agentes dentro de las restricciones del runtime de Workers.",
  "tools": [
    "Codex",
    "Cursor",
    "Claude Code"
  ],
  "stack": [
    "Cloudflare",
    "TypeScript"
  ],
  "tags": [
    "cloudflare",
    "typescript",
    "conventions",
    "deploy"
  ],
  "difficulty": null,
  "updated": "2026-06-08",
  "markdown": "Añade esto como `AGENTS.md` o un fragmento de prompt de sistema de Codex. Cloudflare Workers se ejecutan en el runtime de V8 isolate — no en Node.js — por lo que los agentes necesitan barreras explícitas para evitar generar código que falle silenciosamente en desarrollo local pero se bloquee en el despliegue.\n\n## Archivo de reglas de Codex\n\n```txt title=\"Codex Rules\"\n# Cloudflare Workers Rules\n\n## Runtime constraints — READ FIRST\n- This project runs on the Cloudflare Workers runtime (V8 isolate), NOT Node.js.\n  Node.js built-ins (`fs`, `path`, `crypto` from `node:crypto` pre-Workers-crypto,\n  `child_process`, `net`, `dgram`) are NOT available unless explicitly listed as\n  available in the wrangler compatibility flags.\n- Allowed globals: `fetch`, `Request`, `Response`, `Headers`, `URL`, `URLSearchParams`,\n  `ReadableStream`, `WritableStream`, `TransformStream`, `TextEncoder`, `TextDecoder`,\n  `crypto` (Web Crypto API), `caches` (Cache API), `setTimeout`, `clearTimeout`.\n- Do NOT use `process.env`. Environment variables and secrets are accessed via the\n  `Env` bindings object passed to the `fetch` handler as the second argument.\n- Do NOT import `node:*` modules unless `nodejs_compat` is set in `wrangler.toml`\n  and you have confirmed the specific module is available in that compat mode.\n\n## Bindings pattern\n- All KV, R2, D1, Durable Object, Queue, and AI bindings are declared in\n  `wrangler.toml` and typed in `src/types/env.d.ts` (or `worker-configuration.d.ts`).\n- Access bindings only through the `env` parameter of the `ExportedHandler` fetch\n  method: `export default { async fetch(req, env, ctx) { ... } }`.\n- Never instantiate KV or R2 clients manually — use the env binding directly.\n- Run `wrangler types` after adding a new binding to regenerate the TypeScript types.\n\n## Request/Response handling\n- Always return a `Response` object from the `fetch` handler. Never `throw` outside\n  a try/catch at the handler boundary — unhandled errors surface as opaque 500s.\n- Use `ctx.waitUntil()` for fire-and-forget async work (logging, analytics writes)\n  so the isolate is not terminated before the side effect completes.\n- Stream large responses with `ReadableStream` rather than buffering them entirely\n  in memory — Workers have a 128 MB memory limit per isolate.\n\n## Build and deploy\n- Use `wrangler dev` for local development (not `node server.js` or any other runner).\n- Test with `wrangler dev --remote` before deploying to catch binding resolution\n  issues that only appear against real Cloudflare infrastructure.\n- Deploy with `wrangler deploy`. Never edit the production worker via the Cloudflare\n  dashboard directly — it diverges from the codebase.\n- Bundle size must stay under 1 MB (compressed). Run `wrangler deploy --dry-run`\n  and check the reported bundle size before merging large dependency additions.\n\n## TypeScript conventions\n- Strict mode enabled. No `any`. Use `unknown` for untrusted external data and\n  narrow it with Zod or manual type guards before use.\n- The `Env` interface must be in sync with `wrangler.toml`. If you add a binding\n  in `wrangler.toml`, add the corresponding property to `Env` in the same PR.\n- Use `satisfies ExportedHandler<Env>` on the default export to catch binding\n  type mismatches at compile time.\n\n## Definition of done\n- `wrangler check` (or `tsc --noEmit`) passes with zero errors.\n- `wrangler dev` starts without warnings.\n- `wrangler deploy --dry-run` reports bundle size under 1 MB.\n- No `process.env` references in source. No `node:*` imports unless compat flag is set.\n```\n\n## Por qué estas reglas\n\n- **No `process.env`** es el error más común que los agentes de IA cometen en Cloudflare Workers. Los agentes entrenados en bases de código de Node.js y Next.js recurren a `process.env.MY_SECRET` por defecto. En Workers, esto es `undefined` en tiempo de ejecución — los enlaces vienen a través del argumento `env`, no del entorno del proceso.\n- **`ctx.waitUntil()` para efectos secundarios** previene una clase sutil de errores de pérdida de datos. Workers terminan el isolate tan pronto como se devuelve la `Response`. Cualquier `await` que se ejecute después de que se envíe la respuesta sin `waitUntil` se descarta silenciosamente, causando pérdida de eventos de analítica, escrituras de log fallidas o actualizaciones parciales de base de datos.\n\n## Buen ajuste\n\n- APIs de Cloudflare Workers, middleware de borde, enrutadores de Workers basados en Hono, Workers con enlaces D1/KV/R2.\n\n## No es adecuado\n\n- Cloudflare Pages Functions (runtime similar, pero convención de enrutamiento basada en archivos diferente) o proyectos que se despliegan intencionalmente en Node.js mediante la bandera `nodejs_compat` con las APIs completas de Node.js habilitadas."
}