Back in August 2025 GitHub Copilot announced support for AGENTS.md, which is primarily a filename convention for passing context to the AI agent you are working with in the code repository, but its structure is also interesting to investigate as we will do here.

It's safe to say it's better to use a filename that's not specific to any single agent, for example, Copilot can also use copilot-instructions.md but other agents like Gemini might not read context from it. Additionally, the advantage of AI lies in its natural language syntax. This means any agent can use AGENTS.md without transformations, leading to more consistent output regardless of the agent.

The list of AI agents currently supporting this convention is quite extensive as seen on the official page, e.g., all the popular options are there:

• Codex
• Cursor
• Gemini
• VS Code
• GitHub Copilot

The 'official' guide for AGENTS.md can be found here.

Today AGENTS.md is stewarded by the Agentic AI Foundation which itself is a project of the Linux Foundations, so it's good to know there is an open-source home for these conventional standards going forward.

With that out of the way, what content goes into AGENTS.md?

Example

Here's an example AGENTS.md file for the spring petclinic demo application. The prompt that was used to generate can be found below.

# AGENTS.md

This document serves as a comprehensive practical guide for any human or automated "agent" (developer, CI system, bot) interacting with the codebase of the Spring PetClinic application. It outlines the development environment setup, testing procedures, pull request guidelines, and information about automated processes.

## 1. Dev Environment Tips

*   **Project Setup:**
    To get the Spring PetClinic application up and running locally:
    1.  **Clone the repository:**
        ```bash
        git clone https://github.com/spring-projects/spring-petclinic.git
        cd spring-petclinic
        ```
    2.  **Run the application:**
        Using Maven (recommended):
        ```bash
        ./mvnw spring-boot:run
        ```
        Or using Gradle:
        ```bash
        ./gradlew bootRun
        ```
    The application will typically be accessible in your web browser at `http://localhost:8080`.

*   **Local Dependencies:**
    The application by default uses an in-memory H2 database. For persistent database development, you can use MySQL or PostgreSQL. The `docker-compose.yml` file provides configurations to easily spin up these databases:
    *   **Start MySQL:**
        ```bash
        docker compose up mysql
        ```
    *   **Start PostgreSQL:**
        ```bash
        docker compose up postgres
        ```
    Refer to the `README.md` for more details on database configuration, including active Spring profiles.

*   **Workspace Navigation:**
    This project is structured as a single-module Java application. Standard directory navigation applies, without the complexities of a JavaScript-style monorepo.

*   **New Project Creation:**
    This `AGENTS.md` focuses on interacting with the existing Spring PetClinic project. Guidelines for creating new projects or modules are outside the scope of this document.

*   **Tooling Integration:**
    The project uses Java 17 or newer, built with Maven or Gradle.
    The `scss` files are compiled into `css` during the Maven build if the `css` profile is active (`./mvnw package -P css`).

*   **IDE/Editor Configuration:**
    The project is typically developed using popular Java IDEs. Refer to the main `README.md` for detailed instructions on setting up the project in:
    *   IntelliJ IDEA
    *   Eclipse (with m2e plugin)
    *   Spring Tools Suite (STS)
    For consistent coding styles, the project includes an `.editorconfig` file, which is supported by most modern editors and IDEs.

## 2. Testing Instructions

*   **CI/CD Overview:**
    The project utilizes GitHub Actions for Continuous Integration. Workflow definitions can be found in the `.github/workflows/` directory:
    *   `maven-build.yml`: For projects built with Maven.
    *   `gradle-build.yml`: For projects built with Gradle.
    These workflows trigger on `push` and `pull_request` events to the `main` branch, ensuring code quality and functionality.

*   **Running All Tests:**
    To execute the full test suite locally:
    *   **Using Maven:**
        The CI pipeline uses `verify`, which includes testing:
        ```bash
        ./mvnw verify
        ```
        To run only the tests:
        ```bash
        ./mvnw test
        ```
    *   **Using Gradle:**
        The CI pipeline uses `build`, which includes testing:
        ```bash
        ./gradlew build
        ```
        To run only the tests:
        ```bash
        ./gradlew test
        ```

*   **Running Specific Tests:**
    *   **Using Maven:**
        To run a specific test class (e.g., `OwnerControllerTests`):
        ```bash
        ./mvnw test -Dtest=OwnerControllerTests
        ```
        To run a specific test method within a class (e.g., `OwnerControllerTests.testInitCreationForm`):
        ```bash
        ./mvnw test -Dtest=OwnerControllerTests#testInitCreationForm
        ```
    *   **Using Gradle:**
        To run a specific test class (e.g., `OwnerControllerTests`):
        ```bash
        ./gradlew test --tests "*OwnerControllerTests*"
        ```
        To run a specific test method (e.g., `OwnerControllerTests.testInitCreationForm`):
        ```bash
        ./gradlew test --tests "*OwnerControllerTests.testInitCreationForm*"
        ```

*   **Linting and Type Checking:**
    *   **Code Style & Formatting:** The project enforces code style and formatting using `spring-javaformat-maven-plugin` and `maven-checkstyle-plugin`. These checks are integrated into the Maven `verify` lifecycle phase. The Checkstyle configuration, including `nohttp-checkstyle.xml`, is located in `src/checkstyle/`. Running `./mvnw verify` will perform these checks.
    *   **Type Checking:** As a Java project, strong type checking is an inherent part of the compilation process, executed during any build command (e.g., `./mvnw compile`, `./gradlew build`).

*   **Test Maintenance:**
    It is crucial to write new unit and integration tests for new features and update existing ones when modifying functionality. This practice helps maintain code quality, prevents regressions, and ensures the reliability of the application.

*   **Debugging Guides:**
    Debugging can be performed directly within your IDE (IntelliJ IDEA, Eclipse, STS) by running the `PetClinicApplication` main class in debug mode. Standard Java debugging tools and techniques apply.

*   **Performance Tuning:**
    While the `README.md` does not explicitly detail performance tuning guides, standard Java profiling tools (e.g., Java Flight Recorder, VisualVM) can be used to analyze application performance.

## 3. PR Instructions

*   **Commit Message/PR Title Format:**
    All commits must include a `Signed-off-by` trailer at the end of each commit message to indicate agreement with the Developer Certificate of Origin (DCO). This is a mandatory project requirement. For example:
    ```
    Fix: Short descriptive message

    Longer explanation if needed.

    Signed-off-by: Your Name <your.email@example.com>
    ```

*   **Pre-commit Checks:**
    Before submitting a pull request, ensure all local checks pass to avoid CI failures:
    *   Run all tests, code style, and formatting checks:
        ```bash
        ./mvnw verify
        ```
        Or for Gradle:
        ```bash
        ./gradlew build
        ```

*   **Branching Strategy:**
    The project typically follows a feature branching workflow. Create a new branch from `main` for your changes (e.g., `git checkout -b feature/my-new-feature`), implement your changes, and then submit a pull request targeting the `main` branch.

