Improve AGENTS.md files based on recurring PR review feedback

[petebacondarwin]

Analyzed review comments from the last 100 merged PRs to identify recurring patterns that should be codified in agent guidance.

Changes

Root AGENTS.md

Code Style (3 new rules):

• Prefer function declarations over const arrow functions for named/exported functions
• ESLint disable comments must use -- double-dash separator before reason
• Never modify generated files directly — modify the generator/config instead

Testing Standards (6 new items):

• Full expect from test context pattern with sub-bullets covering destructured context, ExpectStatic parameter passing, import type usage, node:assert fallback, and the E2E globals: true caveat
• Snapshot update reminder when changing user-facing strings
• Test fixture tsconfig.json requirement for vitest-pool-workers-examples/
• Test fixtures as user-facing recipes (avoid type casting)

Changesets (1 new rule):

• Focus on user-facing impact; reference the public-facing package, not internal packages

Anti-Patterns (2 new entries):

• Trivial/obvious code comments (explain "why" not "what")
• Cross-package type/constant duplication

Subdirectory Knowledge:

• Keep AGENTS.md files updated when making architectural changes

packages/wrangler/AGENTS.md

• E2E vitest config globals: true caveat (most common source of ReferenceError bugs)
• Check ALL call sites when adding expect parameter to helpers

packages/miniflare/AGENTS.md

• New "Generated Files" section documenting workerd.ts and openapi.local.json as generated

Evidence from PR reviews

The most frequently recurring themes across the last 100 PRs:

Theme	PRs where it came up
expect from test context	#13255, #13149, #13180, #13164, #13102, #13084
Trivial AI-generated comments	#13240
Stale AGENTS.md after arch changes	#13243
Prefer function over arrow	#13102
Generated files modified directly	#13240
Cross-package duplication	#13073
Missing fixture tsconfig.json	#13079
ESLint disable -- format	#13149
Changeset scope/focus	#13079, #13087

---

• Tests
  • Tests included/updated
  • Automated tests not possible - manual testing has been completed as follows:
  • Additional testing not necessary because: documentation-only changes to AGENTS.md files
• Public documentation
  • Cloudflare docs PR(s):
  • Documentation not necessary because: internal agent guidance only

---

[changeset-bot]

⚠️ No Changeset found

Latest commit: c691c62

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[workers-devprod]

Codeowners approval required for this PR:

• ✅ @cloudflare/wrangler

Show detailed file reviewers

[ask-bonk]

Everything checks out. The changes are documentation-only updates to AGENTS.md files, adding codified guidance based on recurring PR review feedback. The referenced files exist, the descriptions are accurate, and the content is well-structured and actionable.

LGTM

github run

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

[pkg-pr-new]

create-cloudflare

npm i https://pkg.pr.new/create-cloudflare@13408

@cloudflare/kv-asset-handler

npm i https://pkg.pr.new/@cloudflare/kv-asset-handler@13408

miniflare

npm i https://pkg.pr.new/miniflare@13408

@cloudflare/pages-shared

npm i https://pkg.pr.new/@cloudflare/pages-shared@13408

@cloudflare/unenv-preset

npm i https://pkg.pr.new/@cloudflare/unenv-preset@13408

@cloudflare/vite-plugin

npm i https://pkg.pr.new/@cloudflare/vite-plugin@13408

@cloudflare/vitest-pool-workers

npm i https://pkg.pr.new/@cloudflare/vitest-pool-workers@13408

@cloudflare/workers-editor-shared

npm i https://pkg.pr.new/@cloudflare/workers-editor-shared@13408

wrangler

npm i https://pkg.pr.new/wrangler@13408

commit: c691c62

[ascorbic]

Nice. Good idea

[workers-devprod]

Codeowners reviews satisfied