How real projects brief Codex, Cursor and every other agent that reads AGENTS.md.
CloudflareAGENTS.mdcloudflare/workerd/src/workerd/jsg/AGENTS.md
See README.md for terse reference (type mappings, macro catalog, error catalog). See docs/jsg.md for narrative tutorial. Macro-driven C++/V8 binding layer: declares C++ types as JS-visible resources/structs with automatic type conversion.
CloudflareAGENTS.mdcloudflare/workerd/src/workerd/server/AGENTS.md
Binary + orchestration layer. :workerd is a Rust binary: the :workerd-cli crate (cli/) parses the command line (clap), produces the encoded config (schema files via config-compiler.c++), handles --watch and compile, and runs each serving subcommand (serve, compile, test, fuzzilli, pyodide-lock, make-pyodide-baseline-snapshot) through a run_* function in cli-main.c++. Server (server.c++, ~6K lines) is the god object: parses workerd.capnp config, constructs all service types as nested inner classes, wires sockets/bindings/actors, runs the event loop.
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/AGENTS.md
Cloudflare Agents SDK — a framework for building stateful AI agents on Cloudflare Workers. This is a monorepo containing the core SDK packages, examples, guides, sites, and documentation. Some directories have their own AGENTS.md with deeper guidance: Node 24+ required. Uses pnpm workspaces with Nx for task orchestration, caching, and affected detection. Run from the repo root: Run an exampl
CloudflareAGENTS.mdcloudflare/agents/agent-think/AGENTS.md
A Think agent (@cloudflare/think) that reproduces and fixes cloudflare/agents GitHub issues inside a container-backed @cloudflare/workspace VFS. Anyone trusted on the repo triggers it from an issue comment: e.g. @agent-think reproduce this issue or @agent-think open a PR fixing this. It runs the matching skill (reproduce / open-pr) in a real Linux container and reports back on the issue as the agent-think GitHub App — never impersonating the triggering user. - Replace CI-runner automations (the /repro + /pr Actions shape from…
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/AGENTS.md
Self-contained demo apps that show how to use the Agents SDK. These are user-facing learning material — keep them simple, clear, and consistent. Each example should focus on one feature or concept (e.g., MCP servers, email routing, workflows). The exception is playground/, which is the kitchen-sink showcase covering the full spread of SDK features in a single app. Most examples have both a frontend and a backend. This makes them immediately runnable and visually demonstrable — users can pnpm run…
CloudflareAGENTS.mdcloudflare/agents/examples/webmcp-react/AGENTS.md
WebMCP should work out of the box. If it does not:
CloudflareAGENTS.mdcloudflare/agents/guides/AGENTS.md
In-depth, pattern-oriented tutorials — runnable apps with substantial narrative READMEs that teach how to build a particular kind of agent application. If it demonstrates a single feature, it belongs in /examples. If it teaches an approach or pattern, it belongs here. Guides are runnable apps with the same structural conventions as examples: The README is the guide. The code is the supporting material. A guide README should walk a reader through the application, explaining both what the code does and…
CloudflareAGENTS.mdcloudflare/agents/packages/agents/AGENTS.md
The core Agents SDK, published to npm as agents. This is the most complex package in the monorepo. Each export maps to a public entry point that users import from. These are the boundaries of the public API — changes here need a changeset.
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/vibesdk/AGENTS.md
No summary in the file. Open it to read it.
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/cloudflare-docs/.flue/AGENTS.md
.flue/ is the Cloudflare Worker that reviews pull requests for cloudflare/cloudflare-docs. It uses Flue 2.1.0, Cloudflare Workflows, R2, Workers AI, and Hono. app.ts verifies GitHub webhooks and delegates to the…
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/auto-triage-bot/AGENTS.md
This package contains the private Flue application for agent-powered Workers SDK automation. Channels receive events from external services and dispatch specialized agents with narrowly scoped tools and runtime access. GitHub issue reproduction is the first implemented workflow, not the boundary of the application. Keep shared architecture generic enough for additional maintenance and triage workflows without prematurely abstracting code used by only one workflow. Run the focused checks from the repository root: Run pnpm prettify before committing. There is currently no…
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.
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.
