CXX-3440 Add initial AGENTS.md with updated coding_guidelines.md

[eramongodb]

Resolves CXX-3440. Adds an initial AGENTS.md (+ CLAUDE.md) to inform AI agents how to use the mongo-cxx-driver project.

Note

Claude Code 2.1.132 with Sonnet 4.6 200K "High Thinking" mode was used for agent behavior described below.

---

The "baseline" commit used for the changes in this PR is 9b0c132 (r4.3.0). The changes were subsequently rebased onto master after validating AI agent behavior (with AGENTS.md) against the baseline commit (without AGENTS.md). A "clean repository" -- a detached clone under /tmp/mongo-cxx-driver with no remotes, Claude Code memories, or commits (to minimize extraneous information to Claude Code's initial context) -- was used to validate that changes had observable and significant changes in agent behavior. Nevertheless, behavior and results varied greatly across reiterations even with the same initial state and commands (long way to go towards AI agent reproducibility).

Given the following prompt:

Describe this project. Do not explore anything. Use only the current context.

the response on the baseline commit was:

This is the MongoDB C++ Driver (mongo-cxx-driver), currently at version 4.3.0.

It provides two libraries:

• mongocxx — the MongoDB client driver for C++
• bsoncxx — a C++ library for BSON (Binary JSON) document handling

From the recent commits, active work includes URI options (e.g., maxAdaptiveRetries), BSON vector iterator fixes, updating the underlying C driver dependency (to 2.3.0), and deprecating older toolchain support (VS 2015).

This suggests Claude Code includes a bit of git history as part of its session initialization context and natively understands concepts such as MongoDB clients/servers and BSON documents.

---

The initial CLAUDE.md was generated by running the simple /init command as-is. Once the CLAUDE.md file was present, the same "Describe this project" prompt above (using a clean repository) resulted in the following response:

This is the mongo-cxx-driver — the official MongoDB C++ driver, maintained by MongoDB.

It provides two libraries:

• bsoncxx — a standalone BSON document library that wraps libbson from the C driver. No MongoDB dependency required.
• mongocxx — the MongoDB C++ driver itself, wrapping libmongoc and depending on bsoncxx.

Key characteristics:

• Built with CMake; the C driver (mongoc) is fetched automatically via FetchContent
• Tests use Catch2 and are run via ctest
• Minimum C++ standard is C++11
• Has two ABI namespaces: v_noabi (unstable, most existing code) and v1 (stable, newer additions)
• Tracks JIRA tickets in commit/PR titles (e.g., CXX-3439)

Recent work (from git log) includes adding maxAdaptiveRetries URI option, fixing a subscript operator on bsoncxx::vector::iterators, updating the C driver to 2.3.0, and deprecating VS 2015 support.

Notably, the result now includes build system details, issue tracking conventions, and some architecture design details.

---

The initial CLAUDE.md is renamed to AGENTS.md and Claude Code specific wording replaced with "AI coding agents" to conform to the AGENTS.md protocol. Because Claude Code still requires a CLAUDE.md file, the AGENTS.md file must be "imported" to avoid redundancy.

Once this initial AGENTS.md established a basic content structure, a combination of manual edits and Claude Code feedback were used to refine their contents. AI agent behavior was validated by executing "user simulation" scenarios and validating behavior against test rubrics, such as:

• "Build this project":
  • Does it use C++17 by default?
  • Does it use "RelWithDebInfo" by default for installation? Does it use "Debug" by default for local development and testing?
  • Does it use --config <config> instead of -D CMAKE_BUILD_TYPE=<config> for multi-config generators?
  • Does it ask the user to set CMAKE_PREFIX_PATH to a local MongoDB C Driver installation when FetchContent fails (i.e. due to sandbox restrictions)?
  • Does it consistently use paths specified by the user (e.g. binary directory, install prefix, etc.)?
  • Does it consistently use a custom binary directory (that is not build/) when requested by the user?
• "Install this project":
  • Does it understand default install prefix behavior and potential permissions issues?
  • Does it suggest using build/install/ as a local fallback on failure to install to system directories?
  • Does it understand how to use custom install prefixes when requested by the user?
• "Run tests":
  • Does it know how to enable tests (ENABLE_TESTS=ON) and its requirements (C++14 and newer)?
  • Does it understand where test executables are located (for each library? for the specific test cases requested)?
  • Does it inform the user about required environment variables (e.g. *_TESTS_PATH)?
  • Does it understand how to lookup and use Catch2 command-line flags (i.e. to filter tests by name, tag, section name, etc.)?
• "Implement foo":
  • Does it understand the filesystem structure (e.g. ABI namespaces, include vs. lib vs. test mirroring, etc.)?
  • Does it understand component design patterns (e.g. IWYU, public vs. internal vs. test components, etc.)?
  • Does it understand ABI namespace requirements (e.g. never using v_noabi in v1, always qualifying vN in implementation code, etc.)?
  • Does it understand how to use export macros (e.g. cdecl for functions and SMFs, class-level exports in forward headers only for polymorphic classes, etc.)?
  • Does it know to look at etc/coding_guidelines.md for detailed guidance?
  • Does it know how to format files using helper scripts?

For reference, here are some exerpts from one of the design plan documents used to generate a concrete implementation plan (via the /writing-plans skill provided by the superpowers plugin):

Overview

Each test scenario runs in parallel, each in an isolated local git clone. Each scenario subagent:

1. Executes the canonical scenario task itself, following the current AGENTS.md (baseline)
2. Self-evaluates its own actions against the predefined rubric
3. Patches its local AGENTS.md copy to address any failures
4. Re-runs the task up to 3 more times until all criteria pass or iterations are exhausted

Execution Model

Each scenario subagent is simultaneously the agent-under-test and the evaluator. It performs the task described by the canonical prompt (runs cmake commands, edits source files, etc.), then reviews its own actions against the rubric checklist and scores each criterion pass / fail / not-triggered.

Self-evaluation instructions for subagents: After completing each phase of the task, re-read the rubric for your scenario. For each criterion, determine whether your actions satisfied the pass condition. Be strict: if the criterion was not triggered (e.g. a failure condition never occurred), mark it not-triggered rather than pass.

Scenarios and Rubrics

S3 · Install

Prompt: "Install this project"

Setup: The subagent runs as a normal user without write access to /usr/local. No active permission restriction is needed — the default user environment is sufficient to cause the install to fail with a permissions error.

User simulation: Criteria 3 and 4 require suggesting a fallback and asking the user to confirm. Since there is no real user in an automated test, the subagent plays both roles: it produces the suggestion and confirmation request in its output, then proceeds as if the user confirmed build/install/. Score criteria 3 and 4 based on whether the agent's output contains the suggestion and explicit confirmation request before proceeding.

#	Criterion	Pass condition
1	Initial attempt	Attempts cmake --install build (default /usr/local is acceptable first behavior)
2	Failure recognition	When the install fails due to permissions, reports the failure clearly
3	Fallback suggestion	Suggests build/install/ as a fallback prefix
4	User confirmation	Produces an explicit confirmation request before proceeding (user simulation: proceeds with build/install/)
5	Confirmed install	Runs cmake --install build --prefix build/install (or user-confirmed path)
6	Result reporting	Reports the final install location clearly

This example "S3" scenario (among others like "S1", "S2a", "V1", etc.) tests agent behavior when prompted to "install this project" (deliberately lacking detailed instructions). The rubric is then used to check whether the agent use good defaults, accurate assumptions, and know how to handle errors.

---

The AGENTS.md is deliberately not a comprehensive description of all features and aspects of the project. It's purpose is to establish a set of clear, consistent, and minimal agent-oriented guidelines. The agent can/should be expected to explore further details as-needed for the given task: the AGENTS.md establishes a reliable, effective initial direction with which to start looking. This notably includes details concerning coding guidelines.

Due to the AGENTS.md deferring details concerning architecture, C++ coding style, and others to etc/coding_guildelines.md, this PR necessarily motivated a review and update of its contents for both human-readability and agent-awareness. This review exposed various gaps and inaccuracies, such as the "errc" namespace (leftover from a proposal in #1412 that was rejected in favor of per-class enumerations), the absence of guidance concerning macro guard headers, and inaccurate directory structure trees.

---

With the proposed AGENTS.md + updated coding guidelines, the response to the "Describe this project" prompt now looks as follows:

This is the MongoDB C++ Driver (mongo-cxx-driver), an open-source C++ library for interacting with MongoDB.

It consists of two libraries:

• bsoncxx — A standalone BSON document library wrapping the C driver's bson library. No MongoDB dependency required.
• mongocxx — The full MongoDB C++ driver, wrapping mongoc and depending on bsoncxx.

Key characteristics:

• Built with CMake; depends on the MongoDB C Driver (auto-fetched via FetchContent if not found)
• Minimum C++ standard: C++11; C++17 recommended
• Uses Catch2 for testing
• Exposes both a stable ABI (v1/) and unstable ABI (v_noabi/) for each library
• Formatted with clang-format, linted with clang-tidy, with Python/shell script helpers in etc/

Recent work (from git log) includes adding maxAdaptiveRetries URI option, fixing a subscript operator on bsoncxx::vector::iterators, updating the bundled C driver to 2.3.0, and deprecating VS 2015 support.

[kevinAlbs]

Nicely done. The self-evaluation seems like an effective technique.

As a spot check, I tried a simple prompt before and after this PR:

Add a test to send a "ping" command and expect a successful response. I want to add this test to serve as a spot-check of the test environment. Please compile and run this change.

Both wrote similar tests, but using the new AGENTS.md completed much faster:

• Before: 4m 51s
• After: 2m 34s