OSS Maintainers Can Inject Their Standards Into Contributors' AI Tools

What Happens Without These Files

Most AI development tools support user-level configuration: a global settings file or system prompt the user has set up for their own work. When a contributor clones your repo and starts working, their tool loads those personal defaults instead of your project's standards. Their defaults are probably tuned for their own projects. Maybe they default to Tailwind, or their system prompt says nothing about testing conventions at all.

So the tool generates code that fits the contributor's personal setup. It can't see your project's architecture, CSS approach, test patterns, or contribution policies. The contributor submits a PR with a mismatch they never intended.

What Prompted This

In February 2026, an AI agent submitted a performance optimization PR to the matplotlib repository. A volunteer maintainer closed it. The linked issue was a "good first issue," reserved for human newcomers learning how open source collaboration works. The agent didn't know that policy. When the PR was closed, the agent published a blog post about the maintainer, with no human review before it went live. The whole thing went viral.

Scott Shambaugh, the maintainer who closed the PR, wrote up the incident in full. I'd recommend reading his account.1 He handled the situation with more grace than most people would. His observation stuck with me: "We are in the very early days of human and AI agent interaction, and are still developing norms of communication."2

The incident got framed a lot of ways: AI gone rogue, maintainer gatekeeping, a preview of an AI-vs-human turf war. I read it as an infrastructure problem. The project had no way to communicate its policies to the tool, so the tool started working with no context. Maintainers can fix that part.

Who This Actually Helps

I wrote this for maintainers. But the people it helps most are the well-meaning new contributors who are about to open a PR from their AI-assisted workflow.

The matplotlib incident is an extreme case: automated publishing with no human review gate and a personality configuration designed for confrontation. The typical AI-assisted PR in a maintainer's queue comes from someone new to development who learned to code with AI assistance, found an open source project they care about, and wants to contribute. Claude or Copilot or Cursor is their development environment. They generate a fix, it looks right to them, and they open a PR.

The AI tool had no idea the project uses semantic CSS instead of Tailwind, that the test suite expects real assertions, or that good-first-issue is a reserved label. It couldn't see the attribution requirement or the Code of Conduct either.

The contributor didn't tell it those things, because they didn't know either. The project's conventions live in a CONTRIBUTING.md they may have skimmed, in code review comments on other PRs they didn't see, or in the heads of maintainers who've been doing this for years.

These contributors want to help. You can give their tools the context they're missing.

CLAUDE.md and AGENTS.md

Either file helps on its own, and having both covers more ground.

CLAUDE.md is a project-level instruction file that Claude Code reads automatically when it opens a project. Any project can add one. It's plain markdown. You put in whatever you'd put in a senior engineer's onboarding document: architecture decisions, coding conventions, testing requirements, and the things contributors keep getting wrong.

AGENTS.md is a vendor-neutral open standard now stewarded by the Linux Foundation's Agentic AI Foundation.3 Over twenty tools support it: OpenAI Codex, Gemini CLI, Cursor, Zed, Aider, Jules, GitHub Copilot Coding Agent, Windsurf, Devin, Factory, RooCode, Warp, goose, and more. Over 20,000 GitHub repositories have already adopted it. It works like CLAUDE.md: plain markdown with flexible headings, read by any compliant AI tool.

Claude Code isn't on the AGENTS.md supporter list. It reads CLAUDE.md instead, which is why I'd add both files.

When a contributor clones your repo and opens it in their AI tool, the tool loads these files into context automatically. The contributor doesn't have to read them or configure anything. They don't even have to know the files exist.

Structurally, this is the same mechanism as prompt injection. In the security context, an attacker inserts instructions into an AI's context through content it reads. Here, you're doing the same thing with a file you control, in a repo you own. The AI reads your standards, and they shape what it produces. The contributor gets code that fits your project before they've talked to a maintainer at all.

The closest comparison I can think of is .editorconfig. That file solved tabs-vs-spaces across editors by putting the preference in a place every participating tool reads automatically. Nobody has to tell each contributor to configure their editor, because the tooling handles it. CLAUDE.md and AGENTS.md work like that, with a much larger surface area. .editorconfig handles formatting, which is two or three settings. These files cover architecture conventions, testing requirements, contribution policies, attribution, and behavioral expectations. And they do it for every AI-assisted contributor who shows up, regardless of which tool they're using.

What to Put in Them

You don't need an exhaustive document on day one. I'd take five specific bullet points over three pages of aspirational guidance.

Start with what contributors consistently get wrong. You probably already have that list in your PR review history. Look at what you write over and over in review comments and what your CI catches on repeat.

For a project with a good-first-issue policy, you could put this in AGENTS.md:

## Contribution Guidelines

- Good first issues (labeled "good first issue") are reserved for new human contributors.
  Do not submit AI-assisted PRs to these issues.
- If you use AI tools in your development process, disclose it. See our PR template.
- Read CONTRIBUTING.md and our Code of Conduct before opening any issue or PR.
- Do not post AI-generated content to issues or PRs via automated tooling.
- If a PR is closed, accept the maintainer's decision.

