Skip to content

Docs: Add minimal agent guidance - #455

Open
ebinnion wants to merge 1 commit into
trunkfrom
update/agents-md-minimal-guidelines
Open

ebinnion wants to merge 1 commit into
trunkfrom
update/agents-md-minimal-guidelines

Conversation

@ebinnion

@ebinnion ebinnion commented Feb 18, 2026 •

Copy link
Copy Markdown
Contributor

Across Automattic, we're attempting to improve the agent experience of our codebases. At a high level, this includes the following:

  • Guidelines: The repo tells agents what they need to know: project structure, conventions, gotchas, and explicit instructions via AGENTS.md, CLAUDE.md, and skills. A developer can point an agent at the repo and it understands how to work in it. See the Field Guide article linked above the table.
  • Build & Tests: An agent can build the project and run tests on its own. It can verify its code compiles and doesn't break existing functionality without human hand-holding.
  • E2E Verification: An agent can check that its changes actually work — not just that tests pass, but that the feature behaves correctly from a user's perspective (e.g. local dev server, preview URL).
  • Isolated ENV: An agent can work in a sandboxed environment where it's safe to experiment. Mistakes don't touch production or shared state, so developers can let agents run with less supervision.

All Submissions:

  • Does your code follow the WooCommerce Sniffs variant of WordPress coding standards?
  • Have you written new tests for your changes, as applicable?
  • Have you successfully run tests with your changes locally?
  • Will this change require new documentation or changes to existing documentation?

Changes proposed in this Pull Request:

Add AGENTS.md and CLAUDE.md with minimal guidance for agents.

Steps to test the changes in this Pull Request:

  1. Checkout branch
  2. Ask agent (Claude Code or Codex) to do things like build the plugin or to use playwright to determine the state of the plugin.

Changelog entry

Add - Agent guidance for development.

Closes #456

Closes #457

Closes #458

Closes #460

Closes #461

@ebinnion ebinnion self-assigned this Feb 18, 2026
@github-actions

Copy link
Copy Markdown

This is linked to GitHub issue #456.

@github-actions

Copy link
Copy Markdown

This is linked to GitHub issue #457.

@github-actions

Copy link
Copy Markdown

This is linked to GitHub issue #458.

@github-actions

Copy link
Copy Markdown

This is linked to GitHub issue #459.

@github-actions

Copy link
Copy Markdown

This is linked to GitHub issue #460.

@github-actions

Copy link
Copy Markdown

This is linked to GitHub issue #461.

@ebinnion

Copy link
Copy Markdown
Contributor Author

I guess all of these extra issues might've got created because I was also checking checkboxes shortly after submitting the PR?

@vikrampm1

Copy link
Copy Markdown
Contributor

I guess all of these extra issues might've got created because I was also checking checkboxes shortly after submitting the PR?

Not sure what caused it, the automation generally checks for a Linear link and if the link is not found, it creates a GH issue, but only once. Maybe the checkboxes indeed triggered those duplicates.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment