Docs: Strengthen AI governance in AGENTS.md (review comments, co-author identity, agent safety)

Open Beginner friendly
#17,670 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
82/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Quiet
Domain
documentation, security

Research direction

Start by reading the existing AI section in AGENTS.md and the linked review-comments discussion. Expand AGENTS.md with the four requested areas: human-reviewed concise comments, canonical Generated-by crediting, safe agent operation, and unchanged review and security gates. Done means the change remains docs-only and clearly covers each proposal item.

Written by the indexing model from the issue text.

Description

improvement
Feature Request / Improvement
Background

The [DISCUSS] AI Review comments thread on dev@iceberg.apache.org raised that AI-generated review comments are often verbose, sometimes posted without human review, and can conflict across different AI tools. While investigating, I also found related issues in recent commit metadata on main.

Findings (last ~2 months on main)
  • PRs merged; 9.6% PR show LLM authorship/assist signals; 80 are Dependabot.
  • AI tools are being recorded as Co-authored-by: with bot noreply@ addresses.
  • The same tool appears under multiple identities, which fragments contributor
    stats and misrepresents provenance. Examples observed:
    • Claude Opus 4.8 (1M context) <noreply@anthropic.com>
    • Claude Opus 4.8 <noreply@anthropic.com>
    • Claude Opus 5 (1M context) <noreply@anthropic.com>
    • Claude Opus 4.6 (1M context) <noreply@anthropic.com>
    • Claude <svc-devxp-claude@slack-corp.com>
    • Codex <codex@openai.com>
    • Cursor <cursoragent@cursor.com>

AGENTS.md currently covers PR-authoring disclosure and the Generated-by: token well, but has only a single soft line on review comments and nothing on co-author identity or AI review-agent safety.

Proposal

Expand the AI section of AGENTS.md to add:

  1. AI-Assisted Review Comments - a human must read, understand, and endorse each AI comment and post it under their own account; keep comments concise
    (what/where/fix); at most one AI reviewer per PR; no auto-posting.
  2. Crediting AI Tools - disclose AI via the Generated-by: token, not Co-authored-by: bot identities; use one canonical tool name; reserve
    Co-authored-by: for humans.
  3. AI Review Agent Safety - treat agent-instruction files (AGENTS.md, CI agent configs) as security-sensitive; run AI review agents with least privilege and no auto-acting on untrusted PR content. (Motivated by documented prompt injection via agent-instruction files.)
  4. Boundaries - AI-authored PRs must pass the same review, test, and security/static-analysis gates as human-authored PRs.
Scope

Docs-only change to AGENTS.md. A PR implementing this will be linked.

Links
Query engine

None

Willingness to contribute
  • I can contribute this improvement/feature independently
  • I would be willing to contribute this improvement/feature with guidance from the Iceberg community
  • I cannot contribute this improvement/feature at this time
Dominant language
Java
Stars
9.3k
Forks
3.5k
Avg merge
2d 11h
Merged PRs (30d)
143

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from apache/iceberg

All issues in apache/iceberg

Similar issues

More Java issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.