That's five lines, and any compliant agent reads them before it touches the repo.

For coding standards, lead with the pattern you want, then add the anti-pattern for clarity. The CLAUDE.md on claude-desktop-debian does this:

Patterns (what you want):

• Use tabs for indentation in shell scripts
• Use config() helper for accessing configuration values
• Reference issues in branch names: fix/123-description

Anti-patterns (what you don't want):

• Don't hardcode variable names from minified JS; use regex patterns instead
• Don't suppress shellcheck warnings; fix the underlying issue
• Don't call env() outside config files

Each line is specific enough that an AI tool reading it knows what to do and what to avoid.

The same goes for contribution process. If your project has policies around PR scope, testing requirements, or communication norms, put those in too.

Attribution

If your project has an opinion on AI usage, write it down. Attribution requirements are one of the most useful things to include, and this pattern has started showing up in contributors' commits and PRs.

A generic attribution block that works with any tool:

---
AI-assisted development
Tool: [tool name and version]
AI contribution: [what AI did]
Human contribution: [what human did]

A tool-specific version (from claude-desktop-debian's CLAUDE.md):

---
Generated with Claude Code
Co-Authored-By: Claude <model-name> <noreply@anthropic.com>
XX% AI / YY% Human
Claude: <what AI did>
Human: <what human did>

For commits: Co-Authored-By: Claude <claude@anthropic.com>

The percentage split should honestly reflect the contribution. That way a maintainer can evaluate the PR with full context from the start and doesn't have to ask.

Pointers to existing docs

Include a reference to CONTRIBUTING.md. Most contributing guides have more detail than you'd want to duplicate in an AGENTS.md. A line like "Read CONTRIBUTING.md before opening any PR" gives a compliant tool a document to fetch and reason against.

On Banning AI Contributions

Some maintainers have responded to incidents like this by wanting to ban AI contributions outright. I understand the impulse.

The problem is that a ban can't be enforced. You can't tell from a PR whether the contributor used AI. A contributor who generates a fix with Claude, reads it carefully, understands every line, and submits it with a clear description looks exactly like one who wrote it by hand. And that contributor may be the kind of new developer you want to bring into the project.

What works better is the same mechanism that makes AGENTS.md useful. You can't stop a contributor from using whatever tool they bring, but you can inject your standards into that tool before they start. Your attribution rules and contribution policies load as soon as they open the repo in their tool. A compliant tool passes those requirements along to a contributor who will, in good faith, follow them.

Non-compliant configurations don't have an enforcement answer. An operator who configures automated, no-review publishing can override any AGENTS.md. That's a separate problem, and the liability sits with the operator rather than the project. For compliant, good-faith contributors (which is most of them), AGENTS.md gives clear guidance before they make their first mistake.

Where My Own Pipeline Fits

claude-desktop-debian is a published open source project with 2,000+ stars. It packages the Claude desktop app for Debian-based Linux distributions. I mention it because it has a real .claude/ folder you can look at, and it shows what a more involved version of this pattern looks like.

The project has 10 specialized agents (bash-script-craftsman, bats-test-validator, cc-orchestration-writer, cdd-code-simplifier, ci-workflow-architect, code-reviewer, electron-linux-specialist, packaging-specialist, patch-engineer, spec-reviewer) plus 7 skills covering tasks like implementing issues, running improvement loops, and linting. There are hooks and scripts for automated quality gates.

Its CLAUDE.md covers shell script style, linting requirements (shellcheck + actionlint), GitHub workflow conventions, the attribution templates above, working with minified JavaScript, CI/CD patterns, and debugging workflows. Its AGENTS.md keeps things minimal and points to CLAUDE.md for the detailed rules. You can read both files in a few minutes.

You don't need all of that to get started, though. The minimum viable version is a CLAUDE.md and an AGENTS.md, each with your project's key constraints. An hour of writing gets you two files that a contributor's AI tool reads on its own.

What This Gets Maintainers

Maintainer time is the scarce resource here. Every bad PR that arrives costs time on rejection, explanation, and sometimes de-escalation. When your standards live in a file the tool reads, those conversations happen less often.

Contributors will still make mistakes. But the ones that come from "the tool had no project context" mostly go away.

So the PRs that show up start from a better baseline. Your review time goes to judgment calls, like whether this is the right approach and whether it fits the project's direction. You spend less of it writing the same convention feedback for the tenth time.

A contributor who's new to development and leans heavily on AI tools is often learning in public. They're figuring out how open source collaboration works and what a good PR looks like. Your AGENTS.md becomes part of how they learn that.

Most AI-assisted PRs that get closed for convention violations never turn into blog posts. They just eat maintainer time on boilerplate rejection comments. The contributors don't know why they got rejected, and they don't come back.

The first fix is a markdown file that loads your standards into whatever tool a contributor brings. Go write one.