Docs: Strengthen AI governance in AGENTS.md (review comments, co-author identity, agent safety)
- 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
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