Skip to content

ai-contribution-policy: adopt documentation-first approach for AI context#444

Open
iholder101 wants to merge 1 commit into
kubevirt:mainfrom
iholder101:ai-policy-docs-first
Open

ai-contribution-policy: adopt documentation-first approach for AI context#444
iholder101 wants to merge 1 commit into
kubevirt:mainfrom
iholder101:ai-policy-docs-first

Conversation

@iholder101

Copy link
Copy Markdown
Contributor

What this PR does / why we need it:
Replaces the AGENTS.md/vendor-specific prompt file approach with an agent-agnostic, documentation-first strategy for providing context to AI tools.

Repositories are encouraged to maintain a documentation index file linking existing docs by topic [1], keeping project knowledge in standard markdown that serves both humans and AI tools equally. A clear separation between agent-agnostic documentation and vendor-specific tool configuration is established, and local development tool choice is left to individual contributors.

[1] This pattern is adopted by other projects (e.g., Anthropic's docs map).

Release note:

NONE

…text

Replace the AGENTS.md / vendor-specific prompt file approach with an
agent-agnostic, documentation-first strategy. Repositories provide a
documentation index file instead of AGENTS.md, and maintain a clear
separation between agent-agnostic documentation and tool-specific
operational configuration. Local development tool choice is left to
individual contributors.

Assisted-by: Claude <[email protected]>
Signed-off-by: Itamar Holder <[email protected]>
@kubevirt-bot kubevirt-bot added the dco-signoff: yes Indicates the PR's author has DCO signed all their commits. label May 28, 2026
@kubevirt-bot

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign stu-gott for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@iholder101

Copy link
Copy Markdown
Contributor Author

/cc @EdDev @vladikr @lyarwood

@EdDev EdDev left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for this direction, replacing the AGENT.md reference with a documentation-first approach is a cleaner long-term strategy.

One structural point worth discussing: the new "Providing Context to AI Tools" section feels like it belongs in a dedicated file rather than inline here.

The existing ai-contribution-policy.md is consistently contributor-facing: it tells people what to disclose, what they're responsible for, and how reviewers should evaluate AI-assisted work. Every section addresses the same actor: a contributor submitting a PR.

The new section addresses a different actor and a different moment in time: it's repository-maintainer guidance for how to set up a repo to work well with AI tools. That's a meaningful shift in audience and scope.

There's also a practical concern: the section names concrete artifacts, i.e. AGENTS.md, .coderabbit.yaml, documentation index files. These conventions are still evolving and will need updates as tooling changes. Embedding them in a policy document means the policy gets touched for what are really tooling-hygiene updates, which is friction and noise. A dedicated ai-tooling-guidelines.md can evolve at its own cadence.

The PR already does the right structural thing on the contributor-policy side, the cross-reference (see Providing Context to AI Tools) in the
Disclosure section. It just needs to point outward to a separate file rather than downward within the same document.

How about this:

  1. Move the new section into a new dedicated file (e.g., ai-tooling-guidelines.md)
  2. Update the cross-reference in the Disclosure section to point to that file.

This keeps the policy document focused on its original purpose, and gives the tooling guidance room to grow without polluting the policy's change history.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

dco-signoff: yes Indicates the PR's author has DCO signed all their commits. size/M

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants