Added AGENTS.md instructions and SKILLS.md

[rozza]

Initial implementation of AGENTS.md and SKILLS.md for the MongoDB Java Driver Repo

JAVA-6143

[rozza]

Followed general guidelines from: https://wiki.corp.mongodb.com/spaces/MMS/pages/499158370/Making+a+Repo+Agent+Ready
Also used glean to review the PR and provide suggested feedback.

AGENTS.md: The Constitution

AGENTS.md is a markdown file at the root of the repository. Every AI agent — Augment, Claude Code, Cursor — reads it automatically at the start of every session.

This means every token in AGENTS.md is loaded into the agent's context window every single time. The context window has a budget. Frontier models reliably follow ~150-200 instructions, and tool system prompts consume a significant share before your AGENTS.md even loads. Overstuffing AGENTS.md degrades the quality of all instructions — not selectively. Brevity is load-bearing.

What belongs in AGENTS.md

Core development principles (style, testing, safety rules)
Architecture overview (tech stack, build system)
Conventions that apply to every task, every session

What does NOT belong in AGENTS.md

Detailed workflows for specific tasks (use a skill)
Reference documentation (use a skill with a references/ directory)
Long examples or templates (use a skill)
If the information is only relevant to 1 in 10 sessions, it should not be in AGENTS.md. It should be a skill.

[Copilot]

Pull request overview

Copilot reviewed 52 out of 53 changed files in this pull request and generated 5 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ajcvickers]

We had a bit of discussion about this in the AI/ML-sync meeting yesterday. My approach has been to use very minimal agents files (for Junie, Augie, and Claude) because I don't think it is clear what is:

• Useful
• Benign
• Harmful

I think we've all seen harmful changes--for example, telling it about tests and then having the agent get caught up attempting to run them all the time.

Things that are not harmful but also not very useful (the benign category) can end up being accidentally harmful by taking up context space and thereby forcing something important out.

We can discuss these things on a case-by-case basis, but I think that means starting small and understanding the impacts of the changes made.

Another approach is for each platform team to do something different and then we all compare notes later.

[katcharov]

Partial review. Agree with @ajcvickers points above. There is a fair bit of content here, and I am not sure how we can validate it.

[katcharov]

Could you run Claude to review this PR, asking something like "Confirm that this PR follows best practices for creating CLAUDE.md files. Evaluate it personally, confirming that various items are generally necessary. Also evaluate it based on official and authoritative sources (official Claude documentation, online posts that are corroborated AND experimentally verified, and posts from recognized experts; but not: blog posts, social media speculations, and other uncorroborated sources. Is anything unnecessary, and easily discoverable? Is anything crucial missing?"

Independently, have it doublecheck correctness until it stops finding issues.

Please also include info about how these files were generated, and AI-reviewed, including results of the above. (This is just the typical AI usage, effectiveness comment in the description).

[katcharov]

I am not sure how to interpret this or check if a model has actually applied these principles. For example, the first one, "deep modules", seems to be a matter of intuition. In practice, I'm not sure how we would choose one approach vs another, or what would make a given approach have a "powerful implementation".

[katcharov]

I don't think a model should ever be applying some of these. I also don't know what "Libraries should not depend on these" means? Our users can depend on Beta, but we can change it.

[katcharov]

I don't understand how a model would expose these as public APIs?

[katcharov]

I ran only this skill through Claude, and I got this:

What's already known to models:
  - The design principles section is essentially a summary of Ousterhout's A
  Philosophy of Software Design. Any capable model already knows these
  concepts and would apply them naturally. This section adds little value.
  - "Search before implementing" is generic good practice, not
  project-specific guidance.

  What's genuinely useful (project-specific):
  - The stability annotations (@Alpha, @Beta, @Evolving, @Sealed) — these are
   driver-specific and not inferable without reading the source.
  - The com.mongodb.internal.* / org.bson.internal.* rule.
  - The concrete pattern examples (Filters.eq(),
  MongoClientSettings.builder()).
  - The package-info.java requirement.

  What's missing that would actually help:
  - How to choose which annotation for new API — when should something be
  @Alpha vs @Beta vs @Evolving? What's the promotion path?
  - Sync/async API mirroring — does every sync method need an async
  counterpart? How are they kept in sync?
  - Nullability conventions — does the driver use @Nullable/@NonNull? What's
  the stance on null parameters?
  - The module structure — what goes in driver-core vs driver-sync vs
  driver-reactive-streams? Where should new API land?
  - Default methods on interfaces — the strategy for evolving @Evolving
  interfaces without breaking implementors.
  - Concrete examples of "wrong" API decisions — models learn more from
  "don't do X because Y happened" than from abstract principles.

  Bottom line: The skill is ~30% useful as-is. The design principles section
  could be dropped entirely without loss. The project-specific rules are
  valuable but thin. The biggest improvement would be replacing the generic
  principles with concrete, driver-specific guidance on the missing items
  above — things a model can't infer from first principles.

I am uncertain that what is marked "useful" above will be in practice (see other comments).

[katcharov]

What is this pattern based on?

I tried to look up how it works, and info is scarce. As of 9 months ago, this convention did not imply that the file would be embedded in the other file. See comments in this post, someone experimented and confirmed that Claude sometimes only conditionally reads these files. I believe this means that:

1. We don't actually have a guarantee that a referenced file will be read, and the conditions under which it is read are unclear
2. Updating the referenced file while a session is in-flight will not cause an immediate context update, which makes tuning difficult
3. There will be an additional step (time, tokens) for reading this file

I don't think we should use this pattern if the above is true.