Hey all, I put up a draft PR [1] adding an AGENTS.md to the repo. AI coding agents (Claude Code, Codex, Cursor, Copilot, etc.) pick this file up automatically, similar to how CONTRIBUTING.md works for humans. Right now we don't have any project-level guidance for them, and the result is predictable: missing license headers, invented patterns, scope creep, PRs that cost reviewers time on things that could have been caught earlier.
The file splits rules into hard gates (format, compile, headers, module checks/tests) and discipline rules (scope, simplicity, naming, PR descriptions). Hard gates are things agents can verify mechanically. Discipline rules need judgment, but spelling them out still helps, agents do follow behavioral instructions when they're concrete enough. I kept this separate from CONTRIBUTING.md because the audiences need different things. Agents want exact gradle commands and file paths. Humans want rationale and process. The two cross-reference each other where they overlap. This covers coding hygiene only. My bias would be to add architecture context and reviewer-oriented skills (thinking GitHub Copilot auto-review) in later phases, but wanted to get the basics landed first and see if the direction makes sense to folks. [1] https://github.com/apache/polaris/pull/4276 -ej
