Ok

Which makes sense, if you want some standards across contributions. Setting aside that agent assisted contribution itself is questionable, as long as it is happening, a universal agents file is probably helpful.

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.

As they should. It’ll make better ai commits and reduce time needed for review.

Or you know, stop fucking accepting them.

No, that’s an unrealistic reactionary view which fails to address the gains that can be had, has no way to be enforced, and is a short sighted take.

Agents md file doesn’t actually do anything except using more tokens arxiv.org/pdf/2602.11988

I feel like you either didn’t read your article or didn’t read the post article

To quote the research paper conclusion…

Conclusion We evaluate the impact of context files on coding agent performance for four common coding agents on SWE-BENCH and the novel CTXBENCH, built from recent GitHub issues and less popular repositories containing developer-written context files. We find that all context files consistently increase the cost and number of steps required to complete tasks. LLM-generated context files have a marginal negative effect on task success rates, while developer-written ones provide a marginal performance gain, neither statistically significant. Our trace analyses show that instructions in context files are generally followed and lead to more test- ing and broader exploration; however, they do not function as effective repository overviews. Over- all, our results suggest that context files don’t improve coding agent performance, and should only contain specific additional instructions beyond what is already available in the codebase. This high- lights a concrete gap between current agent-developer recommendations and observed outcomes, and motivates future work on principled ways to automatically generate concise, task-relevant guid- ance for coding agents.

That sounds like “Agents.MD doesn’t work” to me.

Am I missing something?

Agents.md doesn’t exist to make sure generated code functions, it’s there to make sure it’s written well.

What is the difference between the models writing code “well” and their performance in this context? Are we referring to readability?

Genuine question. If we use agents to read, edit, and review code, why do we care about readability? That’s a human constraint. Unless attempting to do those three is not effective and thus requires human attention to correct issues which would justify readable code. If that’s the case; why use the agent to edit the code in the first place?

If that’s the case; why use the agent to edit the code in the first place?

Agents for generation, humans for review

One, that sounds truly miserable.

Two, there is a decent body of evidence to suggest that this method does not actually speed up development unless you go full lights out software factory which… Why would you want to do that?

ide.mit.edu/insights/ai-productivity-and-roi/

EDIT: As an aside this actually reminds me of the Xerox park study into efficiency gains for keyboard heavy workflows vice mouse heavy workflows. Keyboards were perceived as faster by subjects but when actually measured the mouse was faster.

That’s just because I need to stop and appreciate my efficiency for 10 seconds every time it saves me 10 seconds :-)

You joke but that’s basically the conclusion of both the newer agent studies and the older Xerox park study on peripheral use. Language and logic are stored in an easier to access location in the brain than the kinds of skills used in architecture and planning.

To be clear, I’m no rube. I recognize that these are powerful tools. But I suppose my take here is that if an LLM is necessary to get rid of a lot of the boilerplate and setup for a task that indicates we should explore how we’re doing the task.

What I want to see is using these tools not to delegate our problem solving but finding ways to enhance and accelerate it and I don’t think writing spec sheets is the answer.

I think you’re correct, the amount of rigor in your prompts seems orthogonal from whether you’re using them for architecture or implementation.

“Writing code well” includes several relavant things:

• Security implications
• Stability and edge case handling
• Performance
• Quality of output (ie. for UI/UX)
• Readability (Agents need to read to make changes too! Violating DRY/SOLID/etc. could still cause issues!)

As far as I’m aware you do currently still need a human to ensure stuff like this is followed. People use agents because they don’t care about the above, or because they can get close enough and intervene to fix any issues that appear.

your research paper:

llm generated agent.md files are harmful. handwritten ones on average don’t have an effect on ability to complete a task

thread article:

agents keep signing off on commits wrong. we added it to the agents.md and now they don’t

benchmarks notoriously don’t measure the likelihood that the results would be merged by maintainers, just that they passed a test

the old style “repo map” agents.md files that every tool used to create is no longer useful, but of course things that would otherwise be repeated prompts are still good. I cut the ones at work down from hundreds of lines each to tens. without those last few lines the amount of iteration I do - both with agent and when reviewing PRs - goes up significantly

BSD here i come.

Everywhere I go I started leaving AGENTS.md files. I feel like the future needs some reliability and stability as LLMs help us improve everything we do. So if your agent replies with a bunch of shit emojis or an ASCII art of a beautiful veiny dick then you can thank this guy and is AGENTS.md files. You’re welcome.

We’re gonna have to end up using TempleOS to avoid this AI bullshit arent we.

Or one might try BSD before installing TempleOS… BSD might just do the trick.

BSD is too usable. will have AI in it before long.

Have at it.

There should be one that bans ai from the repo

This is being proposed so that the bot doesn’t have to read the entire README file. Humans are supposed to do it but the bot replacing them does not. Makes sense to me.

Surely this will improve code quality for the single most important piece of software in existence today.

What would end up in it, though? The kernel has a lot of conventions that are enforced by reviewers rather than written down anywhere. An AGENTS.md that only restates the documented ones saves nobody anything. I doubt the maintainers want to write down the stuff they currently catch by instinct, like which subsystem takes which kind of patch. If they don’t, the file becomes a style guide nobody reads, same as the coding style doc is for most first-time contributors.