# Codex-Regeln für Cloudflare Workers

> Codex-Regeln für Cloudflare Workers-Projekte, die die Nutzung von Node.js-APIs verhindern, Binding-Muster erzwingen und Agenten innerhalb der Workers-Laufzeitbeschränkungen halten.

**Type:** Rule  
**Tools:** Codex, Cursor, Claude Code  
**Stack:** Cloudflare, TypeScript  
**Updated:** 2026-06-08

---

Fügen Sie dies als `AGENTS.md` oder ein Codex-System-Prompt-Snippet hinzu. Cloudflare Workers laufen auf der V8-Isolate-Laufzeit – nicht Node.js –, daher benötigen Agenten explizite Leitplanken, um zu vermeiden, dass Code generiert wird, der in der lokalen Entwicklung stillschweigend fehlschlägt, aber bei der Bereitstellung abstürzt.

## Codex-Regeldatei

```txt title="Codex Rules"
# Cloudflare Workers Rules

## Runtime constraints — READ FIRST
- This project runs on the Cloudflare Workers runtime (V8 isolate), NOT Node.js.
  Node.js built-ins (`fs`, `path`, `crypto` from `node:crypto` pre-Workers-crypto,
  `child_process`, `net`, `dgram`) are NOT available unless explicitly listed as
  available in the wrangler compatibility flags.
- Allowed globals: `fetch`, `Request`, `Response`, `Headers`, `URL`, `URLSearchParams`,
  `ReadableStream`, `WritableStream`, `TransformStream`, `TextEncoder`, `TextDecoder`,
  `crypto` (Web Crypto API), `caches` (Cache API), `setTimeout`, `clearTimeout`.
- Do NOT use `process.env`. Environment variables and secrets are accessed via the
  `Env` bindings object passed to the `fetch` handler as the second argument.
- Do NOT import `node:*` modules unless `nodejs_compat` is set in `wrangler.toml`
  and you have confirmed the specific module is available in that compat mode.

## Bindings pattern
- All KV, R2, D1, Durable Object, Queue, and AI bindings are declared in
  `wrangler.toml` and typed in `src/types/env.d.ts` (or `worker-configuration.d.ts`).
- Access bindings only through the `env` parameter of the `ExportedHandler` fetch
  method: `export default { async fetch(req, env, ctx) { ... } }`.
- Never instantiate KV or R2 clients manually — use the env binding directly.
- Run `wrangler types` after adding a new binding to regenerate the TypeScript types.

## Request/Response handling
- Always return a `Response` object from the `fetch` handler. Never `throw` outside
  a try/catch at the handler boundary — unhandled errors surface as opaque 500s.
- Use `ctx.waitUntil()` for fire-and-forget async work (logging, analytics writes)
  so the isolate is not terminated before the side effect completes.
- Stream large responses with `ReadableStream` rather than buffering them entirely
  in memory — Workers have a 128 MB memory limit per isolate.

## Build and deploy
- Use `wrangler dev` for local development (not `node server.js` or any other runner).
- Test with `wrangler dev --remote` before deploying to catch binding resolution
  issues that only appear against real Cloudflare infrastructure.
- Deploy with `wrangler deploy`. Never edit the production worker via the Cloudflare
  dashboard directly — it diverges from the codebase.
- Bundle size must stay under 1 MB (compressed). Run `wrangler deploy --dry-run`
  and check the reported bundle size before merging large dependency additions.

## TypeScript conventions
- Strict mode enabled. No `any`. Use `unknown` for untrusted external data and
  narrow it with Zod or manual type guards before use.
- The `Env` interface must be in sync with `wrangler.toml`. If you add a binding
  in `wrangler.toml`, add the corresponding property to `Env` in the same PR.
- Use `satisfies ExportedHandler<Env>` on the default export to catch binding
  type mismatches at compile time.

## Definition of done
- `wrangler check` (or `tsc --noEmit`) passes with zero errors.
- `wrangler dev` starts without warnings.
- `wrangler deploy --dry-run` reports bundle size under 1 MB.
- No `process.env` references in source. No `node:*` imports unless compat flag is set.
```

## Warum diese Regeln

- **Kein `process.env`** ist der häufigste Fehler bei Cloudflare Workers, den KI-Agenten machen. Mit Node.js und Next.js trainierte Agenten greifen standardmäßig auf `process.env.MY_SECRET` zu. Bei Workers ist dies zur Laufzeit `undefined` – Bindungen erfolgen über das `env`-Argument, nicht über die Prozessumgebung.
- **`ctx.waitUntil()` für Seiteneffekte** verhindert eine subtile Klasse von Datenverlustfehlern. Workers beenden das Isolat, sobald die `Response` zurückgegeben wird. Jedes `await`, das nach dem Senden der Antwort ohne `waitUntil` ausgeführt wird, wird stillschweigend verworfen, was zu verlorenen Analyseereignissen, fehlgeschlagenen Log-Schreibvorgängen oder teilweisen Datenbankaktualisierungen führt.

## Geeignet für

- Cloudflare Workers APIs, Edge-Middleware, Hono-basierte Workers-Router, Workers mit D1/KV/R2-Bindungen.

## Nicht geeignet

- Cloudflare Pages Functions (ähnliche Laufzeit, aber andere dateibasierte Routing-Konvention) oder Projekte, die absichtlich über das `nodejs_compat`-Flag mit vollständigen Node.js-APIs auf Node.js bereitgestellt werden.