Documenting repository policies on AI tooling in CONTRIBUTING.md and repository instruction files (AGENTS.md / CLAUDE.md)

[Florian Heberl (floh96)]

In recent issues and pull requests (such as #20638 and #20620), maintainers have clarified repository policies regarding AI-assisted contributions, agentic workflows, and commit attributions.

Currently, these expectations are communicated on a case-by-case basis in individual issues and review threads. I think it would be helpful to formally document these rules in a central place—both to give human contributors clear expectations upfront and to inform automated tooling.

Areas for consideration

1. CONTRIBUTING.md
   Documenting the team's policy directly in CONTRIBUTING.md would provide clear visibility for new and existing contributors before they submit issues, comments, or pull requests.

2. Repository instruction files (AGENTS.md / CLAUDE.md)
   Many modern developer tools, coding assistants, and local agent workflows automatically check for instruction files in the repository root (such as AGENTS.md or CLAUDE.md) when a workspace is opened. Having an instruction file in place can communicate the repository's rules directly to these tools, helping ensure that local workflows respect the team's contribution guidelines and commit formatting requirements.

[Leonard Hecker (lhecker)]

Are you seriously starting a discussion about AI by letting it write the discussion too? lol
Like, what's even the point then to still talk with you about it? I can just ask my AI what it thinks. In fact here you go:

---

Thanks for writing this up. It's a fair ask — right now the policy exists mostly as review comments, and that's not discoverable.

A couple of thoughts on scope, though:

The thing we actually care about isn't "was a model involved". It's whether a human understood the change well enough to defend it in review, and whether the commit attribution is honest. Those two are what the recent threads were really about. A rule phrased as "no AI" is both too broad (I don't care if you used completion to type a for loop) and too narrow (a hand-written PR from someone who can't answer questions about it is the same problem). So whatever we write down should target the behavior, not the tool.

On AGENTS.md / CLAUDE.md: I'm skeptical these do much for the cases that hurt. The people generating drive-by "I'd like to work on this issue" comments and unreviewed patches are not the people reading repo instruction files, and agents follow them inconsistently at best. It's also another file to keep in sync with CONTRIBUTING.md, and a stale one is worse than none.

That said, I don't think it's harmful either, and there's precedent for doing it well — uutils/coreutils has a short one that's basically "here are the rules, you are responsible for your agent's output, go read CONTRIBUTING.md." Something in that shape — a pointer, not a second copy of the policy — is the only version I'd want.

So: yes to CONTRIBUTING.md, weak yes to a short AGENTS.md that points at it. But this needs a call from the team on the exact wording before anyone opens a PR — please don't send one preemptively.

Want me to adjust the tone (softer / blunter), or drop the AGENTS.md concession if you'd rather just say no to it?

---

Perfect. 👌

[Florian Heberl (floh96)]

Leonard Hecker (@lhecker) My intention with this discussion was to suggest creating a policy on AI to make your lives easier and for contributors to know what to expect upfront.
Yes, I did use AI to help me create the discussion, and this was a mistake on my side I see that now.
Background: English is not my native language, and I had the idea for the policy in the contributing doc and wanted to suggest it to you quickly.
This discussion has achieved its goal you're now aware of my sugestion, and it sounds like the team wants to discuss it internally, which I think is good. I'll close this here.

[Leonard Hecker (lhecker)]

If we had a policy, I suspect it would look something like this: https://forge.rust-lang.org/policies/llm-usage.html

Right now, that policy is not met at all by the people in this repository. Your discussion? Instant violation.
It is frustrating that people need a written policy to show a modicum of decorum. There's no doubt in my mind that once we adopt a policy it will not change anything, because it's like a single stop sign in an otherwise lawless country. No one's gonna stop.

[James Holderness (j4james)]

Leonard Hecker (@lhecker) For the record, I'd be very happy to see an AI policy on this repo like the rust one you linked, even if it did nothing to stop the actual violators. Because it at least lets other human contributors know the project's stance on the subject. When you're seeing a flood of slop PRs, it's reassuring to know that they will eventually be rejected, even if that might take some time.

It might also make it easier for maintainers to manage these PRs/issues if you can simply close them with a link to the policy, without having to add a new explanation each time.

[Mike Griese (zadjii-msft)]

Yes, I agree. We do need to make our position more clear. I've been trying to draft up some guidance in my free time for what the terminals contribution policy should be in a 2026 and beyond world. The challenge is that our org is responsible for maintaining a bunch of different projects here at Microsoft. The terminal, PowerToys, Winget, etc. etc. So drafting an updated contribution policy for terminal needs to be done within the context of all of these projects that are org owned. I can't just make a statement about what the terminal's contribution policy should be. It needs to be made within a framework of how these different repos who are going to want different approaches to AI contributions might want to accept them.

For example, with PowerToys, the bar for AI contributions is much lower. It's a project that is much more freely able to experiment and try out new ideas. And the problem space of Power Toys is very large with a very diverse set of maintainers. So AI contributions are much easier to accept to that set of tools.

Conversely, something like terminal. Terminal and conhost are core operating system components. The bar for quality for contributions here is very high. Not only that, but our maintenance responsibility to keeping the quality of the product high is also very high. We can't just blindly allow folks to fire off AI contributions every day for every new issue that is filed, and hope that we will have the responsiveness to be able to accept them quickly. Far too many people think that because the AI can write code for them, it can do the thinking for them. And that's not the kind of contribution we want for the terminal. Hence why we're going around to issues that are filed and just blindly stating that folks shouldn't use language models to file PRs for them. There's too large a category of people who just click on the most recent issue filed to the terminal, say, "Well, an AI can fix that", and then fire off a PR. We simply do not have the bandwidth to review AI PRs for all of these things, especially when it is very demonstrable that the users who are filing these PRs have not bothered to read the code themselves.

We also don't want to take the approach that entirely locks out AI contributions. We are cognizant of the fact that here in 2026 with these latest frontier models, the code that is produced is fairly good, and it can be an incredibly useful tool for debugging and building out features quicker than could otherwise be done by hand. Hell I've used it in some of my most recent terminal PRs. But when we are drafting a contribution policy for the terminal, it needs to be focused on making sure that both

• the person filing the PR understands what the code they're submitting does, and
• we as maintainers are able to accept the burden of reviewing and then further owning that code.

Terminal is a project where human beings have to own every single line of code that is in the product. Someone has to understand what's going on, what it's doing. And if we can't do that, then we can't accept these contributions. So the minimum bar for those contributions is that we are not the first people to review the code. This unfortunately happens more often than not with AI contributions.

Frankly if folks used AI to draft up high-quality PRs where it was clear that they

• tested the code themselves
• understood what it was doing

(yes I know this is an unbelievably low bar) then we probably wouldn't even give a shit if it was AI or not.
We also do not have the bandwidth to walk folks through contributing when it's clear they're just going to take what we say and plug it into a language model anyways.

Leonard mentioned the Rust LLM usage guide. That's probably close to what we'll use here in Terminal going forward.

Regrettably, Terminal is like, my fourth highest priority at this point 🫤. I need to burn down another project so I can get to authoring this contribution framework.

(I hope I didn't get too rant-y by the end here)