Payload Agent Rules

A TypeScript CMS and application backend integrated with Next.js.

Overview

Payload's detailed instructions live in CLAUDE.md; AGENTS.md only points there. The guide covers CMS architecture and test fixtures, with examples for access control, React memoization, CSS, and server/client imports.

Hard prohibitions Behavioral framing Verification by change type Good and bad pairs

Documents

├── 
├── 
└── packages
    ├── codemod
    │   └── 
    └── create-payload-app
        └──

Techniques in this file

01 / Hard prohibitions

Make an unsafe default visible at the call site

Server functions and endpoints must supply both overrideAccess: false and the user to Payload operations. The guide contrasts a bare find call with the access-controlled form and explains the security consequence.

342**Building server functions, views, or endpoints:** Always use `overrideAccess: false` and pass the `user` to payload operations. Without these, the operation runs with access control disabled, which is a security vulnerability.

02 / Behavioral framing

Put database lifecycle in the shared fixture

Integration tests use the shared wrapper rather than initializing Payload or seeding data themselves. The fixture owns setup, per-test reset, and cleanup, except in existing shared-state suites.

173- Do not initialize Payload manually or add database reset/seed hooks; the fixture initializes174  Payload once per file, resets and seeds before each test that uses it, and destroys it afterward

03 / Verification by change type

Make visual baselines reproducible across machines

Screenshot baselines must be generated inside the pinned Playwright Docker image. The reason is the effect of operating-system font rendering on comparisons, even when the UI has not changed.

250- **Baselines must be generated/updated inside the pinned Playwright Docker image**, never on a251  bare host — font rendering differs enough between operating systems to fail the comparison on252  CI even when nothing visually changed. Use `pnpm test:visual:update`.

04 / Verification by change type

Verify bundling in the mode where it can fail

The server/client import rules explain why relative imports and barrel exports can cause production-only problems. The required verification builds and serves production output rather than relying on the dev server.

466**Testing bundling changes:** Always test with `pnpm prepare-run-test-against-prod` followed by `pnpm dev:prod <suite>`. Dev mode (`pnpm dev`) doesn't catch these issues.

05 / Good and bad pairs

Show physical and logical CSS properties side by side

A bad/good pair replaces left and right properties with inline-direction equivalents. The example makes the RTL requirement concrete across spacing, borders, and positioning.

390/* BAD - physical properties don't flip for RTL */391padding-left: var(--spacer-3);392margin-right: var(--spacer-2);393border-left: 1px solid var(--color-border);394left: 0;395 396/* GOOD - logical properties adapt automatically */397padding-inline-start: var(--spacer-3);398margin-inline-end: var(--spacer-2);399border-inline-start: var(--stroke-width-small) solid var(--color-border);400inset-inline-start: 0;