AGENTS.md is a markdown file placed at your repository root that tells AI development tools how your project works. Unlike tool-specific files, an AGENTS.md provides unified configuration for any AI agent.
- The AGENTS.md file is a contextual and instructional file recognize by several AI agents, as described on the official AGENTS.md site.
- Creating an AGENTS.md file is recommended for all Projects, but is especially useful for software developers who use more than one AI agent as part of their development process.
An AGENTS.md file eliminates repetitive prompt instructions by establishing project conventions in one central location. Agents reference these guidelines automatically, ensuring consistent code generation that follows your project standards.
Your AGENTS.md file may include:
- Essential setup commands, build steps, and development server instructions for getting the project running quickly.
- Code style guidelines, formatting rules, and architectural patterns the project follows for consistent development.
- Testing workflows, quality checks, and merge requirements that must be completed before submitting code.
# Sample AGENTS.md file
## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to jump to a package instead of scanning with `ls`.
- Run `pnpm install --filter <project_name>` to add the package to your workspace so Vite, ESLint, and TypeScript can see it.
- Use `pnpm create vite@latest <project_name> -- --template react-ts` to spin up a new React + Vite package with TypeScript checks ready.
- Check the name field inside each package's package.json to confirm the right name—skip the top-level one.
## Testing instructions
- Find the CI plan in the .github/workflows folder.
- Run `pnpm turbo run test --filter <project_name>` to run every check defined for that package.
- From the package root you can just call `pnpm test`. The commit should pass all tests before you merge.
- To focus on one step, add the Vitest pattern: `pnpm vitest run -t "<test name>"`.
- Fix any test or type errors until the whole suite is green.
- After moving files or changing imports, run `pnpm lint --filter <project_name>` to be sure ESLint and TypeScript rules still pass.
- Add or update tests for the code you change, even if nobody asked.
## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing.In the example above, the AGENTS.md file includes details on running the application within a development environment, testing instructions, and details for creating pull requests.
Just like with .builderrules files, AGENTS.md files can be replicated in multiple directories.
Rules should be actionable, focused, precise, and scoped.
- Keep rules under 500 lines.
- Split large rules into multiple, composable rules.
- Provide concrete examples or referenced files.
- Avoid vague guidance. Write rules like clear internal docs.
- Ensure rules in one file do not conflict with rules in another file.
For more best practices and detailed examples, visit AI instruction best practices.
Full Agents.md file examples are included below.
Example file from Agents.md.
# AGENTS Guidelines for This Repository
This repository contains a Next.js application located in the root of this repository. When
working on the project interactively with an agent (e.g. the Codex CLI) please follow
the guidelines below so that the development experience – in particular Hot Module
Replacement (HMR) – continues to work smoothly.
## 1. Use the Development Server, **not** `npm run build`
* **Always use `npm run dev` (or `pnpm dev`, `yarn dev`, etc.)** while iterating on the
application. This starts Next.js in development mode with hot-reload enabled.
* **Do _not_ run `npm run build` inside the agent session.** Running the production
build command switches the `.next` folder to production assets which disables hot
reload and can leave the development server in an inconsistent state. If a
production build is required, do it outside of the interactive agent workflow.
## 2. Keep Dependencies in Sync
If you add or update dependencies remember to:
1. Update the appropriate lockfile (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`).
2. Re-start the development server so that Next.js picks up the changes.
## 3. Coding Conventions
* Prefer TypeScript (`.tsx`/`.ts`) for new components and utilities.
* Co-locate component-specific styles in the same folder as the component when
practical.
## 4. Useful Commands Recap
| Command | Purpose |
| ------------------ | -------------------------------------------------- |
| `npm run dev` | Start the Next.js dev server with HMR. |
| `npm run lint` | Run ESLint checks. |
| `npm run test` | Execute the test suite (if present). |
| `npm run build` | **Production build – _do not run during agent sessions_** |
---
Following these practices ensures that the agent-assisted development workflow stays
fast and dependable. When in doubt, restart the dev server rather than running the
production build.Wordpress' open-source Agents.md file.
# WordPress AI Client - Coding Agent Guide
## Project Overview
An AI client and API for WordPress to communicate with any generative AI models of various capabilities using a uniform API. Built on top of the [PHP AI Client](https://github.com/WordPress/php-ai-client), it provides a WordPress-native Prompt Builder, an Admin Settings Screen for credentials, automatic credential wiring, a PSR-compliant HTTP client, and a client-side JavaScript API.
## Commands & Scripts
* `composer lint`: Lints the PHP code (PHPCodeSniffer and PHPStan).
* `composer phpcs`: Runs PHPCodeSniffer on the PHP code.
* `composer phpstan`: Runs PHPStan on the PHP code.
* `npm run build`: Builds the JavaScript assets.
* `npm run format-js`: Formats the JavaScript code using Prettier.
* `npm run lint-js`: Lints the JavaScript code.
* `npm run lint-php`: Lints the PHP code using Composer inside the `wp-env` environment.
* `npm run test-php`: Runs PHPUnit tests with single site config inside the `wp-env` environment.
* `npm run test-php-multisite`: Runs PHPUnit tests with Multisite config inside the `wp-env` environment.
**Note:** In order to follow the WordPress code style in JavaScript, the project uses a WordPress-specific fork of Prettier (`wp-prettier`) under the hood.
## Coding Standards & Compatibility Constraints
This project adheres to the WordPress Coding Standards with specific exceptions for PSR-4 autoloading (file names match class names). More details about coding and documentation standards are outlined in the `CONTRIBUTING.md` file. Any agent working on this project MUST read and follow the guidelines in that file before starting any work.
* **PHP Version:** Code must be compatible with **PHP 7.4**.
* **Code Style:** All code (PHP and JavaScript) must be compliant with the WordPress Coding Standards.
* **Type Hints:** Use explicit type hints for parameters, return values, and properties where supported by PHP 7.4.
## Core Principles
* **Uniform API:** Provide a consistent interface for interacting with various AI providers.
* **WordPress Native:** Integrate deeply with WordPress APIs (Abilities API, HTTP API, Settings API).
* **Security:** Restrict access to powerful features (like arbitrary prompt generation via REST API) using capabilities (`prompt_ai`).
* **Standards Compliance:** Adhere to PSR standards where applicable (e.g., HTTP Client) while maintaining WordPress compatibility.
## Project Architecture Overview
The project consists of three main layers:
1. PHP SDK (`includes/`): The core logic, built on `wordpress/php-ai-client`. It handles prompt building, request execution, and response parsing. It also manages API credentials and integrates with WordPress core.
2. REST API (`includes/REST-API/`): Exposes the AI capabilities to the client-side. It handles authentication and validation.
3. JavaScript SDK (`src/`): A client-side library that mirrors the PHP Prompt Builder interface, communicating with the backend via the REST API.
## Directory Structure
* `build/`: Compiled JavaScript and CSS assets.
* `includes/`: Main PHP source files (PSR-4 autoloaded).
* `API_Credentials/`: Manages API keys and settings.
* `Builders/`: Prompt builder implementations.
* `Capabilities/`: Capability management.
* `HTTP/`: HTTP client integrations.
* `REST_API/`: REST API controllers.
* `src/`: Source TypeScript/JavaScript files.
* `tests/`: PHPUnit tests.
* `phpunit/`: Test suite configuration and test files.
* `vendor/`: Composer dependencies.
## Git Repo
The main branch for this project is called "trunk".
## Agent Guidelines
* **DO:** Read `CONTRIBUTING.md` before writing any code.
* **DO:** Ensure all PHP code is compatible with PHP 7.4.
* **DO:** Use `wp_enqueue_script( 'wp-ai-client' )` to load the JS SDK.
* **DO:** Add unit tests for new PHP functionality in `tests/phpunit/tests/`.
* **DO:** Run `npm run lint-php` and `npm run test-php` before submitting changes.
* **DON'T:** Use PHP 8.0+ features (e.g., constructor property promotion, union types, match expressions, enums).
* **DON'T:** Create new top-level directories without a strong reason.
* **DON'T:** Hardcode API credentials.
## Common Pitfalls
* **Ignoring the Fluent API:** While the traditional API is available, the fluent API is the preferred way for implementers to use the client. Avoid writing complex, nested method calls when the fluent API provides a cleaner alternative.
* **Duplicating Interface Documentation:** Manually writing PHPDoc descriptions for methods that implement an interface is a common pitfall. The `{@inheritDoc}` tag should be used instead to inherit the documentation from the interface.
* **Missing Capability Checks in REST:** Exposing AI generation endpoints without proper capability checks. Always ensure `prompt_ai` capability is checked for privileged operations.Learn more about Configuration files in Builder, or read up on AI instruction best practices.
Was this article helpful?