AGENTS.md directory

Workers SDK

Wrangler and the toolchain for Cloudflare Workers.

States that copied values go stale, and points at the config that defines them instead.

Documents it routes to

This file points the agent at 3 other documents in the repository. Open any of them to read it here, as it was at this commit.


├── .changeset
│   └── 
├── .github
│   └── PULL_REQUEST_TEMPLATE.md — not in the repository at this commit
└── AGENTS.mdeach package's own AGENTS.md

By the numbers

153
Lines
1,099
Words
about 5 min read
8.9kB
File size
10
Headings
45
Bullet rules
0
Code blocks
0
Links to other docs
4.5k
Repo stars

File measured on main at commit f830836. Analysis written 2026-09-14. Star count is a snapshot from September 2026.

What kind of file this is

Opens with a rule about its own maintenance, then covers commands, a task-to-location table, cross-tool development, and testing conventions. Subsystem detail is delegated to per-package files.

Techniques in this file

Quoted lines are verbatim from the file. Open one to see it where it sits.

A stated policy against copying

Pointing at the source of truth

The second sentence of the file rules out copying details into it, naming versions, rule lists and counts as the things that go stale. Later sections apply it: the root package file is named as authoritative for scripts, and a validation command replaces a duplicated list of enforced lint rules.

A table indexed by task, not by directory

Fourteen rows map a thing the agent might be asked to do onto the location that handles it, with a note on each. The first column is the task rather than the path, so the table is read by intent.

A rule about which layer a feature belongs in

Three tools consume the same development platform, so a feature is stated to be incomplete if it only works through one of them. Implementation goes in the shared layer wherever possible, with the integration layers kept thin, and intentional gaps documented in the pull request.

Package files kept current in the same change

Nested instruction files

Packages carry their own instruction files, and the agent is directed to read the closest applicable one before making changes and to update it in the same change when the change makes it inaccurate. The division of content between the root file and package files is stated.

One security rule with its linter

Hard prohibitions

Shell commands may not be built from interpolated or concatenated untrusted input, and the custom lint rule that enforces it is named.

Takeaways for your own repo

  • Put the anti-drift rule in the file itself. Naming versions, rule lists and counts as things not to copy is what keeps it from rotting.
  • Index your repo map by task rather than by directory. Agents arrive with an intent, not a path.
  • If several tools consume one platform, state which layer a feature belongs in and that one consumer is not done.
  • Require the package instruction file to be updated in the same change that makes it wrong.

How the file is organized

  1. 01Start Here
  2. 02Common Commands
  3. 03Repository Map
  4. 04Cross-Tool Development Features
  5. 05Implementation Conventions
  6. 06Dependencies and Security
  7. 07Testing Conventions
  8. 08Changes and Pull Requests
  9. 09Package-Specific Guidance
Read the full file on GitHub

Context your AGENTS.md cannot carry

Workers SDK's file tells an agent how the codebase works. It cannot tell it which bug three customers hit this week. Modem keeps that context current and attaches it to the work.