RFC: AI contribution conventions — PRs, commits, comments, attribution #238

Why

Multiple maintainers using multiple AI tools means inconsistent PR shapes, commit styles, comment density, and attribution if left undefined. Worth landing a short RFC/ADR that defines, tool-agnostically, what AI-assisted contributions should look like — for any contributor using any AI tool, not Claude- or Copilot-specific.

Framed as a discussion/RFC, not a deliverable. The conventions are opinionated and need maintainer agreement before they land as enforced rules.

Scope to cover

• Attribution: when and how to credit AI involvement. Co-Authored-By lines are already used for Claude-driven commits — should Copilot and others follow the same shape? Should the AI's role (drafted / reviewed / executed verbatim) be distinguishable, or is "any AI involvement = one Co-Authored-By line" enough?
• PR description style: how much "explain my reasoning" detail an AI-assisted PR should include. Real tension between useful reviewer context and a wall of AI-generated text that obscures the actual change.
• Comments in code: AI tools love adding comments. CLAUDE.md already says "default to writing no comments". Promote to a repo-wide rule for humans too, or keep AI-specific?
• Review expectations: do AI-authored PRs go through the same review path as human ones, a faster one (rubber-stamp if CI green?), or a stricter one (assume hallucinations until proven otherwise)?
• What's NOT acceptable: speculative refactors, doc-only PRs that add no value, hallucinated API references, changelog entries not grounded in the diff, etc.
• Commit hygiene: AI tools produce many small commits. Squash-on-merge default, or guidance on commit granularity?

Action

• Open as a GitHub Discussion (or keep this issue as the thread) — gather maintainer input
• Draft conventions as an ADR under docs/adr/
• Land the outcome in CONTRIBUTING.md and/or AGENTS.md
• Decide if any of this is machine-enforced (commit-msg hook, PR-template required fields) or stays social

Coordinate with

• AGENTS.md adoption issue — outcome lives there
• Data-handling policy issue — adjacent concern

Done when

• ADR drafted and merged
• CONTRIBUTING.md / AGENTS.md reference the conventions
• (Optional) machine-enforced bits wired into hooks or PR templates