AGENTS.md standardization for all DBX Repositories

XMLWordPrintableJSON

    • Type: Improvement
    • Resolution: Unresolved
    • Priority: Major - P3
    • None
    • Component/s: AI/ML
    • None
    • ODM Changes Needed
    • Hide

      Summary of necessary driver changes

      1. Create AGENTS.md

      Create a file called AGENTS.md in the root each of your actively maintained Git repositories. Consider:

      • Keep it short–it uses up agentic context
      • Collaborative with agents–ask the agent what is/is not useful
      • Use your human expertise and experience to keep it short and relevant
      • Iterate after a session with the agent, especially if the agent struggled

      See the discussion in https://jira.mongodb.org/browse/DRIVERS-3428 for more information, or reach out to the AI champions.

      Here’s a template with section headers that you can start from:

      # AGENTS.md - <Project name>

## Overview
Short description of what the project is for.

## Tech Stack
Helps the agents understand the tech stack. Let the agent tell you what is and is not useful here–it’s often non-obvious.

## Project Structure
Help the agent find different parts of the project–important for reducing token usage when the agent is finding this.

## <Custom>
Include special instructions based on what the agent had issues with–see C# example below.

## Commands
Helps the agents run commands to build, test, etc. Again, let the agent tell you what is and is not useful here–it’s often non-obvious.

## Testing
Specific details needed to run tests. 

## Commit and PR Conventions
Help the agent understand team conventions

      Here’s an example for the C# driver. The specifics in each section are likely to differ significantly per project.

      # AGENTS.md - CSharpDriver

## Overview
The C# driver for MongoDB.

## Tech Stack
- .NET library projects producing NuGet packages
- Multi-targeted to various .NET versions from .NET Framework 4.7.2 up
- xUnit + FluentAssertions for testing

## Project Structure
- `src/MongoDB.Bson/` - BSON for MongoDB
- `src/MongoDB.Driver/` - C# driver for MongoDB
- `src/MongoDB.Driver.Encryption/` - Client encryption (CSFLE with KMS).
- `src/MongoDB.Driver.Authentication.AWS/` - AWS IAM authentication
- `tests/MongoDB.Driver.Tests/` - Main C# driver tests
- `tests/MongoDB.Bson.Tests/` - BSON handling tests
- `tests/*/TestHelpers` - Common test utilities
- `tests/*` - Specialized tests; less common
- `tests/MongoDB.Driver.Tests/Specifications/` are JSON-driven tests using a common runner.

## Editing
- Be careful to preserve file BOMs.

## Commands
- Build: `dotnet build CSharpDriver.sln`
- Run all tests: `dotnet test tests/MongoDB.Driver.Tests/MongoDB.Driver.Tests.csproj -f net10.0`
- Run a single test class: `dotnet test tests/MongoDB.Driver.Tests/MongoDB.Driver.Tests.csproj -f net10.0 --filter "FullyQualifiedName~ClassName"`

## Testing
- Tests cannot be run in parallel.
- A MongoDB connection is always available locally, so "integration" tests can be run as well as unit tests. Some test suites also require additional environment variables — if you need to run those tests and the variables are not set, stop and tell the user which variables are needed rather than working around it.

| Feature area | Required environment variables |
|---|---|
| Atlas Search | `ATLAS_SEARCH_TESTS_ENABLED`, `ATLAS_SEARCH_URI` |
| Atlas Search index helpers | `ATLAS_SEARCH_INDEX_HELPERS_TESTS_ENABLED`, `ATLAS_SEARCH_URI` |
| CSFLE / auto-encryption | `CRYPT_SHARED_LIB_PATH` |
| CSFLE with KMS mock servers | `KMS_MOCK_SERVERS_ENABLED` |
| CSFLE with AWS KMS | `CSFLE_AWS_TEMPORARY_CREDS_ENABLED` |
| CSFLE with Azure KMS | `CSFLE_AZURE_KMS_TESTS_ENABLED` |
| CSFLE with GCP KMS | `CSFLE_GCP_KMS_TESTS_ENABLED` |
| AWS authentication | `AWS_TESTS_ENABLED` |
| GSSAPI / Kerberos | `GSSAPI_TESTS_ENABLED`, `AUTH_HOST`, `AUTH_GSSAPI` |
| OIDC authentication | `OIDC_ENV` |
| X.509 authentication | `MONGO_X509_CLIENT_CERTIFICATE_PATH`, `MONGO_X509_CLIENT_CERTIFICATE_PASSWORD` |
| PLAIN authentication | `PLAIN_AUTH_TESTS_ENABLED` |
| SOCKS5 proxy | `SOCKS5_PROXY_SERVERS_ENABLED` |

