# Règles Codex pour Cloudflare Workers

> Règles Codex pour les projets Cloudflare Workers qui empêchent l'utilisation d'API Node.js, imposent des modèles de liaison et maintiennent les agents dans les contraintes du runtime Workers.

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

---

Ajoutez ceci comme `AGENTS.md` ou un extrait de prompt système Codex. Les Cloudflare Workers s'exécutent sur le runtime V8 isolate — pas sur Node.js — donc les agents ont besoin de garde-fous explicites pour éviter de générer du code qui échoue silencieusement en développement local mais plante au déploiement.

## Fichier de règles Codex

```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.
```

## Pourquoi ces règles

- **Pas de `process.env`** est l'erreur la plus courante que les agents IA commettent avec Cloudflare Workers. Les agents entraînés sur des codebases Node.js et Next.js utilisent par défaut `process.env.MY_SECRET`. Sur Workers, cela vaut `undefined` à l'exécution — les liaisons passent par l'argument `env`, pas par l'environnement du processus.
- **`ctx.waitUntil()` pour les effets de bord** évite une classe subtile de bugs de perte de données. Workers termine l'isolate dès que la `Response` est renvoyée. Tout `await` exécuté après l'envoi de la réponse sans `waitUntil` est silencieusement ignoré, entraînant des événements d'analyse perdus, des échecs d'écriture de logs ou des mises à jour partielles de base de données.

## Bon ajustement

- APIs Cloudflare Workers, middleware edge, routeurs Workers basés sur Hono, Workers avec liaisons D1/KV/R2.

## Pas un ajustement

- Cloudflare Pages Functions (runtime similaire, mais convention de routage basée sur les fichiers différente) ou projets intentionnellement déployés sur Node.js via le flag `nodejs_compat` avec les API Node.js complètes activées.