apache / apache/iceberg

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
improvement
Dominant language
Java
Stars
9.2k
Forks
3.5k
Avg merge
2d 11h
Merged PRs (30d)
132

Description

### 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) `
- `Claude Opus 4.8 `
- `Claude Opus 5 (1M context) `
- `Claude Opus 4.6 (1M context) `
- `Claude `
- `Codex `
- `Cursor `

`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

- `[DISCUSS] AI Review comments` thread: https://lists.apache.org/thread/y93010hlq2m59jjw9lsjbrs38xw8nkdb

### 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

Contributor guide

Open the contributing guide

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.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.