What to Put in AGENTS.md for a PHP and WordPress Repository

An effective AGENTS.md tells a coding agent how to work safely in one repository. It should contain stable project facts, exact verification commands, architecture boundaries, and instructions that cannot be inferred reliably from the code.

It should not become a second copy of every README, style guide, and product specification. Long files consume attention and become stale. Start with one complete, honest file, then explain only the decisions that need local context.

Start with one complete file

This compact template is a practical starting point for a PHP and WordPress plugin repository:

# AGENTS.md

## Project

- This repository builds the Example Membership plugin for WordPress.
- Minimum versions are PHP 8.1 and WordPress 6.5.
- `plugin.php` boots the plugin.
- `src/` and `templates/` contain production source.
- `assets/src/` contains editable browser assets.
- `assets/dist/` is generated and committed.
- `tests/Unit/` covers isolated rules.
- `tests/Integration/` boots WordPress for hooks, storage, and REST behavior.
- Never edit `vendor/` or `node_modules/`.

## Setup and verification

- Run PHP commands through `lando`.
- Install dependencies with `lando composer install` and `npm ci`.
- During development, run the narrowest relevant test.
- Before handoff, run `lando composer test`, `lando composer analyse`, and `lando composer lint`.
- Run `npm test` and `npm run build` after changing `assets/src/`.
- Report skipped checks and the reason.
- Never use production credentials or customer data locally.

## Architecture and implementation

- Keep business rules independent of WordPress globals and HTTP input.
- Controllers validate and adapt input, then call application services.
- Repositories own persistence. Templates render escaped data and perform no writes.
- Keep external systems behind focused adapters.
- Register WordPress hooks in dedicated integration classes.
- Follow the checked-in PHPCS and PHPStan configurations.
- Namespace project code under `Example\Membership`.
- Reuse existing helpers and keep each class focused on one responsibility.
- Preserve public hook contracts unless the task explicitly includes a deprecation.

## WordPress safety

- Validate input at the application boundary and escape output for its context.
- Verify nonces for state-changing browser requests and check capabilities separately.
- Use `$wpdb->prepare()` for values and allowlist dynamic identifiers.
- Add integration tests for capabilities, hooks, REST routes, cron callbacks, and migrations.
- Make activation and database upgrades safe to run more than once.

## Generated files and dependencies

- Change editable sources, then run the documented generator.
- Commit updated `assets/dist/` files when the build changes them.
- Keep lockfiles synchronized with manifests.
- Do not upgrade unrelated dependencies while fixing a bug.

## Git and release safety

- Use signed Conventional Commits.
- Keep refactoring separate from behavior changes.
- Preserve unrelated working-tree changes and never rewrite shared history.
- Do not push, merge, publish, or deploy without explicit authorization.
- Never commit secrets, auth state, database dumps, or personal data.

Replace every example name, version, path, and command. Run every command before committing the file. A shorter file that tells the truth is safer than a comprehensive template that describes a repository that does not exist.

Customize the repository map and commands

An agent first needs to know which files are source, which are generated, and which must not be edited directly. Name real entry points and directories. “Use best practices” cannot prevent an edit to generated output, but “change assets/src/, run npm run build, and commit assets/dist/” can.

Commands need the same precision. State their order, working directory, required services, environment variables, and whether they run on the host or through Lando. Distinguish the fast development loop from the full handoff or release gate.

Do not list a command because a similar repository uses it. A maintainer should be able to paste every documented command into a clean checkout and get the promised result.

Make verification task-specific

“Add tests” leaves too much to interpretation. Describe the evidence expected for common changes:

• Pure business rules receive unit tests.
• Database queries, WordPress hooks, REST routes, and capabilities receive integration tests.
• Bug fixes begin with a failing regression test when the behavior is safely reproducible.
• Schema migrations are tested from a clean install and the previous schema version.
• Payment, mail, and HTTP tests use fakes or sandbox services and never contact production.
• Snapshot updates require review of the rendered difference.
• Every handoff lists the commands run and any check that could not run.

Add localization, accessibility, performance, packaging, or compatibility checks only when the project requires them. The file should encode the repository's real definition of done, not a generic ideal.

Encode boundaries tools cannot infer

Architecture guidance should name dependency directions and ownership. Explain that controllers adapt input, services own use cases, repositories own persistence, and templates do not write data only if those statements match the codebase. Point to domain documentation for details rather than copying it into the instruction file.

Keep formatter and linter configuration as the authority for mechanical style. Use AGENTS.md for choices those tools cannot express, such as supported PHP versions, exception boundaries, generated-file policy, public hook compatibility, and when a database integration test is mandatory.

Delivery boundaries belong here too. Pushing a branch, merging a pull request, publishing a package, and deploying a site affect other people. State exactly which actions require authorization.

Never include credentials, customer data, private URLs, production dumps, or temporary incident details. Describe how approved test credentials are supplied, such as an environment variable, without storing or printing the value.

Understand scoped discovery before relying on it

Codex builds its instruction chain once when a run starts. It begins at the project root and walks down only as far as the current working directory, loading at most one supported instruction file per directory. A closer file has later precedence. The official Codex AGENTS.md guide documents the exact discovery and override rules.

Consider this repository:

AGENTS.md
tests/
  Integration/
    AGENTS.md
    MembershipApiTest.php

Starting Codex in the repository root loads the root file and stops there. The nested tests/Integration/AGENTS.md is not proven active merely because a later task edits MembershipApiTest.php. Starting a new run with tests/Integration as the working directory loads the root instructions followed by the nested instructions.

Verify the chain instead of assuming it:

codex --ask-for-approval never "List the instruction sources you loaded."
codex --cd tests/Integration --ask-for-approval never \
  "List the instruction sources you loaded."

The first command should report the global and repository-root guidance. The second should also report the integration-test file last. Restart the run after changing discovery configuration because an existing run does not rescan nested files dynamically.

This is Codex behavior, not a universal standard for every coding agent. If a repository supports several tools, keep shared rules consistent and document tool-specific discovery only where it differs.

Review AGENTS.md like code

Update the file when project structure, support policy, commands, generated output, or authority boundaries change. During review, confirm that:

• Every path and command exists in a clean checkout.
• Source and generated files are distinguished.
• Architecture rules match the actual domain model.
• Test requirements identify observable evidence.
• Dangerous external actions have explicit boundaries.
• Scoped files are verified from the intended working directory.
• No secret, personal data, or short-lived operational fact is present.

The best AGENTS.md reduces guesswork without replacing engineering judgment. It gives an agent the same durable orientation a careful maintainer would give a new teammate: where to work, how to prove the change, and where authority stops.