MONGOCRYPT-955 add AGENTS.md - #1211
Conversation
connorsmacd
left a comment
connorsmacd
left a comment
There was a problem hiding this comment.
LGTM with some minor feedback. Erring on the side of approving this now since I will be away until next week.
Co-authored-by: Connor MacDonald <connor.macdonald@mongodb.com>
vector-of-bool
left a comment
vector-of-bool
left a comment
There was a problem hiding this comment.
Sorry, thought I submitted my pending comments a few days ago. A few comments regarding redundant information that the model already knows.
There was a problem hiding this comment.
Can the text in this file be reflowed to a column limit? Not important but aides readability across both very wide and very narrow screens.
There was a problem hiding this comment.
I am slightly averse to hard-wrapping I think I have a historical peeve of my small text changes in the spec repo creating big diffs after rewrapping. I expect that is less of an issue with modern GitHub highlighting content changes.
I am admittedly biased towards my own workflow with VS Code. VS Code does not appear to have built-in support for hard wrapping. But I can enable soft wrapping in VS Code with user settings:
"[markdown]": {
"editor.wordWrap": "wordWrapColumn",
"editor.wordWrapColumn": 120,
"editor.rulers": [
120
],
},
With that said, would hard wrapping still seem preferable? I am open to it if it may help with reading (though I might poke you for recommendations on a wrapping tool).
There was a problem hiding this comment.
Soft wrapping may be a useful compromise.
The wrapping happens automatically for me because I have an extension, "Reflow Markdown", installed that formats markdown files on save. It may not be the optimal formatter though, and it can garble some constructs like admonitions. May be better to adopt a proper tool like mdformat in the future. I'd say leave it for now and we can discuss reformatting of everything altogether at some future date.
| > [!IMPORTANT] | ||
| > For multi-configuration generators (e.g. "Visual Studio *", "Ninja Multi-Config", etc.), use `--config <config>` during the build, install, and test steps instead of `CMAKE_BUILD_TYPE=<config>`. | ||
| > The `CMAKE_BUILD_TYPE` option will be ignored by the configuration step. | ||
| > Only use `CMAKE_BUILD_TYPE` with single-configuration generators (e.g. Makefile Generators, Ninja, etc.). |
There was a problem hiding this comment.
I believe that models will have information like this baked-in. e.g. I've never needed to guide an LLM on how multi-config generators work, it just knows.
I think the only thing that needs to be specified is the configuration parameters that are specific to this project.
There was a problem hiding this comment.
I originally erred towards consistency with the C and C++ driver AGENTS.md, but I tend to agree. I expect CMake instructions common to any CMake project are unlikely to help an LLM. I removed some CMake notes, and left notes about preferences (e.g. using cmake-build) or project specific options.
| - `-G <generator-name>`: specify a build system generator (e.g. `Ninja`). | ||
| - `-D CMAKE_PREFIX_PATH:PATH=<prefix>`: installation prefixes to search with `find_*()` (e.g. an installed libbson with `USE_SHARED_LIBBSON=ON`, or OpenSSL). | ||
| - `-D CMAKE_INSTALL_PREFIX:PATH=<install-prefix>`: install directory used by `install()`. Use `cmake-build/install/` when system modification is undesirable or disallowed by the user. | ||
| - `-D CMAKE_BUILD_TYPE:STRING=<config>`: build type on single-configuration generators. |
There was a problem hiding this comment.
Same as comment above
| > [!IMPORTANT] | ||
| > For multi-configuration generators, the executable appears under a `<config>/` subdirectory (e.g. `cmake-build/Debug/test-mongocrypt`). | ||
|
|
||
| A few tests need a real crypt_shared library; download one with the `mongodl.py` script from drivers-evergreen-tools: <https://github.com/mongodb-labs/drivers-evergreen-tools/blob/master/.evergreen/mongodl.py> |
There was a problem hiding this comment.
I have a user skill for mongodl that may be useful for sharing across projects in the org, but I don't know how to do that.
There was a problem hiding this comment.
I have not tried it, but https://github.com/10gen/agent-skills might be an option for an org-wide skill.
3 participants
Summary
Add an AGENTS.md for libmongocrypt.
As a drive-by: fix formatting steps CONTRIBUTING.md to refer to
uv(notpipx).Background & Motivation
Organization of build steps was inspired by mongodb/mongo-cxx-driver#1636.
Evaluating
I used Claude to draft an AGENTS.md evaluator. It tested responses to read-only prompts before / after adding AGENTS.md. The draft is in this branch. Response correctness did not change much. But token usage reduced:
The reduced token usage gave me some confidence the AGENTS.md helped lower the need to explore. But I was not confident this evaluator was valuable enough to add to this PR. And I did not want to continue adding scope to this task.