docs: add agent guidance to reduce verbosity

[kevinjqliu]

Which issue does this PR close?

• N/A

What changes are included in this PR?

I find my agent not behaving the way I'd like to create PRs, write code, and documentation... Hopefully these rules are a helpful nudge towards the right direction. 😄

Coding agents tend to be verbose: comments that restate the code, docs explaining review history, tests narrating asserts, unrelated renames, new pub items nobody needs, and PR descriptions that restate the diff.

• AGENTS.md: add guidance for coding agents. Default to no comment, keep docs to what callers need, keep diffs to the change, reuse before adding, use the narrowest visibility, keep PR descriptions short.
• .github/copilot-instructions.md: have Copilot review flag comment churn, unrelated edits, duplication, API growth, and verbose PR descriptions instead of skipping them as trivialities.

Follows the Java repo's comment guidance (apache/iceberg AGENTS.md comment guidance, rewrite).

Are these changes tested?

Docs only.

AI Disclosure

Implemented with GitHub Copilot.

[kevinjqliu]

these instructions were copied over from iceberg-cpp, and can use some tuning

[kevinjqliu]

we only had "Security Model" in this file before

[Copilot]

Copilot review overview

🟡 Changes recommended

The API-growth check can incorrectly classify legitimate downstream APIs as crate-internal.

Review effort: Balanced
Findings: 1

Open (1)

• Don’t restrict public APIs solely because they lack in-workspace callers · New

What changed in this PR

Adds repository guidance to reduce verbose agent-generated code, documentation, reviews, and PR descriptions.

Changes:

• Defines concise commenting, documentation, visibility, and diff-scope rules.
• Extends Copilot review guidance to flag unnecessary churn and API growth.

File	Description
AGENTS.md	Adds coding-agent and PR guidance.
.github/​copilot-instructions.md	Adds targeted review checks.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[kevinjqliu]

I'm still new at this coding agent / review agent thing, so not sure if this is the best. PTAL!
I asked my agent how to improve this, so it might be referential 😆 🤷

cc @blackmwk @CTTY @laskoviymishka @mbutrovich @dannycjones @comphead

[kevinjqliu]

note that these items that should be flagged

[comphead]

Thanks @kevinjqliu looks good to me, my agent skill also includes below, maybe useful in this PR:

• Reuse before adding: for every new object, method, helper, abstraction, etc., explicitly check whether an existing one can be reused, extended, or generalized.
• Deduplicate tests: identify tests introduced by the PR that duplicate existing coverage and remove/merge them rather than increasing test count without adding coverage
• Remove PR-created dead code: detect unused methods, structs, imports, fields, helpers, branches, feature flags, and test utilities introduced by the PR
• Avoid abstraction for abstraction's sake: reuse/generalize only when it makes the code simpler; don't introduce a new abstraction merely to eliminate a few lines

[kevinjqliu]

I like these, thanks @comphead! I’ll add them to the pr.

What are your thoughts on agent skill vs AGENTS.md? Do you think these changes are helpful in AGENTS.md?

[comphead]

What are your thoughts on agent skill vs AGENTS.md? Do you think these changes are helpful in AGENTS.md?

AGENTS.md makes more sense to me as this is project wise skill for any agent. The good followup would also be to have a kinda precommit hooks to perform code analysis and fix it. Also run tests, to avoid spending ASF CI resources on partially ready PRs like https://github.com/apache/datafusion/blob/main/AGENTS.md#before-committing

[andygrove]

I'd also recommend adding PR review skills to the repo so you can set expectations for reviews. Feel free to take inspiration from those in Comet

[andygrove]

I'd also recommend adding PR review skills to the repo so you can set expectations for reviews. Feel free to take inspiration from those in Comet

https://github.com/apache/datafusion-comet/tree/main/.ai/skills

[dannycjones]

Thanks Kevin, I think these are good improvements. Good to encode in AGENTS.md rather than continuing to argue with it 😄

AGENTS.md makes sense as a good general steer for the LLM. I'd hestitate to add skills for now except for very specific tasks (like code review which Andy suggested just now).

[dannycjones]

I'd also recommend adding PR review skills to the repo so you can set expectations for reviews. Feel free to take inspiration from those in Comet

https://github.com/apache/datafusion-comet/tree/main/.ai/skills

I'm wondering if we can do this, and just point Copilot at it so people can use whichever model and harness with the same markdown.

[laskoviymishka]

Thanks! This will make our life a bit better <3

🌬️ ⛵

[mbutrovich]

I'm taking a pass through this now.

[mbutrovich]

Thanks @kevinjqliu, this will save reviewers a lot of back and forth with agent-written PRs. The comments suggest a few additions drawn from feedback that comes up repeatedly in reviews here.

[blackmwk]

Thanks @kevinjqliu for this pr, and @mbutrovich for review!