[PROPOSAL] Adopt AGENTS.md across OpenFeature repositories

Summary

I'd like to propose that OpenFeature adopt AGENTS.md as a per-repository convention for AI coding agent instructions, with CLAUDE.md as a symlink to it, and that we document a generative AI contribution policy in technical-guidelines.md.

Agent-assisted PRs are already arriving whether or not we have a position on them. Today an agent working in an OpenFeature repo infers our conventions from scratch and usually infers wrong — it runs go test ./... instead of make test, misses the e2e submodule, forgets DCO sign-off, names a spec conformance test whatever it likes, and writes its own PR description. Each of those is a review round trip a maintainer pays for.

Prior art

Most of CNCF has already done this. Root AGENTS.md files ship today in kubernetes/kubernetes (plus kops, kubebuilder, karpenter, kueue), 11+ OpenTelemetry repos including the collector and specification, OPA, Gatekeeper, Argo CD, Prometheus, Envoy, Helm, Flux, Jaeger, Vitess, KEDA, Kyverno, Backstage, and Tekton, among others. TAG Developer Experience is studying the topic in its State of AI-Assisted Development initiative.

OpenFeature has no AGENTS.md anywhere. The only agent file in the org is an ad-hoc CLAUDE.md in ruby-sdk — good content, but only Claude Code reads it, so every other agent gets nothing.

Proposal

1. AGENTS.md per repository

These files should be mostly unique per repository — the content that actually changes agent behaviour is toolchain-specific, and an org-wide file would be too vague to help.

open-feature/go-sdk is the clearest example. Its CONTRIBUTING.md already encodes things agents reliably get wrong:

• Unit tests run via make test, e2e via make e2e-test, and e2e needs the test-harness submodule pulled first with git submodule update --init --recursive. Agents skip the submodule step and then misread the failure.
• Spec conformance tests follow TestRequirement_x_y_z for spec requirement x.y.z, with the requirement description as a comment on the test. No agent invents that convention.
• Release Please generates CHANGELOG.md from Conventional Commit titles, so it's never hand-edited; DCO sign-off (git commit -s) is required on every commit; and runtime dependencies are deliberately kept as few as possible, so adding one needs review.

Almost none of that transfers to java-sdk or flagd. So: per-repo files, authored by that repo's maintainers, kept short and linking to CONTRIBUTING.md rather than restating it, so we don't create a second source of truth that drifts. opentelemetry-go's is a good model for a Go repo; OPA's is a good short policy-led one.

2. CLAUDE.md as a symlink

Claude Code reads CLAUDE.md, so a symlink keeps one source of truth with zero duplicated content:

ln -s AGENTS.md CLAUDE.md
git add CLAUDE.md

jaegertracing/jaeger and kubernetes-sigs/karpenter both do exactly this (git mode 120000). Repos can symlink other tool files the same way if maintainers want (kubernetes/kops adds GEMINI.md), but I'd only standardise AGENTS.md and CLAUDE.md.

3. Generative AI contribution policy

As a CNCF project we're already covered by the Linux Foundation Generative AI Policy, so this is about extending that baseline rather than inventing one. OpenTelemetry's policies/genai.md is a useful precedent — it explicitly supersedes and extends the LF policy, and it recommends AGENTS.md as a disclosure mechanism.

For the GitHub-interaction half specifically, I'd suggest following the approach in jdx's AGENTS.md, which I think draws a better line than a blanket ban:

• AI-assisted responses are welcome, spam is not. The distinction worth encoding is connected-vs-drive-by, not human-vs-AI: someone answering their own question or an established contributor helping out is fine, while volume AI answers from accounts with no connection to the project are the actual problem. Several projects, OpenTelemetry included, instead ban AI-generated issue and PR comments outright — I'd rather not discourage contributors who use these tools to communicate.
• Disclose AI-contributed GitHub prose with a consistent line. When AI contributes a PR description, review, comment, or discussion post, append a disclosure naming tool, model, and version — e.g. *AI-assisted — Tool: <tool>; model: <provider>/<model>; version: <version>.* — using identifiers the runtime actually exposes, never inferred, with unavailable where a value isn't.
• PR descriptions are written for reviewers, not as a changelog of files. Lead with the user-visible problem and outcome, include concrete examples for user-facing behaviour, and keep implementation detail and test commands in secondary sections.
• The human author is accountable and must have reviewed the change before submitting — Kubernetes puts it as "do not leave the first review of AI generated changes to the reviewers." Agree direction on the issue first for anything non-trivial, keep AI-assisted PRs tightly scoped, and leave maintainers discretion to close low-effort generated contributions with an explanation.

The org-wide CONTRIBUTING.md can then link to this the way it already links to the DCO section.

4. Where this lands

• A short baseline AGENTS.md template in open-feature/.github/templates/, alongside the existing README templates — org-wide policy bits only, toolchain sections left to maintainers.
• A generative AI section in technical-guidelines.md, plus a row in the repository requirements table as recommended, not required. Requiring it would produce unmaintained files in repos that see no agent traffic.
• go-sdk as the first implementation, since its CONTRIBUTING.md is the most detailed in the org.

Ask

Feedback on whether the TC wants to take this on, and specifically: recommended vs. required, the disclosure shape, and whether go-sdk is an acceptable first repo.

AI-assisted — Tool: Claude Code; model: anthropic/claude-opus-5; version: 2.1.236.

Start with technical-guidelines.md, the existing .github/templates directory, and the org-wide CONTRIBUTING.md; compare the go-sdk CONTRIBUTING.md with the linked AGENTS.md examples. Review the open questions about recommended versus required adoption, disclosure wording, and go-sdk as the first implementation. Done means the TC has decided the direction and the agreed template, policy guidance, and repository links are documented.