Add AGENTS.md governance document for AI Agent projects

[phongphongg]

Summary by CodeRabbit

• Documentation
  • Added a governance document defining AI Agent development standards: modern Java usage, coding/style and testing requirements, explicit nullness rules (JSPECIFY), error-handling and logging expectations, native-image compatibility guidance, legacy API modernization, and version-control & pull-request conventions.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

📝 Walkthrough

Walkthrough

Adds a new governance document AGENTS.md that mandates AI Agent development standards: modern Java (Java 25), checkstyle/structural rules, unit test & coverage requirements, explicit JSpecify nullness compliance, GraalVM native-image compatibility, legacy API modernization, and Git/PR conventions. No code or public API changes.

Changes

Cohort / File(s)	Change Summary
Governance Documentation AGENTS.md	New governance document specifying mandatory AI Agent development standards: Java 25 preference, checkstyle and structural compliance, unit test and coverage mandates, explicit JSpecify nullness rules (including @NullMarked and generics guidance), GraalVM native-image compatibility expectations, legacy API modernization, and Git commit/PR proposal guidelines.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• Verify Java 25 recommendation against CI/tooling compatibility.
• Confirm JSpecify annotation strategy and package-level @NullMarked approach are actionable.
• Ensure checkstyle and GraalVM requirements are feasible for existing modules.
• Validate Git/PR guidance doesn't conflict with repository contribution policies.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and accurately describes the main change: adding a new governance document (AGENTS.md) for AI Agent projects.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/agents.md

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 4c52e63 and 7a01c17.

📒 Files selected for processing (1)

• AGENTS.md (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• AGENTS.md

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Analyze (java-kotlin)

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Summary of Changes

Hello @phongphongg, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a foundational document, AGENTS.md, to standardize the development practices for AI Agents within the project. The new guidelines aim to elevate code quality, ensure adherence to modern Java 25 features, enforce strict nullness compliance using JSpecify, and streamline version control processes. This ensures that all AI-generated or modified code maintains a high level of consistency, reliability, and maintainability.

Highlights

• AI Agent Development Standards: Introduces a new markdown document, AGENTS.md, which formalizes mandatory quality, compliance, and procedural rules for all code generated or modified by the AI Agent in this project.
• Code Quality and Modernization: Establishes rules for modern Java 25 usage, Checkstyle compliance, comprehensive unit testing, explicit error handling, GraalVM native image compatibility, and proactive modernization of legacy APIs.
• JSpecify Nullness Compliance: Mandates a 'Non-Nullable by Default' principle, specifies the exclusive use of @Nullable for explicit nullability, defines generics nullability, requires @NullMarked in package-info.java, and outlines an audit for legacy nullness.
• Version Control Guidelines: Details strict Git commit structure adherence (7 rules) and requires the AI Agent to automatically suggest structured Pull Request Proposals for significant changes.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces AGENTS.md, a document outlining development standards for an AI agent. The guidelines are comprehensive, covering modern Java practices, nullness safety with JSpecify, and version control. The document is well-written and provides clear direction. I've added a couple of suggestions to refine the version control rules for better clarity and practicality.