Add an AGENTS.md pointing to our policy

[StanFromIreland]

Please don't pull out your pitchforks just yet 😅

I know adding an AGENTS.md has been discussed and rejected in the past. However, what I'm proposing here is much more limited. I want to add a short AGENTS.md that points to our existing AI policy, with no additional recommendations, instructions, skills, or anything else like that.

I've heard that this approach has been quite successful for several projects (for example, Rust) and it should hopefully make it more likely that both users and agents actually see and follow the existing policy.

It seems better than having nothing here, and avoids the previous concerns. Hopefully this is small and uncontroversial enough to be worth trying. We can always add more things here in the future. Quoting Martin Luther King Jr., "you don't have to see the whole staircase, just to take the first step."

[johnslavik]

cc @gpshead @ambv

[johnslavik]

Do we want to symlink CLAUDE.md to this?

[StanFromIreland]

Do we want to symlink CLAUDE.md to this?

From what I understand based on Greg's previous comments, Claude should be smart enough to check this one as well. So for now I think we can do without?

[picnixz]

I appreciate this. We should also update our devguide guidelines if necessary

[maurycy]

I think it's a good call.

[gpshead]

I suggest using .claude/ to contain the symlink back to AGENTS.md and long term maybe .agents/skills/ similar to the structure you see in, for example, https://github.com/coredevices/PebbleOS/tree/main/.claude

it'll be invisible locally to most people by virtue of being in a hidden .claude/ tree - BUT first we need to also address

cpython/.gitignore

Line 182 in d16a691

/.claude/

and change that to exclude the paths that many core team folks likely now have laying around per the https://github.com/gpshead/cpython-skills/blob/main/plugins/cpython-skills/skills/dev/SKILL.md instructions. (/.claude/pr-* /.claude/branch-* /.claude/sandbox/ and add AGENTS.local.md and to that list and get rid of the link to the claude docs.

mind if i just push that as a commit on this PR since I know what needs to happen?

---

We had a conversation at the europython language summit about adding such a thing and people were a mix of generally onboard and agreeing that it'd help make things go better, or unwilling to voice opposition. Including adopting a fork of my gpshead/cpython-skills as official for use with the cpython repo to make things in general go better for people (though we'll probably want to leave the skills outside of the repo - all skill stuff will be followup work).

[picnixz]

I would rather have a single AGENTS.md file if possible than lots of symlinks. Aren:t agents told to actually read this instead of their dedicated file? People could also consider that .claude is a way for CPython to endorse it officially (leaving other agents unendorsed for instance).

[StanFromIreland]

I suggest using .claude/ to contain the symlink back to AGENTS.md and long term maybe .agents/skills/

Greg, as I noted in the description, I'd prefer to try and keep this as simple as possible. Seeing as this is already raising objections, I'd prefer to land this, and make such changes in a follow-up (or as part of @ambv 's plan to create a proper file here with instructions and such things). Is that alright with you?

[gpshead]

IMNSHO we should not add agents.md without also adding the trivial claude link to it because claude code still doesn't read agents.md by default so it won't do as much good to have this in the repo without that. this shouldn't be a hot button issue or seen as an endorsement.

practicality beats purity here, it should lead to more consistent outcomes.