ai-contribution-policy: adopt documentation-first approach for AI context#444
ai-contribution-policy: adopt documentation-first approach for AI context#444iholder101 wants to merge 1 commit into
Conversation
…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]>
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
EdDev
left a comment
There was a problem hiding this comment.
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:
- Move the new section into a new dedicated file (e.g.,
ai-tooling-guidelines.md) - 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.
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: