I don’t get why agents.MD needs to be committed. It feels a bit like committing IDE settings, everyone is going to have slightly different preferences, so its better to just have everyone do their own thing. If anything, I prefer to .gitignore itso it doesnt get accidentally committed.

Like formatters and git ignore configuration, some agent instructions are personal and those should not be commited. But some are worth sharing. Having formatter config in a repo is not uncommon. And in this case the file is only a link to the readme, so the agent reads the contrib guidelines.

I’m on board with committing formatter config, because thats deterministic and really should be shared amongst a team.

I don’t get why the agent needs to have the contrib guidelines, it should be a human doing the actual contrib part, so its just a waste of tokens for the LLM to read it?

Waste of tokens for the agent to make changes that the human then changes to comply with contrib guidelines. Potentially a smaller number used to read in some guidelines and get closer to correct in the first place.

I don’t get why the agent needs to have the contrib guidelines, it should be a human doing the actual contrib part, so its just a waste of tokens for the LLM to read it?

Why would you want to waste the tokens required to generate a subpar response that will either require the user to undo a potentially significant portion of what was generated, or you’ll end up using more tokens while the operator tries to get the AI to obey the standard (before they inevitably tell the stupid thing to follow the guide themselves later, anyway)?

At least for the specific example given, I want developers to do the commit part themselves, so if their LLM is doing any part of that, its already a mistake IMO.

I had a very quick look at the AI agent guidelines, and nothing about them strikes me as overly burdensome for a human to fix up. So I’d rather just do that myself (if I were a kernel dev).

My main objection is forcing it on developers, it should be up to each dev to configure and manage their own agent. Making it a suggestion is fine, just don’t commit it. Also, if developers are using local hosted models, then context may be quite limited, so wasting it on an Agents.MD maybe be unideal.

A contributor still has global config for their personal preferences. It makes sense to me, anyway. My biggest issue is it’s not deterministic. Someone else could have a version that works better or uses fewer tokens for the same thing.

At work we commit the whole .claude folder, though we carve out some space for personal agents and skills.

For agents (semi-autonomous) I think it’s more similar to introductory developer docs. Which are usually committed.

I get that analogy. However, I would heirarchaically place the agents as subordinates to the developer, which is why I would expect each developer to institute their own customised agents.md file, rather than it being dictated from the repo, which is a level removed.

You’d put the things that aren’t up to personal preference in there, like an AI disclosure / contribution policy or what changes should look like to be reviewable. You usually don’t need to tell humans “don’t change things for the sake of changing them” because we don’t like to do more work than we have to, but agents do.

You can also include a compact “table of contents,” describing what lives where in the project. It saves at most a little bit of exploration though so I don’t know if it’s really worth the maintenance

but agents do

Depends on the model, Gemma 4 is extremely lazy in my experience, half the time it won’t finish the task properly anyway. Deepseek (not sure of the version) was crazily overactive. I personally prefer Gemma’s laziness, because it avoid making the chaotic changes that need to be rolled back, but thats a personal preference.

And thats kinda why I don’t like it being committed. If the entire team is using one model, then sure, commit the agents.md, and everyone gets a sane default, but given this is a multi-developer project with likely many different agents and models in use, it makes more sense to me that each developer manages the agents.md themselves and optimises it for their own model/workflow.

You do definitely need some agent-specific guidance locally. The committed AGENTS.md should be pretty sparse. Ironically I think the clearest use case is for instructing agents that AI contributions are not allowed. Not that they won’t ignore it if prompted.