Thanks EJ for drafting this. We’ve seen an increasing number of AI assisted PRs and reviews. While this is exciting, we still need humans in the development loop. In an OSS project like Polaris, that responsibility mainly falls on reviewers. I personally feel the growing pressure on the reviewer side.
With an agent.md, we could distill knowledge that contributors’ agents can reuse. I’d encourage everyone to chime in and contribute ideas, so contributors can use them as context for coding and self review. Hopefully, this should help improve code quality and relieve some of the burden on reviewers. Yufei On Wed, Apr 22, 2026 at 3:07 PM EJ Wang <[email protected]> wrote: > 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 >