## Commit and PR Conventions

- The first commit message and the PR message start with a JIRA number: `CSHARP-1234: Description`
- The branch name will usually match the JIRA number: `CSHARP-1234`

      2. Create CLAUDE.md

      Anthropic has instructed Claude not to read the AGENTS.md directly. Instead it always looks for CLAUDE.md. However, CLAUDE.md can include any of file, so use this to direct claude to the agents file:

      @AGENTS.md

      Acceptance criteria

      Each actively maintained repo contains an appropriate AGENTS.md file, and a CLAUDE.md directing Claude to the agents file.

      Show
      Summary of necessary driver changes 1. Create AGENTS.md Create a file called AGENTS.md in the root each of your actively maintained Git repositories. Consider: Keep it short–it uses up agentic context Collaborative with agents–ask the agent what is/is not useful Use your human expertise and experience to keep it short and relevant Iterate after a session with the agent, especially if the agent struggled See the discussion in https://jira.mongodb.org/browse/DRIVERS-3428 for more information, or reach out to the AI champions. Here’s a template with section headers that you can start from: # AGENTS.md - <Project name> ## Overview Short description of what the project is for . ## Tech Stack Helps the agents understand the tech stack. Let the agent tell you what is and is not useful here–it’s often non-obvious. ## Project Structure Help the agent find different parts of the project–important for reducing token usage when the agent is finding this . ## <Custom> Include special instructions based on what the agent had issues with–see C# example below. ## Commands Helps the agents run commands to build, test, etc. Again, let the agent tell you what is and is not useful here–it’s often non-obvious. ## Testing Specific details needed to run tests. ## Commit and PR Conventions Help the agent understand team conventions Here’s an example for the C# driver. The specifics in each section are likely to differ significantly per project. # AGENTS.md - CSharpDriver ## Overview The C# driver for MongoDB. ## Tech Stack - .NET library projects producing NuGet packages - Multi-targeted to various .NET versions from .NET Framework 4.7.2 up - xUnit + FluentAssertions for testing ## Project Structure - `src/MongoDB.Bson/` - BSON for MongoDB - `src/MongoDB.Driver/` - C# driver for MongoDB - `src/MongoDB.Driver.Encryption/` - Client encryption (CSFLE with KMS). - `src/MongoDB.Driver.Authentication.AWS/` - AWS IAM authentication - `tests/MongoDB.Driver.Tests/` - Main C# driver tests - `tests/MongoDB.Bson.Tests/` - BSON handling tests - `tests/*/TestHelpers` - Common test utilities - `tests/*` - Specialized tests; less common - `tests/MongoDB.Driver.Tests/Specifications/` are JSON-driven tests using a common runner. ## Editing - Be careful to preserve file BOMs. ## Commands - Build: `dotnet build CSharpDriver.sln` - Run all tests: `dotnet test tests/MongoDB.Driver.Tests/MongoDB.Driver.Tests.csproj -f net10.0` - Run a single test class: `dotnet test tests/MongoDB.Driver.Tests/MongoDB.Driver.Tests.csproj -f net10.0 --filter "FullyQualifiedName~ClassName" ` ## Testing - Tests cannot be run in parallel. - A MongoDB connection is always available locally, so "integration" tests can be run as well as unit tests. Some test suites also require additional environment variables — if you need to run those tests and the variables are not set, stop and tell the user which variables are needed rather than working around it. | Feature area | Required environment variables | |---|---| | Atlas Search | `ATLAS_SEARCH_TESTS_ENABLED`, `ATLAS_SEARCH_URI` | | Atlas Search index helpers | `ATLAS_SEARCH_INDEX_HELPERS_TESTS_ENABLED`, `ATLAS_SEARCH_URI` | | CSFLE / auto-encryption | `CRYPT_SHARED_LIB_PATH` | | CSFLE with KMS mock servers | `KMS_MOCK_SERVERS_ENABLED` | | CSFLE with AWS KMS | `CSFLE_AWS_TEMPORARY_CREDS_ENABLED` | | CSFLE with Azure KMS | `CSFLE_AZURE_KMS_TESTS_ENABLED` | | CSFLE with GCP KMS | `CSFLE_GCP_KMS_TESTS_ENABLED` | | AWS authentication | `AWS_TESTS_ENABLED` | | GSSAPI / Kerberos | `GSSAPI_TESTS_ENABLED`, `AUTH_HOST`, `AUTH_GSSAPI` | | OIDC authentication | `OIDC_ENV` | | X.509 authentication | `MONGO_X509_CLIENT_CERTIFICATE_PATH`, `MONGO_X509_CLIENT_CERTIFICATE_PASSWORD` | | PLAIN authentication | `PLAIN_AUTH_TESTS_ENABLED` | | SOCKS5 proxy | `SOCKS5_PROXY_SERVERS_ENABLED` | ## Commit and PR Conventions - The first commit message and the PR message start with a JIRA number: `CSHARP-1234: Description` - The branch name will usually match the JIRA number: `CSHARP-1234` 2. Create CLAUDE.md Anthropic has instructed Claude not to read the AGENTS.md directly. Instead it always looks for CLAUDE.md. However, CLAUDE.md can include any of file, so use this to direct claude to the agents file: @AGENTS.md Acceptance criteria Each actively maintained repo contains an appropriate AGENTS.md file, and a CLAUDE.md directing Claude to the agents file.
    • $i18n.getText("admin.common.words.hide")
      Key Status/Resolution FixVersion
      CDRIVER-6276 Needs Triage
      CXX-3440 In Code Review
      CSHARP-5943 Fixed 3.9.0
      GODRIVER-3845 Needs Triage
      JAVA-6146 Needs Triage
      NODE-7494 Needs Triage
      PYTHON-5768 In Code Review
      PHPLIB-1815 Needs Triage
      RUBY-3795 Needs Triage
      RUST-2388 Needs Triage
      INTPYTHON-939 In Code Review
      MONGOID-5929 Blocked
      PHPORM-478 Blocked
      $i18n.getText("admin.common.words.show")
      #scriptField, #scriptField *{ border: 1px solid black; } #scriptField{ border-collapse: collapse; } #scriptField td { text-align: center; /* Center-align text in table cells */ } #scriptField td.key { text-align: left; /* Left-align text in the Key column */ } #scriptField a { text-decoration: none; /* Remove underlines from links */ border: none; /* Remove border from links */ } /* Add green background color to cells with FixVersion */ #scriptField td.hasFixVersion { background-color: #00FF00; /* Green color code */ } #scriptField td.willNotDo { background-color: #FF0000; /* Red color code */ } /* Center-align the first row headers */ #scriptField th { text-align: center; } Key Status/Resolution FixVersion CDRIVER-6276 Needs Triage CXX-3440 In Code Review CSHARP-5943 Fixed 3.9.0 GODRIVER-3845 Needs Triage JAVA-6146 Needs Triage NODE-7494 Needs Triage PYTHON-5768 In Code Review PHPLIB-1815 Needs Triage RUBY-3795 Needs Triage RUST-2388 Needs Triage INTPYTHON-939 In Code Review MONGOID-5929 Blocked PHPORM-478 Blocked

      Teams are introducing AGENTS.md files, which give Claude Code and other agents consistent, guidance for repos or sections of the codebase. We need generalized guidance for how to best set up such files across all drivers and ODM repos. This does not imply one global file, or a set of fixed requirements that each project is required to meet, but rather an evolving set of best-practices. Individual teams are free to selectively implement those best practices into their own repositories. The guidance should include information on what should be present, how we validate what should be added, how we remove items and validate their removal.

      Anthropic documents AGENTS.md as the place to capture persistent project context such as coding standards, workflow rules, architectural decisions, build/test commands, repository etiquette, and non-obvious gotchas, especially the information Claude cannot reliably infer from code alone. Extensive documentation must be balanced against the need to avoid extensive context, as well as redundant or even contradictory instructions.

      Standardizing this across repositories would improve the quality and consistency of AI-assisted contributions by reducing repeated prompt setup, making repo conventions explicit, and ensuring shared instructions travel with the codebase in source control. Because project AGENTS.md files are team-shared and versioned in git, they can become a durable layer of operational knowledge that helps onboard contributors faster and keeps Agents (claude / copilot etal) aligned with each repository’s expectations over time.

      Note that this should apply to any DBX repository such as:

      • specifications
      • drivers
      • ODMs
      • libraries
      • tools

      Why AGENTS.md over CLAUDE.md: See: https://wiki.corp.mongodb.com/spaces/MMS/pages/499158370/Making+a+Repo+Agent+Ready

      We want this process to be iterative, so after this is ready for teams to implement, file a follow-up DRIVERS ticket for Q4 to revisit and reassess.

            Assignee:
            Arthur Vickers
            Reporter:
            Alex Bevilacqua
            Votes:
            0 Vote for this issue
            Watchers:
            7 Start watching this issue

              Created:
              Updated: