[FEATURE] Add AGENTS.md to guide AI coding agents contributing to Kyuubi

[wangzhigang1999]

Code of Conduct

• I agree to follow this project's Code of Conduct

Search before asking

• I have searched in the issues and found no similar issues.

Describe the feature

Add an AGENTS.md at the repository root that documents project conventions, build/test commands, module boundaries, and AI-assisted contribution policy in a format optimized for AI coding agents (Claude Code, Codex, Cursor, Copilot, Gemini, etc.).

AGENTS.md is an emerging cross-tool convention (see https://agents.md) that complements CONTRIBUTING.md — it's terser, command-oriented, and explicitly addresses agent failure modes (silent compliance, scope creep, fabricated APIs, undisclosed AI authorship).

Motivation

AI-assisted contributions to Kyuubi are already happening — recent merged PRs show the practice is here. Without an in-repo guide, agents miss project-specific conventions: the [KYUUBI #xxxx][COMPONENT] PR title, our pre-commit/style checks, the engine isolation between externals/kyuubi-*-sql-engine modules, the JVM-version matrices for Spark/Flink/Hive/Trino profiles.

Reviewers end up flagging the same things repeatedly.

The convention has reached critical mass in the Apache ecosystem. As of May 2026, 60+ Apache repos have committed an AGENTS.md to root, including direct neighbors of Kyuubi:

• Apache Spark, Apache Flink — both engines Kyuubi gateways
• Apache Iceberg, Apache Paimon, Apache Polaris, Apache Gravitino — table format / catalog peers
• Apache Doris, Apache Pinot, Apache Druid — OLAP peers
• Apache Airflow, Apache Superset, Apache Zeppelin, Apache ShardingSphere

Active proposals exist in Cassandra (CASSANDRA-21301), Arrow R, and Fluss.

Describe the solution

Propose an AGENTS.md (~150–200 lines, ~8KB) at the repo root, modeled on the Spark/Iceberg/Flink style. Tentative outline:

1. Pre-flight Checks — remote setup, fetch upstream, branch selection (Spark-style)
2. Build and Test — Maven single-module / single-class / single-method commands, the dev format/lint scripts, the -Pspark-3.5 / -Pflink-1.18 profile pattern
3. Repository Structure & Module Boundaries — kyuubi-server, kyuubi-common, externals/, extensions/; engine modules must not depend on each other; server must not depend on engine modules
4. High-Sensitivity Areas — Thrift IDL under kyuubi-common/src/main/thrift/, OperationManager/SessionManager, Kubernetes operations
5. Coding Standards — Checkstyle/scalastyle expectations; AssertJ for tests
6. PR & Commit Conventions — [KYUUBI #xxxx][COMPONENT] title, link the issue, fill the PR template, the existing AI-disclosure checkbox
7. AI-assisted contributions — use Generated-by: rather than Co-Authored-By: ; no AI self-references in code/comments/messages (Flink/Polaris pattern)
8. Investigating CI failures — use gh api check-run annotations rather than downloading full logs (Spark pattern)
9. Boundaries — explicit Never / Ask first lists (no direct push to apache/kyuubi, no mixed PRs, no secrets, no breaking thrift, ask before new dependencies / public API changes / cross-engine refactors)

Additional context

Reference implementations from sibling Apache projects:

• apache/spark/AGENTS.md (https://github.com/apache/spark/blob/master/AGENTS.md) — closest analog; pre-flight checks and CI-failure investigation are particularly worth borrowing
• apache/iceberg/AGENTS.md (https://github.com/apache/iceberg/blob/main/AGENTS.md) — strong "high-sensitivity areas" + Boundaries section
• apache/flink/AGENTS.md (https://github.com/apache/flink/blob/master/AGENTS.md) — most comprehensive AI-disclosure policy
• apache/polaris/AGENTS.md (https://github.com/apache/polaris/blob/main/AGENTS.md) — explicit [HARD GATE] vs [DISCIPLINE] rule classification

Happy to draft the file in a follow-up PR once the community aligns on scope.

Are you willing to submit PR?

• Yes. I would be willing to submit a PR with guidance from the Kyuubi community to improve.
• No. I cannot submit a PR at this time.

[wangzhigang1999]

I did a quick survey of the latest 100 PRs, and 21 of them — #7442, #7439, #7437, #7436, #7431, #7429, #7426, #7425, #7419, #7417, #7409, #7408, #7404, #7400, #7393, #7386, #7385, #7374, #7368, #7320, #7306 — explicitly stated that they were AI-assisted.

I think we could follow Iceberg's approach and distill project conventions, architecture, and coding patterns unique to the Kyuubi community from historical reviews and comments.

https://github.com/apache/iceberg/blob/main/AGENTS.md?plain=1#L22C1-L23C1

[wangzhigang1999]

Circling back with a concrete draft.

To avoid writing it from intuition, I mined Kyuubi's review history first — 4564 PRs scraped, 369 high-signal landed PRs analyzed, 1503 evidence-grounded rule candidates extracted, then manually consolidated into 86 canonical rules across 13 themes. That data made one thing very visible: review here is carried by a handful of extremely active maintainers.

Reviewer	PRs reviewed	Formal reviews	Inline comments	Approvals
@pan3793	1960	4009	2549	1590
@yaooqinn	1395	3136	1979	1204
@ulysses-you	719	1242	917	552
@turboFei	388	915	620	354
@bowenliang123	323	597	364	275
@cxzl25	563	677	167	525
@cfmcgrady	267	341	164	205
@wForget	149	281	175	120

Thank you for the years of patient review — most rules in the draft are literally your words, paraphrased.

Gist (two files): https://gist.github.com/wangzhigang1999/fddcbc62528b343232ed0898f7fc953a

• AGENTS.md — proposed draft (~440 lines)
• distilled_conventions.md — the 86 canonical rules with PR citations and reviewer attribution, for traceability

Caveat worth naming: @pan3793 and @yaooqinn cover ~89% of landed-PR review activity, so the draft disproportionately reflects their judgment.

Would particularly value review on:

1. Hard boundaries (server doesn't depend on engines, engines don't depend on each other, public APIs are cluster-manager-agnostic, no Spark-incompatible SQL, no Thrift wire breaks) — accurate, or are there nuances worth calling out?
2. AI disclosure — draft uses Generated-by: <tool> (per the existing PR template) and forbids Co-Authored-By: <AI> and AI self-references in code/commits. Aligned with Flink/Polaris; happy to change if the community prefers something else.
3. What's missing — concurrency and security came up in review history but were too PR-specific to consolidate. Patterns you consistently expect contributors to know probably belong in the draft.

If the direction looks OK, I'll open a draft PR placing the file at the repo root.

[yaooqinn]

SGTM