Hi all, I've opened PR #25871 (https://github.com/apache/pulsar/pull/25871) that adds an AGENTS.md to the repository and updates the top-level docs so that AI coding agents and human contributors can find the same conventions in one place.
In short: - AGENTS.md is a short "router" that AI coding assistants (Claude Code, Copilot, Cursor, Gemini, Codex, Aider, ...) read. CLAUDE.md and .github/copilot-instructions.md are symlinks to it. - AGENTS.md references ASF's Generative Tooling guidance ( https://www.apache.org/legal/generative-tooling.html) and aligns with it. - The detail lives in human-facing docs at the repo root: CONTRIBUTING.md (build / test / PR workflow), ARCHITECTURE.md (module map and the Gradle build), CODING.md (code style, async, concurrency, logging, testing, backward compatibility), and SECURITY.md (reporting, disclosure hygiene, and the security model). These were updated to be consistent with each other. - Task-specific guardrails live under .agents/skills/ so an agent can load only what's relevant on demand and keep its context small. A similar approach is used in apache/groovy and apache/grails. - Many of the coding and contribution conventions were distilled from recurring guidance in past PR reviews, so they double as a written-down reference for humans. I'd appreciate a review before it's merged - please take a look at https://github.com/apache/pulsar/pull/25871. I plan to merge it unless there's prompt feedback to address. Thanks, Lari
