Guides · C++
How to write an AGENTS.md for a C++ project
Measured across 41 of the most-starred C++ repositories on GitHub. The median scores 42 out of 100.
What C++ repos get wrong
C++ scores lowest of the languages measured, and none of it is about code quality. There is no standard package manager, so 78% commit nothing that pins dependencies. There is no conventional test command, so the same share leave an agent with no way to verify a change. And 88% pin no toolchain version, which in C++ means an agent can hit template errors that have nothing to do with its edit. This is the ecosystem where writing the commands down changes the most.
Most common failures
share of 41 C++ repositories scoring zero on each
Lower is better here. These are failures, not scores.
A working example
Commands first, conventions second, none of the persuasion a README carries. The test is whether a capable stranger could make a small change and verify it using only this file.
Save it at the root of the repository
as AGENTS.md. Tool-specific files like CLAUDE.md or .cursorrules still work, but
AGENTS.md is the one every tool reads.
# AGENTS.md ## Setup cmake -B build -DCMAKE_BUILD_TYPE=Debug cmake --build build -j ## Commands ctest --test-dir build # full suite, must pass before any commit cmake --build build --target format ## Conventions - Headers in include/, sources in src/, tests in tests/. - Anything in third_party/ is vendored. Do not edit it. ## Gotchas - Requires a C++20 compiler. Older toolchains fail with confusing template errors.
The two lines that matter most
If you write nothing else, write these. An agent that cannot install the project cannot start, and one that cannot run the tests cannot tell whether it broke something.
# installcmake -B build && cmake --build build# verifyctest --test-dir build
Have it drafted instead
Point the tool at a repository and it writes the file from what is already there, rather than from a template.
For private code, the same rubric runs on your machine and sends nothing anywhere:
$ npx agentreadme --write-agents
Other ecosystems