*   **Code Review Expectations:**
    Be prepared for constructive feedback during the code review process. Address comments, iterate on your changes, and ensure the code quality and functionality meet project standards. The [issue tracker](https://github.com/spring-projects/spring-petclinic/issues) is the preferred channel for bug reports, feature requests, and submitting pull requests.

*   **DCO/Signing Commits:**
    As mentioned above, all commits *must* include a `Signed-off-by` line. Refer to the `README.md` for more details, including a link to "Hello DCO, Goodbye CLA: Simplifying Contributions to Spring."

## 4. Automated Agents & CI/CD Pipelines

*   **Pipeline Details:**
    *   **Name:** `Java CI with Maven` (for Maven builds) and `Java CI with Gradle` (for Gradle builds).
    *   **Triggers:** Both pipelines are triggered on `push` and `pull_request` events targeting the `main` branch.
    *   **Stages (Maven example - `maven-build.yml`):**
        1.  `actions/checkout@v4`: Checks out the repository.
        2.  `actions/setup-java@v4`: Sets up JDK 17 with Maven caching.
        3.  `Build with Maven Wrapper`: Executes `./mvnw -B verify`, which builds the project, runs tests, and performs validation steps.
    *   **Stages (Gradle example - `gradle-build.yml`):**
        1.  `actions/checkout@v4`: Checks out the repository.
        2.  `actions/setup-java@v4`: Sets up JDK 17 with Maven caching (though used for Gradle, the cache key might be Maven).
        3.  `gradle/actions/setup-gradle@v4`: Sets up Gradle.
        4.  `Build with Gradle`: Executes `./gradlew build`, which builds the project and runs tests.

*   **Code Quality Bots/Tools:**
    *   **Checkstyle:** Enforced by `maven-checkstyle-plugin` using `src/checkstyle/nohttp-checkstyle.xml` during the Maven build.
    *   **Spring JavaFormat:** `spring-javaformat-maven-plugin` ensures consistent code formatting. This is part of the `validate` phase in Maven.
    *   **JaCoCo:** `jacoco-maven-plugin` is configured to generate code coverage reports during the `prepare-package` phase in Maven.

*   **Security Scanners:**
    The `maven-enforcer-plugin` ensures the correct Java version is used. No explicit third-party security vulnerability scanners (like Snyk, Dependabot) are directly evident in the provided `pom.xml` or workflows, but they could be integrated.

*   **Release Automation:**
    The `spring-boot-maven-plugin` includes a `build-info` goal to generate build-related information and can be used to `build-image` (container image). The `git-commit-id-maven-plugin` is used to embed Git commit information into the build. The `cyclonedx-maven-plugin` generates an SBOM (Software Bill of Materials).

*   **Documentation Bots:**
    No explicit automated documentation generation tools or bots were identified within the provided context.

*   **Monitoring & Alerting Integrations:**
    The project includes `spring-boot-starter-actuator`, which exposes various production-ready monitoring and management endpoints. While direct integration with specific monitoring systems (e.g., Prometheus, Grafana) is not configured in the provided files, Actuator provides the foundation for such integrations.

## 5. Additional Guidelines

*   **Security Best Practices:**
    When contributing, adhere to secure coding principles. Be mindful of potential vulnerabilities (e.g., injection flaws, sensitive data exposure). Ensure any new dependencies are vetted for security issues.

*   **Accessibility Guidelines:**
    While not explicitly outlined in the `README.md`, strive to develop user interfaces that are accessible to all users, following common web accessibility standards.

*   **Localization/Internationalization:**
    The application supports internationalization, with message properties files located in `src/main/resources/messages/` (e.g., `messages_de.properties`, `messages_es.properties`). If adding new translatable text or a new language, these files should be updated.

*   **Common Pitfalls/Troubleshooting:**
    *   **Database Connectivity:** Issues often arise from incorrect database configurations. Check `application.properties` and ensure your local database (MySQL/PostgreSQL via Docker Compose or local installation) is running and accessible.
    *   **Java Version:** Ensure you are using Java 17 or newer, as enforced by the `maven-enforcer-plugin`.

*   **Contributing to Agents:**
    If you identify opportunities to improve existing automated agents (CI workflows, code quality checks) or propose new ones, discuss them with the maintainers via the [issue tracker](https://github.com/spring-projects/spring-petclinic/issues). Contributions to enhance our automation and development experience are highly valued.

AI generated AGENTS.md

Generate your own

In true fashion, let your AI agent generate the AGENT.md file for you with this prompt, tweak it to your liking:

Please generate an `AGENTS.md` file for this repository. This file should serve as a comprehensive practical guide for any human or automated "agent" (developer, CI system, bot) interacting with the codebase.

The `AGENTS.md` should be structured with the following sections, extracting specific commands, tools, and best practices from the repository's configuration files (e.g., `package.json`, `pom.xml`, `build.gradle`, `.github/workflows/`, `tsconfig.json`, `eslint.config.js`, `vite.config.js`, `jest.config.js`, `vitest.config.ts`, `turbo.json`, etc.) or making reasonable inferences based on common project setups:

## 1. Dev Environment Tips

*   **Project Setup:** Instructions on how to get the project running locally (e.g., `npm install`, `pnpm install`, `mvn install`, `gradle build`).
*   **Local Dependencies:** How to install or manage specific local services (databases, message queues, external APIs) needed for development, potentially with Docker Compose instructions.
*   **Workspace Navigation:** Tips for navigating a monorepo or multi-module project if applicable (e.g., `pnpm dlx turbo run where <project_name>`, `ls -R`).
*   **New Project Creation:** If relevant, provide commands or guidelines for spinning up new modules/packages within the existing repository structure.
*   **Tooling Integration:** Mention how specific tools (e.g., Vite, ESLint, TypeScript) are integrated and how to ensure they recognize new packages.
*   **IDE/Editor Configuration:** Recommended plugins, settings, and workspace configurations for popular IDEs.

## 2. Testing Instructions

*   **CI/CD Overview:** Briefly describe where to find the project's continuous integration plans (e.g., `.github/workflows/`).
*   **Running All Tests:** Provide the command(s) to execute the full test suite for a specific project or the entire repository (e.g., `pnpm turbo run test --filter <project_name>`, `pnpm test`, `mvn test`, `gradle test`).
*   **Running Specific Tests:** Instructions on how to run individual tests or test suites (e.g., `pnpm vitest run -t "<test name>"`, `jest <test_file>`, `mvn test -Dtest=<test_name>`).
*   **Linting and Type Checking:** Commands and advice for ensuring code quality and type correctness (e.g., `pnpm lint --filter <project_name>`, `tsc --noEmit`).
*   **Test Maintenance:** Emphasize the importance of adding or updating tests for any code changes.
*   **Debugging Guides:** How to debug locally (e.g., attaching a debugger, common debugging tools).
*   **Performance Tuning:** Tips for profiling and optimizing code.

## 3. PR Instructions

*   **Commit Message/PR Title Format:** Guidelines for structuring commit messages or pull request titles.
*   **Pre-commit Checks:** List essential commands to run before submitting a pull request (e.g., `pnpm lint`, `pnpm test`).
*   **Branching Strategy:** If applicable, brief notes on the project's branching model.
*   **Code Review Expectations:** What to look for during code reviews and how to provide constructive feedback.
*   **DCO/Signing Commits:** Instructions if Developer Certificate of Origin or signed commits are required.

## 4. Automated Agents & CI/CD Pipelines

*   **Pipeline Details:** Specific stages and their purpose (e.g., build, test, deploy, security scan), triggering mechanisms, environment variables, and notification mechanisms.
*   **Code Quality Bots/Tools:** Linters, formatters, and static analyzers used (e.g., ESLint, Prettier, Checkstyle, SonarQube) – how they're enforced, how to run, and how to fix issues.
*   **Security Scanners:** Dependency scanners (e.g., Dependabot, Snyk) and vulnerability scanners – what they check, how to interpret results.
*   **Release Automation:** How releases are managed (e.g., semantic-release, versioning strategy) and deployment agents/scripts.
*   **Documentation Bots:** Tools that generate API docs, update `CHANGELOG.md`, etc.
*   **Monitoring & Alerting Integrations:** How the project integrates with monitoring systems (e.g., Prometheus, Grafana) and what alerts are configured.

## 5. Additional Guidelines

*   **Security Best Practices:** Guidelines for secure coding, handling secrets, and preventing common vulnerabilities.
*   **Accessibility Guidelines:** How to ensure accessibility standards are met in development.
*   **Localization/Internationalization:** How to add new languages or contribute to existing translations.
*   **Common Pitfalls/Troubleshooting:** A FAQ of common issues and their solutions.
*   **Contributing to Agents:** Instructions on how to propose new automated agents or modify existing ones.

Aim for clarity, conciseness, and actionable advice. Adapt the commands and tool names to match the technologies actually used in the repository. If a section is not applicable or information cannot be directly inferred, state that.

AI generated AGENTS.md creation prompt

Adding additional conventions to AGENTS.md

Lots of similar conventions already exist, which may help your AI agents even further:

1. README.md
2. CONTRIBUTING.md
3. CHANGELOG.md
4. CODE_OF_CONDUCT.md
5. SECURITY.md
6. RELEASES.md
7. GLOSSARY.md
8. LICENSE.md

Update your AGENT.md to reference them as needed, for example:

## Related Documentation and Knowledge Base

 For a deeper understanding of various aspects of this project, please consult the following documents:
   
 *   **[README.md](README.md):** Project overview, core features, and quick start.     
 *   **[GLOSSARY.md](GLOSSARY.md):** Definitions of project-specific terms.
 *   **[DEVELOPMENT.md](DEVELOPMENT.md):** In-depth technical guide for local development and debugging.