RFC: Add an AGENTS.md to guide AI coding agents

[junyeong0619]

Motivation

AI coding agents (Claude Code, Cursor, Copilot, etc.) are increasingly used to open PRs.
Armeria's conventions are well documented for humans in the
developer guide, but there's no
machine-discoverable entry point, so agents routinely miss project-specific rules and
produce noisy PRs:

• Public APIs target Java 8; agents often reach for newer APIs.
• com.linecorp.armeria.internal packages must not be referenced from public APIs.
• Apache 2.0 copyright header on every new file (and not bumping the year on edits).
• Javadoc required on public/protected members.
• JUnit 5 + AssertJ, not JUnit 4 / JUnit assertions.
• Checkstyle formatting, requireNonNull(x, "x"), @Nullable (never @Nonnull), etc.

The repository already includes agent tooling — a .claude/ plugin/skill directory — so
agent usage is clearly part of the workflow. What's missing is the standard entry point that
tells an agent how Armeria wants code written. A standardized AGENTS.md fills that gap,
improving the quality of agent-generated PRs and reducing reviewer burden.

Proposal

Add a root-level AGENTS.md following the vendor-neutral agents.md
convention. It summarizes build/test commands, code style, and PR conventions, and points
to the developer guide as the canonical source (the guide always wins on conflicts). It is
documentation-only — no behavior or build change.

Note: CLAUDE.md is already in .gitignore, so AGENTS.md (read by most agent tools) is
the natural committed source of truth, complementing the existing .claude/ tooling.
Contributors can keep a local CLAUDE.md symlink if they wish.

Prior art

• apache/airflow ships an AGENTS.md.
• valkey-io/valkey ships an AGENTS.md.
• The agents.md convention is read by Claude Code, Cursor, Copilot, and others.

Scope / non-goals

• Doc-only; complements (does not replace) the developer guide.
• Kept concise and in sync with the developer guide to avoid drift.

Open questions

• Location: repository root (recommended) vs .github/.
• How detailed should it be — a short pointer vs a fuller summary?

I have a draft ready and can open the follow-up PR if there's interest.