How real projects brief Codex, Cursor and every other agent that reads AGENTS.md.
CloudflareAGENTS.mdcloudflare/workerd/src/workerd/util/AGENTS.md
Shared utility library: data structures, SQLite wrapper, feature gating, logging, thread-local scopes. No workerd-specific API dependencies — consumed across api/, io/, server/.
CloudflareAGENTS.mdcloudflare/workerd/types/AGENTS.md
Generates @cloudflare/workers-types .d.ts files from C++ RTTI (via jsg/rtti.capnp) + hand-written defines/*.d.ts. A workerd-hosted Worker extracts RTTI at runtime per compat-date; TypeScript transforms post-process into ambient and importable outputs. CI validates generated-snapshot/ matches. Types in this project come from three layers. Changes must be made in the correct layer: Do not edit files in generated-snapshot/ directly — they are overwritten by just generate-types. If the generated output looks wrong, fix the source layer (C++ RTTI, JSGTSOVERRIDE, or defines/). Types in…
CloudflareAGENTS.mdcloudflare/agents/design/AGENTS.md
Internal design records — the "why" behind decisions in this repo and its libraries. This is the Diátaxis explanation quadrant: architecture rationale, tradeoffs, and alternatives considered. Living documents that describe how a concept or subsystem works right now. Named by topic: state.md, mcp.md, visuals.md. These are the primary entry point — a contributor looking for "how does state work" should open one file and get the full picture. Design docs get updated as the implementation evolves. They always reflect the…
CloudflareAGENTS.mdcloudflare/agents/docs/AGENTS.md
User-facing documentation for the Agents SDK monorepo. Each package owns the directory under docs/ matching its unscoped package name. These markdown files are manually synced to developers.cloudflare.com/agents/ where applicable. We follow Diátaxis to keep docs focused. Every doc should have a clear primary type: The fourth Diátaxis type — explanation ("understand why") — lives in /design, not here. If you're writing about why something was designed a certain way, put it there. If you're writing about how to use something,…
CloudflareAGENTS.mdcloudflare/agents/examples/webmcp-react/AGENTS.md
WebMCP should work out of the box. If it does not:
CloudflareAGENTS.mdcloudflare/agents/packages/agents/src/tests/capabilities/AGENTS.md
Harness Durable Objects for testing Lifecycle capabilities — the lower-level sibling of ../agents/ (which holds Agent-level fixture classes). One file per capability, all registered in the shared workers project (../worker.ts + ../wrangler.jsonc), all driving real Durable Objects. - harness.ts — the generic tier's bare CapabilityHarnessObject. Its driver, withCapabilityHarness() (in ../shared/capability-harness.ts), binds per-test-constructed capabilities to a real Lifecycle over real SQLite storage — a new capability gets isolation tests with zero new wiring. - lifecycle.ts — fixtures for the Lifecycle core…
CloudflareAGENTS.mdcloudflare/cloudflare-docs/AGENTS.md
This file helps AI agents understand the structure, tooling, and conventions of the cloudflare-docs repository so they can make correct, buildable changes. This is the source for developers.cloudflare.com. It is…
CloudflareAGENTS.mdcloudflare/workers-sdk/AGENTS.md
This file helps AI coding agents work effectively in the Cloudflare Workers SDK monorepo. Prefer authoritative configuration and documentation over copying details into this file: copied versions, rule lists, and counts become stale. - Use pnpm, not npm or yarn. - Use the Node.js and pnpm versions declared in package.json. - Install dependencies with pnpm install. - Run commands from the workspace root unless package documentation says otherwise. - Before changing a package, read its AGENTS.md if it has one.…
CloudflareAGENTS.mdcloudflare/workers-sdk/packages/create-cloudflare/AGENTS.md
Project scaffolding CLI for Cloudflare Workers. Main source entry: src/cli.ts. Bin entry: bin/c3.js (Node.js version gate shim).
CloudflareAGENTS.mdcloudflare/workers-sdk/packages/miniflare/AGENTS.md
Local dev simulator for Cloudflare Workers, powered by workerd runtime. Main class Miniflare in src/index.ts.
CloudflareAGENTS.mdcloudflare/workers-sdk/packages/vitest-plugin/AGENTS.md
Custom Vitest pool for running Worker tests inside the actual workerd runtime. Do NOT repeat root AGENTS.md content (pnpm, changesets, code style, etc.). - Runs in Node.js, part of the pool bundle (no separate package export) - Validates pool options (WorkersPoolOptionsSchema) and resolves the project's Worker configuration into Miniflare options - src/pool/plugin.ts provides the cloudflareTest() Vite plugin, which injects cloudflare:test resolution and sets resolve conditions (workerd, worker, browser) parseCustomPoolOptions() in src/pool/config.ts resolves at most one configuration file into a normalised…
CloudflareAGENTS.mdcloudflare/workers-sdk/packages/workers-auth/AGENTS.md
OAuth-2.0-with-PKCE flow against Cloudflare's dash.cloudflare.com (or staging / custom-overridden) endpoints. Used by wrangler and (in future) other Cloudflare CLIs. Internal-only — published as prerelease: true. Pluggable credential persistence layer that
CloudflareAGENTS.mdcloudflare/workers-sdk/packages/workers-utils/AGENTS.md
Shared utility package used across wrangler, miniflare, and others. Two main areas: config validation and test helpers.
CloudflareAGENTS.mdcloudflare/workers-sdk/packages/wrangler/AGENTS.md
Wrangler-specific context only. See root AGENTS.md for monorepo conventions. Main CLI for Cloudflare Workers. ~2k-line yargs command tree in src/index.ts. Entry point is src/cli.ts (NOT src/index.ts). - No console.* — use logger singleton - No _dirname / _filename — use getBasePath() - No global fetch — use undici's fetch - Route Cloudflare v4 API calls through the existing cfetch helpers such as fetchResult, fetchListResult, and fetchPagedListResult when possible; do not use global or undici fetch directly. Prefer these helpers over…
CloudflareAGENTS.mdcloudflare/capnweb/packages/docs/AGENTS.md
Astro, with Nimbus (@cloudflare/nimbus-docs) as the docs framework. The package handles content schemas, sidebar/TOC, MDX to markdown, search, OG cards, llms.txt, build hooks, and the nimbus-docs CLI. Everything in src/ is a real file in this repo and yours to edit, including the files the scaffold wrote. README.md next to this file explains why the site looks and works the way it does: the palette, the page shell, the WebGL hero, the example playgrounds, the traps. Read it before changing…
CloudflareAGENTS.mdcloudflare/kumo/packages/kumo/AGENTS.md
React component library: Base UI + Tailwind v4 + Vite library mode. ESM-only, tree-shakeable per-component exports. Parent: See root AGENTS.md for monorepo context.
CloudflareAGENTS.mdcloudflare/kumo/packages/kumo-docs-astro/AGENTS.md
Generated: 2026-09-03 | Commit: 9b4eb70 | Branch: rozenmd/test-preview Astro documentation site for @cloudflare/kumo. Static output uses React islands, MDX reference pages, Tailwind v4, and Cloudflare Workers static assets. Parent: See root AGENTS.md for monorepo-wide rules. vp run build:docs builds @cloudflare/kumo first. Production Astro builds use the package output, while development aliases Kumo imports to source for HMR. - Use ~/* for package-local imports; it maps to src/*. - Standard component pages use MdxDocLayout, then present the primary demo, installation, usage,…
CloudflareAGENTS.mdcloudflare/kumo/packages/kumo-docs-astro/src/components/demos/AGENTS.md
Executable Kumo examples used by documentation pages, the homepage showcase, visual regression, and component registry generation. - Registry files must use {Component}Demo.tsx names. - Registry exports must end in Demo. Both exported function declarations and exported arrow functions are supported. - Add JSDoc to exported function declarations when registry consumers need a description. The extractor does not collect arrow-function JSDoc. - Keep returned JSX self-contained and suitable for copying. The extractor reads the top-level return expression, not arbitrary runtime behavior.…
CloudflareAGENTS.mdcloudflare/kumo/packages/kumo-figma/AGENTS.md
Generates production-quality Figma components from component-registry.json. Destructive sync: purges and recreates all components per run. Parent: See root AGENTS.md for monorepo context.
CloudflareAGENTS.mdcloudflare/kumo/packages/kumo-figma/src/generators/AGENTS.md
37 component generators creating Figma components from component-registry.json. Registry is source of truth. Parent: See packages/kumo-figma/AGENTS.md for plugin context. Every generator follows this structure: ALL magic numbers and constants MUST live here: Key utilities:
An open format for instructions to coding agents, read by Codex, Cursor and others. Think of it as a README written for agents.
At the repository root, with more specific files in subdirectories. Agents read the one closest to the file they're editing.
Setup and test commands, code style, and the rules a new contributor would need to know.
Claude Code reads CLAUDE.md. A one-line CLAUDE.md that points at AGENTS.md covers both.
