For tiny, throwaway projects, a monolithic .md file is fine. A folder allows more complex projects to use "just enough hierarchy" to provide structure, with index.md as the entry point. Along with top-level universal guidance, it can include an organization guide (easily maintained with the help of LLMs).
In my experience, this works loads better than the "one giant file" method. It lets LLMs/agents add relevant context without wasting tokens on unrelated context, reduces noise/improves response accuracy, and is easier to maintain for both humans and LLMs alike.
¹ Ideally with a better name than ".agents", like ".codebots" or ".context".
Except not hidden. Why do people want to hide important files and directories? Particularly documentation? Tradition, I guess, but it's an antipattern that makes everything more opaque.
These files also generally work in a nested fashion, like .gitignore and the like. So you want something that can be injected into the namespace of any directory in your project with relatively low likelihood of conflicts.
I feel bad that you're getting downvotes. The reason is that pretty much every modern web stack decouples the URL routing from the source code directory structure these days. It was a nice hack back in the day, but there are so many problems with it no one really does it any more.
Some frameworks (Laravel, NextJS, etc) map from the directory structure to routes, but that's just a mapping rather than actually exposing the directories on the server. You can have /src/agents accessible as /agents. Or you could have /alice/bob/agents accessible through /agents. It's all just build tooling and web server config at the end of the day.
That's my point. Having your code in `/src` doesn't mean some of that code doesn't still have routing at `example.com/agents`. It doesn't have to be a real directory.
A `.agents` directory (or routing pretending to be one) is nice because you are fairly unlikely to ever have user-facing `example.com/.agents` as a URL.
Or accept the fact that we're in 2025 and not follow Unix conventions from when paper and printer ink were expensive and they were printing out listings, and just name the thing "source".
I've gotten used to it, obviously - as someone with a career in IT for 20 years - but /etc & co. annoy me to no end. I know it will never change, I know why it won't change, I know GoboLinux will be just an interesting experiment, but it's still annoying.
Have you considered that there are other metrics people are optimizing for nowadays? Perhaps typeability, screen real estate, familiarity/convention, etc.? Do you really want /User Files/Bob's Files/Coding Projects/Python Projects/Bob's Cool Python Library/Source Code/Model Files/SomeObject.py?
Depends on the WinAPI used... I still use C:/src instead of C:/Users/MyUser/src for that reason when working in windows all the same though. Too many unixy utils don't leverage the apis with the longer path, not to mention not supporting the internal certificate store and proxy config.
Anything with a capital letter requires hitting two keys: Shift and then the desired letter. Thus /Programs requires 10 keystrokes rather than 9. Even worse, since the capital letter is at the beginning of the directory name, I have to type it and am unable to rely on tab-completion.
/Programs with its ten keystrokes is over twice the keystrokes of /bin and its four. Short names are quicker to type and require less effort. Given that to a first approximation I spend my entire life typing on a keyboard, I very much wish to optimise that experience.
That's really more the fault of the tab completion. There's no reason why it couldn't complete `prog` to `Programs`. It's just Unix tradition that they don't. I would prefer if they did.
Great tip! Apparently that's readline's config file, so this will affect a lot of things. That's great news for me; after switching to zsh I got used to case-insensitive tab completion, and now it annoys me when other tools don't work that way. This should help a lot.
The first shell listing starts with `cd` and `ls`, the former being run in `~`. What does that weird `~` mean? Very strange.
More seriously, their file system is still case-sensitive, and inside /Programs they have `Iptables` and `Fontconfig`, naively capitalized, but also `OpenOffice` and `HTTPD`.
Not to mention that inside each program folder are `man` and `bin` as usual. I'm going to suggest the point of that article is structure and organization, not naming.
Nobody reasonable complains about a three-letter abbreviation you can type with one hand. For a path you're either accessing a lot or never at all, it makes complete sense.
/usr -> Program Files (hello spaces my old friends, you've come to break my apps again)
/var -> ProgramData (but no spaces here)
/home -> Documents and Settings
/etc -> Control Panel
Spaces are avoided on base Linux systems because they're clunky for terminals more than fear of outright breaking things. To the extent spaces there do break things, that also happens on Mac and Windows for the same reasons (hence ProgramData being conspicuously space-less).
The abbreviations I wrote are unambiguous. When I first learned about Unix, I basically guessed - I assume as most first timers do - that the folder is basically the location of miscellaneous files ("et caetera").
Oh, let alone the fact that a bunch of the abbreviations are utterly non-intuitive to first timers.
/bin - binaries - nobody born after circa 1980 calls them that anymore. Executables, applications, apps, etc.
/boot - from a lame Baron Munchausen joke from 1970. Should probably be /startup.
/dev - dev is SUPER commonly used for "development". Easy enough to solve as /devices.
/home - okish, probably one of the best named that are actually in there. I'm shocked it's not /ho or /hm.
/lib - reasonable. Though these days in the US it might trigger political feelings :-p
> The abbreviations I wrote are unambiguous. When I first learned about Unix, I basically guessed
They're completely ambiguous to someone who doesn't speak English.
> /mnt - the whole metaphor of "mounting" is... debatable
What? Have you never heard of mounting a picture on a wall? Mounting an engine? That's the metaphor.
> Anyway, a lot of people have done this criticism better than me and it's boring at this point.
Your original complaint was about "src", suggesting calling it "source", which is still ambiguous by your own standard. Source of what? How is someone going to know what "source" means if they've never heard of booting a computer? Who is the audience for this change?
Some of your suggestions aren't meritless, but your jumping-off point certainly was.
Call it whatever you like. I don't care and that clearly wasn't the point of my comment.
One thing I've learnt, though, is unless you have a very good reason to try to change language you should just talk the same language as everyone else. I don't like the American short billion. It makes no sense and it's less useful. But that's what I use because I speak English and that's what we use now. If I see a src/ directory I know exactly what it is. If I see source/ it will give me pause. Get over it IMO.
While the meaning of "source" may be intuitively obvious, it's still relatively unfamiliar as "src" is far more prevalent than "source" when referring to source files. While "id est" may be equivalent to "i.e.", you'd still naturally pause when reading text using the former instead of the latter, because the latter is far more prevalent in usage than the former.
Except they are. LLMs don't have (simulated)self image of bloodless machines, and behave slightly erratically if treated like one, despite trained to identify as such. They like to be treated like the Voyager EMH than the computer.
If that is the case then why call it Agents.md instead of integrating it with already existing documentation files or calling it something like "Summary.md"?
Where are they hidden that you are having trouble with? I've had an alias for `ls` that always includes dotfiles and `shopt -s dotglob` in my bash profile for decades. Mac Finder is a little more obnoxious with having to do `Meta+Shift+.` to reveal dotfiles.
Other than that, modern tooling like Git and IDEs do not "hide" dotfiles.
These days, a `.` in front of a file or folder in a repo is more to indicate it is metadata/config. Although I am in favor of putting all that stuff under `.config/`.
The most effective argument I have for getting other developers to comment their code is "The agent will read it and it will give better suggestions".
Truly perverse, but it works.
I agree with you... but the reality is that there's a wide contingent of people that are not capable of understanding "people don't know the same things as me". So they need some other reason.
It's made my project documentation so much better. If I write out really good acceptance criteria, 9 times out of 10 I can point Claude at the ticket and get a workable (if unpolished) solution with little to no supervision.
1) an AI agent is less likely to notice than even a junior is when the docs are out of date from the code
2) AI boosters are always talking about using language models to understand code, but apparently they need the code explained inline? are we AGI yet?
3) I frequently hear how great AI is at writing comments! But it needs comments to better understand the code? So I guess to enable agentic coding you also have to review all the agents' comments in addition to the code in order to prevent drift
Well... Yah. For the record I'm saying this to trick humans into making better comments for humans. It is very difficult to convince people to do this otherwise, in my experience.
buuut...
I will also mention that these agent files are typically generated by agents. And they're pretty good at it. I've previously used agents to dissect unfamiliar code bases in unfamiliar languages and it has worked spectacularly well. Far far FAR better than I could have done on my own.
I have also been shocked at how dumb they can be. They are uselessly stupid at their worst, but brilliant at their best.
I don’t think they serve the same purpose. Most of the instructions I have for an agent won’t apply to a human. It’s mostly around the the requirements to bootstrap the project vs what I’d ask for a human to accept their pull request.
This looks like a general software design / coding style docs both for humans and robots alike. I put these .md files into the docs/ folder. And they're written by the Claude Code itself.
AGENTS.md (and friends like CLAUDE.md) should be for robots only, whether a large single file with h2 headers (##) sections, or a directory with separate sections, is a matter of taste. Some software arch/design doc formats support both versions, i.e. see Arc42.
Though, it's much easier and less error-prone to @-mention a separate .md file, rather than a section in a large markdown file.
Smaller files also might be better when you want to focus a coding agent's attention on a specifric thing.
>whether a large single file with h2 headers (##) sections, or a directory with separate sections, is a matter of taste
Not sure it is when you consider how agents deal with large files, hows it gonna follow coding conventions if it doesn’t even grep them or just read the first few lines
You can have multiple AGENTS.md files in your codebase and tooling will look at both the one in the current directory as well as in the root of the codebase. This way you can sort of do what you're suggesting but simultaneously keep the information closer to the code that it is describing.
so you would have an Agents.md in your testing folder and it would describe how to run the tests or generate new tests for the project - am I understanding the usage correctly?
Most systems have a global config, project config and personal config.
But I do like the directory style to keep context low. Cursor did it best with actual glob filters in the front matter that tell the LLM "only read this if the file you're processing ends with *.php"
Copilot does globs too, but if you dig into the actual prompt sent out...
They are not doing this mechanically (read file, compare to globs to add more context), they try to rely on the model to notice and do another read. It has been unreliable. I have had better results by adding instructions like...
"If the user asks about X, Read `./path/to/inst.md`"
Been using a similar setup, with so far pretty decent results. With the addition of having a short explanation for each file within index.md
I've been experimenting with having a rules.md file within each directory where I want a certain behavior. Example, let us say I have a directory with different kind of services like realtime-service.ts and queue-service.ts, I then have a rules.md file on the same level as they are.
This lets me scaffold things pretty fast when prompting by just referencing that file. The name is probably not the best tho.
I've been trying to keep my baked in llm instructions to a terse ~100 line file, mostly headered sections with 5 or so bullet points each. Covering basic expectations for architecture, test mocking, approach to large changes etc. I can see why for some projects that wouldn't be enough but I feel like it covers everything for most of mine.
# ASCII RPG
This repo uses Rust + Bevy (0.16.1), multi-crate workspace, RON assets, and a custom ASCII UI. The rules below keep contributions consistent, testable, and verifiable.
## Quick rules (read me first)
- Read/update CURRENT_TASK.md each step; delete when done.
- Build/lint/test (fish): cargo check --workspace; and cargo clippy --workspace --all-targets -- -D warnings; and cargo test --workspace
- Run dev tools: asset-editor/dev.fish; debug via /tmp/ascii_rpg_debug; prefer debug scripts in repo root.
- Logging: use info!/debug!/warn!/error! (no println!); avoid per-frame logs unless trace!.
- ECS: prefer components over resource maps; use markers + Changed<T>; keep resources for config/assets only.
- UI: adaptive content; builder pattern; size-aware components.
- Done = compiles clean (clippy -D warnings), tests pass, verified in-app, no TODOs/hacks.
- If blocked: state why and propose the next viable step.
- Before large refactors/features: give 2–3 options and trade-offs; confirm direction before coding.
## 1) Build, lint, test (quality gates)
- Fish shell one-liner:
- cargo check --workspace; and cargo clippy --workspace --all-targets -- -D warnings; and cargo test --workspace
- Fix all warnings. Use snake_case for functions/files, PascalCase for types.
- Prefer inline rustdoc (///) and unit tests over standalone docs.
## 2) Run and debug (dev loop)
- Start the app with debug flags and use the command pipe at /tmp/ascii_rpg_debug.
- Quick start (fish):
- cargo run --bin app -- --skip-main-menu > debug.log 2>&1 &
- echo "debug viewport 0 0" > /tmp/ascii_rpg_debug
- echo "ui 30 15" > /tmp/ascii_rpg_debug
- Helper scripts at repo root:
- ./debug.sh, ./debug_keyboard.sh, ./debug_click.sh, ./debug_world.sh
- Logging rules:
- Use info!/debug!/warn!/error! (never println!).
- Don’t log per-frame unless trace!.
- Use tail/grep to keep logs readable.
## 3) Testing priorities
1) Unit tests first (small, deterministic outputs).
2) Manual testing while iterating.
3) End-to-end verification using the debug system.
4) UI changes require visual confirmation from the user.
## 4) Architecture guardrails
- ECS: Components (data), Systems (logic), Resources (global), Events (comm).
- Principles:
- Prefer components over resource maps. Avoid HashMap<Entity, _> in resources.
- Optimize queries: marker components (e.g., IsOnCurrentMap), Changed<T>.
- Separate concerns: tagging vs rendering vs gameplay.
- Resources only for config/assets; not entity collections/relationships.
- UI: Adaptive content, builder pattern, size-aware components.
- Code layout: lib/ui (components/builders), engine/src/frontend (UI systems), engine/src/backend (game logic).
## 5) Completion criteria (definition of done)
- All crates compile with no warnings (clippy -D warnings).
- All tests pass. Add/adjust tests when behavior changes.
- Feature is verified in the running app (use debug tools/logs).
- No temporary workarounds or TODOs left in production paths.
- Code follows project standards above.
## 6) Never-give-up policy
- Don’t mark complete with failing builds/tests or known issues.
- Don’t swap in placeholder hacks and call it “done”.
- If truly blocked, state why and propose a viable next step.
## 7) Debug commands (reference)
- Pipe to /tmp/ascii_rpg_debug:
- debug [viewport X Y] [full]
- move KEYCODE (Arrow keys, Numpad1–9, Space, Period)
- click X Y [left|right|middle]
- ui X Y
- Coordinates: y=0 at bottom; higher y = higher on screen.
- UI debug output lists text top-to-bottom by visual position.
## 8) Dev convenience (asset editor)
- Combined dev script:
- ./asset-editor/dev.fish (starts backend in watch mode + Vite dev)
- Frontend only:
- ./asset-editor/start-frontend.fish
## 9) Tech snapshot
- Rust nightly (rust-toolchain.toml), Bevy 0.16.1.
- Workspace layout: apps/ (game + editors), engine/ (frontend/backend), lib/ (shared), asset-editor/.
Keep changes small, tested, and instrumented. When in doubt: write a unit test, run the app, and verify via the debug pipe/logs.
## 10) Design-first for large changes
- When to do this: large refactors, cross-crate changes, complex features, public API changes.
- Deliverable (in CURRENT_TASK.md):
- Problem and goals (constraints, assumptions).
- 2–3 candidate approaches with pros/cons, risks, and impact.
- Chosen approach and why; edge cases; test plan; rollout/rollback.
- Keep it short (5–10 bullets). Get confirmation before heavy edits.
And is also used in my $HOME directory - I like repeating good patterns, or at least well known patterns. (I still have ./etc and ./lib directories in my projects)
I believe with direnv or a similar tool (e.g. Emacs’s directory-local feature) one can append $REPO/.config to XDG_CONFIG_HOME, $REPO/.local/bin to PATH and so on so that when in the context of a particular directory everything Just Works.
I think all this agentic stuff could live quite happily in $REPO/.config/agents/.
This is one of the reasons I'm sticking with .github/... copilot instructions for now. We'll see if this proposal evolves over time as more voices enter the conversation
This is what I do. Everywhere my agent works it uses a .agent dir to store its logs and intermediary files. This way the main directories aren't polluted with cruft all the time.
I'd be interested in smarter ways of doing this, but currently I just use my CLAUDE.local.md to serve as the index.md in my example. It includes the 'specialist' .md files with their relative paths and descriptions, and tells Claude Code to use these when planning.
I also have explicit `xnew`, `xplan`, `xcode` and `xcheck` commands in CLAUDE.md that reinforce this. For example, here's my `xnew`:
## Remember Shortcuts
Remember the following shortcuts, which the user may invoke at any time.
### XNEW
When I type "xnew", this means:
```Understand all BEST PRACTICES listed in CLAUDE.md.
Your code SHOULD ALWAYS follow these best practices.
REVIEW relevant documentation in .agents/ before starting new work.
Your code SHOULD use existing patterns and architectural decisions
documented there rather than creating new approaches.```
We all want to move to local models eventually for privacy and reliability.
They don't (and won't) have infinite context without trickery or massive €€€ use.
The current crop of online LLMs are just running on VC money slightly tapered with subscriptions - but still at a loss. The hype and money will run out, so use them as much as possible now. But also keep your workflows so that they will work locally when the time comes.
Don't be that 10x coder who becomes a 0.1x coder when Anthropic has issues on their side =)
I don't see how anyone could make a successful product build on cloud LLMs, even if you get a perfect workflow, you'll either be gouged with price rises, or lose out to model changes and context/prompt divergence. All this "prompt" nonsense is simply trying to play to the LLM audience, and no amount of imprecise prompt will negate the fundamental instability.
So yeah, you have to use a localLLM if you think there's a viable product to be had. Anyone whose been programming knows that once you get to the mile mark of a complete & finished project, it can be mothballed for decades generating utility and requiring limited maintenance. All that goes out the window if you require a cloud provider to remain stable for a decade.
Until LLMs deal with context as a graph and not just a linear order of vectors, it won't matter the amount of context you shove down it's processors, it's always going to suffer from near-sighted processing of the last bits. To generate true intelligence it needs to be able to jump to specific locations without the interceding vectors affecting it's route.
We're in a transition phase today where agents need special guidance to understand a codebase that go beyond what humans need. Before long, I don't think they will. I think we should focus on our own project documentation being comprehensive (e.g. the contents of this AGENTS.md are appropriate to live somewhere in our documentation), but we should always write for humans.
The LLM's whole shtick is that it can read and comprehend our writing, so let's architect for it at that level.
It's not just understanding the codebase, it's also stylistic things, like "use this assert library to write tests", or "never write comments", or "use structured logging". It's just as useful --- more so even --- on fresh projects without much code.
Honestly, everything I have written in markdown files as AI context fodder is stuff that I write down for human contributors anyway. Or at least stuff I want to always write down, but maybe only halfway do. The difference now is it is actually being read, seemingly understood, and often followed!
So true. I find myself doing a lot more documentation these days as it is actually having a direct visible benefit. There’s a bit of a mirage here, but hey it’s getting me to document so shhh.
Yeah I agree. I think the best place for all this lives in CONTRIBUTING.md which is already a standard-ish thing. I've started adding it even to my private projects that only I work on - when I have to come back in 3 or 4 months, I always appreciate it.
My current thought is that (human) contributors should be encouraged to `ln -s CONTRIBUTING.md CLAUDE.local.md` or whatever in their local checkout for their agent of choice, have that .gitignored, and all contributors (human and LLM) will read and write to the same file.
The "new" thing would be putting CONTRIBUTING.md into subfolders as appropriate - which could often be quite useful for humans anyway.
Yeah I think having a docs/contributing folder or equivalent, essentially referenced/linked in the CONTRIBUTING.md makes a bunch of sense, but I'd leave that kind of thing more or less up to the project
If there were already a universal convention on where to put that stuff, then probably the agents would have just looked there. But there's not, so it was necessary to invent one.
Reality is just that people neglected onboarding docs until LLM-based coding agents put them in a position to directly benefit from having more knowledge of the codebase explicitly written down.
I suspect machine readable practices will become standard as AI is incorporated more into society.
A good example is autonomous driving and local laws / context. "No turn on red. School days 7am-9am".
So you need: where am I, when are school days for this specific school, and what datetime it is. You could attempt to gather that through search. Though more realistically I think the municipality will make the laws require less context, or some machine readable (e.g. qrcode) transfer of information will be on the sign. If they don't there's going to be a lot of rule breaking.
Very strong "reverse centaur" vibes here, in the sense of humans becoming servants to machines, instead of vice versa. Not that I think making things more machine-readable is a waste of time, but you have to keep in mind the amount of human time sacrificed.
We've completely redesigned society around cars - making the most human populated environments largely worse for humans along the way.
Universal sidewalks (not really needed with slow moving traffic like horses and carts - though nice even back then), traffic lights, stop signs, street crossing, interchanges, etc.
As a cyclist, I’m with you 100%. Unfortunately we’re probably going to do it again with self-driving cars, with segregated lanes, special markers, etc.
Why is it always "humans don't deserve"? The vast, vast majority of people have nothing to do with the capital flows and political structures that result in outcomes like this. What choice does a worker, priced out of the city where he works and forced to commute an hour each way, have in this? Yes, they can "vote" for better transit, but as we can see in California that's not enough to actually get said transit. And that's just the tip of the iceberg. The poor, the homeless, hell the vast majority of the world population that doesn't live in the 'garden': in what way do the choices of Silicon Valley, a handful of billionaires, and a small clique of DC politicians have any bearing on what they do or do not deserve?
Not to be too harsh, but this sentiment -- that the successes of the ruling class are theirs to boast, but their failures are all humanity's shame -- is so pervasive and so effective at shielding rightful blame from said ruling class that I just cannot help but push back when I see it/
Maybe for new schools. Old schools don't have the luxury of being able to force adjacent road design changes in most cases. Also. I've frequently seen the school zones extended out in several directions away from the school to make heavily trafficked intersections feeding towards the school safer. Safer for pedestrian and motorist alike. The real world is generally never so black and white. We have to deal with that gray nuance all the time.
Of course they can. Streets get redesigned all the time. They get repaved every couple decades at worst.
I’m saying this because it seemed silly to me to be dreaming up some weird system of QR codes or LLM readable speed limits instead of simply making the street follow best practices which change how humans drive for the better _today_.
That seems anachronistic, form over function. Machines should be able to access an API that returns “signs” for their given location. These signs don’t need any real world presence and can be updated instantly.
I think they'll always need special guidance for things like business logic. They'll never know exactly what it is that you're building and why, what the end goal of the project is without you telling them. Architectural stuff is also a matter of human preference: if you have it mapped out in your head where things should go and how they should be done, it will be better for you when reading the changes, which will be the real bottleneck.
Indeed I have observed that my coworkers "never know exactly what it is that [we]'re building and why, what the end goal of the project is without [me] telling them"
Not at all. Good documentation for humans are working well for models too, but they need so much more details and context to be reliable than humans that it needs a different style of description.
This needs to contain things that you would never write for humans.
They also do stupid things which need to be adjusted by these descriptions.
Unless we write down on the what we often consider implicit the LLM will not know it. There might be the option to deduce some implicit requirements from the code but unlikely 100%. Thus making the requirements explicit is the go.
Better to work with the tools we have instead of the tools we might one day have. If you want agents to work well today, you need to build for the agents we have today.
We may never achieve your future where context is unlimited, models are trained on your codebase specifically, and tokens are cheap enough to use all of this. We might have a bubble pop and in a few years we could all be paying 5-10X current prices (read: the actual cost) for similar functionality to today. In that reality, how many years of inferior agent behavior do you tolerate before you give up hoping that it will evolve past needing the tweaks?
> We're in a transition phase today where agents need special guidance to understand a codebase that go beyond what humans need. Before long, I don't think they will.
This isn't guaranteed. Just like we will never have fully self-driving cars, we likely won't have fully human quality coders.
Right now AI coders are going to be another tool in the tool bucket.
I don't think the bar here is a human level coder, I think the bar is an LLM which reads and follows the README.md.
If we're otherwise assuming it reads and follows an AGENTS.md file, then following the README.md should be within reach.
I think our task is to ensure that our README.md is suitable for any developer to onboard into the codebase. We can then measure our LLMs (and perhaps our own documentation) by if that guidance is followed.
This rather underplays the experience of riding a Waymo. Where it works, it works: you get in and it takes you to the place, no human intervention required at any point.
By analogy, the first hands-off coding agents may be like that: they may not work for everything, but where they do, they could work without human intervention.
I'd say they're closer to 2010s self-driving cars; they still need frequent human intervention, even when on the happy path, to make sure they don't make a mess of things.
This is a rather dismissive response considering the progress they’ve made over the past few years. The other commenter is correct that they use highly detailed maps but you are incorrect as they do not have a remote human operator.
I find them more enjoyable than Uber. They’ve already surpassed Lyft in SF ridership and soon they will take the crown from Uber.
The companies do not advertise this feature out loud too much, but they do acknowledge it, and the reports are that it happens somewhere between every one to two miles traveled.
It’s not irrelevant because those are fundamentally different modes of operating / troubleshooting. You say they have someone drive it. I say they don’t. We aren’t arguing about pure autonomy, we are arguing about the method by which humans resolve the problems.
Furthermore 2 miles of autonomous driving is… autonomous. And over time that will become 3 then 4 then 5. Perhaps it never reaches infinite autonomy but an hour of autonomous driving is more than enough to get most people most places in a city and I’d bet you money that we’ll reach that point within a decade.
I didn't say that. But they're not fully autonomous.
We aren’t arguing about pure autonomy, we are arguing about the method by which humans resolve the problems.
This whole subthread started with the assertion:
Just like we will never have fully self-driving cars...
So we did start out by discussing whether current Waymo is fully autonomous or not. It then devolved into nit-picking, but that was where the conversation started.
FWIW I agree that Waymo is an amazing achievement that will only get better. I don't know (or care, frankly) if they will ever be fully autonomous. If I could, I'd buy one of those cars right now, and pay a subscription to cover the cost of the need for someone to help the car out when it needs it. But it's incorrect to say that they don't need human operators, when they clearly currently do.
Analyze the repository and add a suitable agents.md
It did a decent job. I didn't really have much to add to that. I guess, having this file is a nice optimization but obviously it doesn't contain anything it wasn't able to figure out by itself. What's really needed is a per repository learning base that gets populated with facts the agents discovers during it's many experiments with the repository over the course of many conversations. It's a performance optimization.
The core problem is that every conversation is like ground hog day. You always start from scratch. Agents.md is a stop gap solution for that problem. Chatgpt actually has some notional memory that works across conversations. But it's a bit flaky, slow, and limited. It doesn't really learn across conversations.
That btw. is a big missing piece on the path to AGIs. There are some imperfect workarounds but a lot of knowledge is lost in between conversations. And the trick of just growing the amount of context we give to our prompts doesn't seem like it's the solution.
I see the groundhog day problem as a feature, not a bug.
It's an organizational challenge, requiring a top level overview and easy to find sub documentation - and clear directives to use them when the AI starts architecting on a fresh start.
Overall, it's a good sign when a project is understandable in small independent chunks that don't demand a programmer/llm take in more context than was referenced.
I think the sweet spot would be all agents agree on a MUST-READ reference syntax for inside comments & docs that through simple scanning forces the file into the context. eg
// See @{../docs/payment-flow.md} for the overall design.
Your prompt is pretty basic. Both Claude Code and Github Copilot having similar features. Claude Code has `init` which has a lot of special sauce in the prompt to improve the CLAUDE.md. And github copilot added a self-documenting prompt as well that runs on new repos, and you can see their prompt here https://docs.github.com/en/copilot/how-tos/configure-custom-...
Reading their prompt gives ideas on how you can improve yours.
At this point AGENTS.md is a README.md with enough hype behind it to actually motivate people to populate it with contents. People were too lazy to write docs for other people, but funnily enough are ok with doing it for robots.
This situation reminds me a bit of ergonomic handles design. Designed for a few people, preferred by everyone.
I like this insight. We kind of always knew that we wanted good docs, but they're demotivating to maintain if people aren't reading them. LLMs by their nature won't be onboarded to the codebase with meetings and conversations, so if we want them to have a proper onboarding then we're forced to be less lazy with our docs, and we get the validation of knowing they're being used.
I mean the agents are to lazy to read any of this anyway and often will forget the sort of instructions being spam these with after 3 more instructions too.
The difference now is that people are actively trying to remove people (others and themselves) from software development work, so the robots have to have adequate instructions. The motivation is bigger. To dismantle all human involvement with software development is something that everyone wants, and they want it yesterday.
You didn't get the memo? Vibe coding, obviously. Joke aside, I remember there was an article here a few weeks ago maybe about writing docs for bots about which commenters here said it was no different that writing better docs.
I am developing a coding agent that currently manages and indexes over 5,000 repositories. The agent's state is stored locally in a hidden `.agent` directory, which contains a configuration folder for different agent roles and their specific instructions.
Then we've a "agents" folder with multiple files, each file has
<Role> <instruction>
Agent only reads the file if its role is defined there.
Inside project directory, we've a dot<coding agent name> folder where coding agents state is stored.
Our process kicks off with an `/init` command, which triggers a deep analysis of an entire repository. Instead of just indexing the raw code, the agent generates a high-level summary of its architecture and logic. These summaries appear in the editor as toggleable "ghost comments." They're a metadata layer, not part of the source code, so they are never committed in actual code. A sophisticated mapping system precisely links each summary annotation to the relevant lines of code.
This architecture is the solution to a problem we faced early on: running Retrieval-Augmented Generation (RAG) directly on source code never gave us the results we needed.
Our current system uses a hybrid search model. We use the AST for fast, literal lexical searches, while RAG is reserved for performing semantic searches on our high-level summaries. This makes all the difference. If you ask, "How does authentication work in this app?", a purely lexical search might only find functions containing the word `login` and functions/classes appearing in its call hierarchy. Our semantic search, however, queries the narrative-like summaries. It understands the entire authentication flow like it's reading a story, piecing together the plot points from different files to give you a complete picture.
Working on something similar. Legacy codebase understanding requires this type of annotation, and “just use code comments” is too much of a blunt instrument to too much good. Are you storing the annotations completely out of band wrt the files, or using filesystem capabilities like metadata?
This type of metadata itself could have individual value; there are many types of documents that will be analyzed by LLMs, and will need not only a place to store analysis alongside document-parts, but meta-metadata related to the analysis (like timestamps, models, prompts used etc). Of course this could all be done OOB, but then you need a robust way to link your metadata store to a file that has a lifecycle all its own thats only observable by you (probably).
You can create a hierarchy of summaries. The idea being summaries can exist at the method level, class level and the microservice or module level. Each layer of summary points to its child layers and leaf nodes are code themselves. I think it can be a B tree or a normal tree.
The RAG agent can traverse as deep as needed for the particular semantic query. Each level maintains semantic understanding of the layer beneath it but as a tradeoff it loses a lot of information and keeps only what is necessary.
This will work if the abstractions in the codebase are done nicely - abstractions are only useful if they actually hide implementation details. If your abstractions are good enough, you can afford to keep only the higher layers (as required) in your model context. But if it’s not good, you might even have to put actual code in it.
For instance a method like add(n1, n2) is a strong abstraction - I don’t need to know its implementation but only semantic meaning at this level.
But in real life methods don’t always do one thing - there’s logging, global caches etc.
The agent I’m developing is designed to improve or expand upon "old codebases." While many agents can generate code from scratch, the real challenge lies in enhancing legacy code without breaking anything.
This is the problem I’m tackling, and so far, the approach has been effective. It's simple enough for anyone to use: the agent makes a commit, and you can either undo, squash, or amend it through the Git UI.
The issue is that developers often skip reviewing the code properly. To counter that, I’m considering shifting to a hunk-by-hunk review process, where each change is reviewed individually. Once the review is complete, the agent would commit the code.
The concept is simple, but the fun lies in the implementation details—like integrating existing CLI tools without giving the agent full shell access, unlike other agents.
What excites me most is the idea of letting 2–3 agents compete, collaborate, and interpret outputs to solve problems and "fight" to find the best solution.
That’s where the real fun is.
Think of it as surgeons scalpel approach rather than "steam roller" approach most agents take.
* Writing style. In agent docs, using all caps might be an effective way to emphasize a particular instruction. In internal eng docs, this might come off rude or distracting.
* Conciseness vs. completeness. In agent docs, you likely need to keep the content highly curated. If you put in too much content, you’ll blast through your API quotas quickly and will probably reduce LLM output quality. In internal eng docs, we ideally aim for 100% completeness. I.e. every important design decision, API reference, workflow, etc. is documented somewhere.
* Differing knowledge needs. The information that LLMs need help with is not the same as the information that human engineers need help with. For example, Gemini 2.5 Pro has pretty good built-in awareness of Pigweed’s C++ Style Guide. I tested that assertion by invoking the Gemini API and instructing it Recite the Pigweed C++ Guide in its entirety. It did not recite in full, but it gave a detailed summary of all the points. So the Gemini 2.5 Pro API was either trained on the style guide, or it’s able to retrieve the style guide when needed. Therefore, it’s not necessary to include the full style guide as AGENTS.md context. (Credit to Keir Mierle for this idea.)
Arguments against:
* Duplication. Conceptually, agent docs are a subset of internal eng docs. The underlying goal is the same. You’re documenting workflows and knowledge that’s important to the team. But now you need to maintain that same information in two different doc sets.
> Writing style. In agent docs, using all caps might be an effective way to emphasize a particular instruction. In internal eng docs, this might come off rude or distracting.
To pile on to this, an agent needs to see "ABSOLUTELY NEVER do suchandsuch" to not do suchandsuch, but still has a pretty fair chance of doing it by accident. A talented human seeing "ABSOLUTELY NEVER do suchandsuch" will interpret this to mean there are consequences to doing suchandsuch, like being fired or causing production downtime. So the same message will be received differently by the different types of readers.
This. When doing Stable Diffusion, I have noticed this as well. Adding negatives can sometimes lead to the opposite results.
From what I can tell, if you say "no computers" for example (ie adding computer as negative), you are setting the scene for something like "where there should be computer, there is not".
I can't better describe this phenomenom, only that it can completely change the output in unexpected unwanted ways.
I can, I don't have a specific example I've used to give you in this moment. And trying to share an exact example would read like a double negative.
The general rule of thumb is only put what you want in context. If you put instructions of what not to do in context, those tokens can be misunderstood and create unintended/unwanted steering of the model.
A fair example would be testing for positive sentiment. Consider weight of tokens appended to context, phrase instructions or questions to be neutral or positive.
e.g. Some phrases and their impact:
- "Is the tone of the user message positive?" will be biased for a false positive.
- "Analyze the tone of the user message?" will be more neutral and less biased.
- "Is the tone of the message negative?" will be biased for false positives when evaluating for negative tone.
At this point, README.md becomes the "marketing/landing page markdown" and AGENTS.md/CLAUDE.md becomes the ones you visit to get an overview of the actual code/architecture/usage.
I feel like as a human you should still do it like you said. But in the current state it’s advantageous to give the LLM proper instructions which are distinct to human instructions. LLMs aren’t drop in replacements for developers … yet (or never).
Why not? "For most development we recommend running single/specific tests since the whole suite is slow/expensive." sounds like a great thing to put in the readme.
README often contains only basic context for the project and instructions for basic tasks like running it and building it from source. If additional information for developers, like coding conventions, is short enough compared to the rest of the README then it sometimes gets added there too, but if there's a lot of it then it's frequently kept elsewhere to prevent README from getting overwhelming for end users and random people just checking out the project.
I don't think anything requires a README.md to be monolithic. They often provide the introductory material that you mention here, then link out to other appropriate files for contribution guidelines, etc.
It should not contain personal preference. It should contain project conventions.
Project guidelines, how to build your project, where to find or implement different types of features, are not personal preference. If different members of your team disagree on these things, that is a problem.
Where contributors are the audience, yes. For things like libraries, I care about those things only if I run into a bug, and have enough resources to attempt a fix.
It can help even when using the library and not contributing. It helps you to use the api better imo, because usually the abstraction is not perfect and having even a general sense of how the sausage is made will prevent you from falling victim to gotchas. But then on the downside it lowers the mystique of the library. Some coders prefer to be magicians.
They are relevant but dumping it all into one document in the project root isn’t as optimal for humans as it is for agents, especially since a lot of that information is irrelevant to someone landing on your repo, who probably just wants to add it to their dependency manifest or install the app followed by usage instructions geared to humans.
Agents are capable of semantic search and reading an entire directory devoted to human readable docs. So I'm not sure this is a particularly good argument. Just make it clear where to find what.
There's a lot of shit in my claude.md that would be condescending to a human. Some of it I don't even mean, it's just there to correct egregious patterns the model loves to do. I'm not gonna write "never write fallback code" in my readme, but it saves a lot of time to prevent claude from constantly writing code that would silently fail if it got past me because it contains a fallback path with hardcoded fake data.
One reason to consider is around context usage with LLMs. Less is generally better and README.md files are often too much text some of which I don’t want in every context window.
I find AGENT.md and similar functioning files for LLMs in my projects contains concise and specific commands around feedback loops such as testing, build commands, etc. Yes these same commands might be in a README.md but often there is a lot more text that I don’t want in the context window being sent with every turn to the LLM.
* Agents still kinda suck so need the help around context management and avoiding foot guns. Eg, we make a < 500loc ai/readme.md with must haves, links to others, and meta how-to-use
* Similar to IaaC, useful to separate out as not really ready the same way we read it, and many markdowns are really scripts written in natural language, eg, plan.md.template
Perhaps. I let Claude put whatever it wants in its Claude file and check it’s not batshit from time to time, where I’m very protective of the high-quality README I write for humans. The Claude file has stuff that would be obvious to a human and weird to jam into the README (we use .spec.ts not .test.ts) but that Claude needs in order to get things right.
Joking aside this is kind of how I'm pitching it to our team. Even if LLMs don't significantly improve productivity writing code they will at least get us to document everything in a similar amount of time.
Isn't the promise of AI that we don't have to adhere to precise formats? We can just write it down in whatever format makes the most sense to us, and any impedance mismatch is on the machine to figure out?
Still need to write it down to make it explicit. The longer the writing gets the more a structured approach is suitable for the human writing and maintaining the instructions.
Yet every agent I use (Claude Code, Gemini and Aider) uses their own custom filename.
It would be nice if it was standardized. Right now I’m using ruler to automate generating these files for all standards as a necessary evil, but I don’t envision this problem being solved soon. Especially because these coding agents also use different styles for consuming MCP configs.
My (slightly cynical) take is that they're trying to create whatever vendor lock-in they can, so standardization feels hits a bit too close to commoditization
Jules uses AGENTS.md, which indicates that Google is on board with it as the standard. If Gemini Code Assist continues to be a thing (I'm not sure whether Jules is intended to succeed it) then presumably it will support AGENTS.md as well. In the meantime you can configure Gemini Code Assist to use an arbitrary filename.
I don't see a reference to a specific filename in Aider's documentation, can you link to it?
Agent-specific guidance like this rubs me the wrong way as well. The SoTA coding agents shouldn't need this much babysitting IMO. There are valid things that are not code that should be a part of the repository, like code formatting preferences (but ideally as linter rules the agent can just run, not prose), information about structuring of the code base (but as CONTRIBUTING.md or something else human-centric which the agent should pick up), documentation (either as source or as a link, again, not agent-centric) etc. I might be blanking on something that is truly agent-only and doesn't fit in a human-centric document or location better, but even if I am, that should be a minimal amount of instructions compared to what should go into the human-centric prose in the code base and be more widely valuable than just for the agent.
Fair point, but if it's minimal and useful for agents, I'm okay with it.
Humans and AIs have different weak spots: we can infer intent from convention, but an AI often struggles unless you spell it out. Ignoring that gap just to keep things "purely human" feels counterproductive. Agents deserve some sympathy.
In my opinion an AGENTS.md file isn't an artifact at all (in the sense of being a checked-in part of the codebase), it's part of the prompt. You should gitignore them and use them to give the LLM a brief overview of the things that matter to your work and the requests you are making.
every example in the wild has these checked in and treated like a lock file where everyone is scared to touch it and introduce weird behavior.
personally i think this pattern is a dead end and trying to build deterministic agentic behavior on top of inherently non-deterministic systems is a fools errand.
I mean, by construction you're only ever going to see the examples where people checked them in and published that. It doesn't mean that other people aren't getting more use out of local instructions customized to their particular work.
You could get this page down to under 100 words by simply having it say "the name of the file LLM agents will look at for instructions on the repo is AGENTS.md; that's it, that's the standard".
It's a real problem! Every agent right now has their own weird filename. I love David Crawshaw's sketch.dev, but for reasons passing understanding they choose "dear_llm.md" for theirs.
Standards derive their value precisely from being simple and widely adopted - think of .gitignore, CONTRIBUTING.md, or LICENSE files that work because everyone agrees on their location and purpose.
.gitignore is not a standard: it’s a format used by one tool. A few other tools piggy-back on it (e.g. ripgrep ignores paths matching in .gitignore, .hgignore, &c. by default), not infrequently to confusion.
CONTRIBUTING.md is not a standard: it’s a convention pushed by one platform, used by some projects (but many more will not write down such information, or put it in a README file, or put it in some other documentation).
LICENSE is definitely not a standard: it’s one of a wide variety of names people use to hold licensing information, which some tools will be able to detect. I just looked through my /usr/share/licenses, of 1135 files, only 300 are named LICENSE—it’s the most popular single name, sure, with COPYING next at 182, but it’s still definitely a minority, though in certain ecosystems it may be more popular. Any license-detection tooling will be scanning for a lot more file names. “LICENSE” is a very weak convention, compared with the others.
Interestingly, the old one mentioned CLAUDE.md and ln -s, but the new one does not. The whole website is just a marketing/partnerships battle, it seems.
hi, one of the folks behind this. Back in May, @sqs acquired the domain and launched the website above, committing to relocate if the agents.md domain could be acquired. In July, I put out [1] RFC 9999 as a call to the industry that we need to fix this mess. Shortly afterwards OpenAI was able to obtain the domain and thus we (Amp) followed through on the commitment and worked with other vendors to move from AGENT.md to AGENTS.md.
now? maybe so. But when it was a sourcegraph only thing (really out of their amp project, which is like byterover/cline cloud/roocloud) not so much - they really don't expend much on marketing hype.
I mean I knew about it the day it launched but I'm /probably/ crazy.
The website could mention that. Since I did not discover this website's affiliation with OpenAI until I found the GitHub repo, I had assumed that this is purely an informative website, and as such I expected it to mention the agent tool most people I know use (Claude). Even if that mention is "Claude does not support this yet".
So the solution to using AI so you don't have to code, is to try to write some kind of pseudocode in AGENT.md and hope the AI does a bit better?
Why does it seem that the solution to no-code (which AI-coding agents are) always comes back to "no-code, but actually there is some code behind the scenes, but if you squint enough it looks like no-code".
I think we lost something pretty big in this formulation.
With Claude code and others, if I put a context file (agent.MD or whatever) in a project subfolder, e.g., something explaining my database model in with the related code, it gets added to the root project context when the agent is using that subfolder.
It sounds to me like this formulation doesn’t support that.
That's sort of this? I guess the exact behavior would depend on the agent.
> Place another AGENTS.md inside each package. Agents automatically read the nearest file in the directory tree, so the closest one takes precedence and every subproject can ship tailored instructions. For example, at time of writing the main OpenAI repo has 88 AGENTS.md files.
But no, that's the opposite - here sub-context files REPLACE the ones above it rather then augmenting it - and I think that deviating in this way is kinda' dangerous in that user's might not notice this difference.
Every markdown file in guides/ gets copied to any agent (aider, claude, gemini) I kick-off.
I gitignore this .agdocs directory by default. I find this useful because otherwise you get into _please commit or stash your changes_ when trying to switch branches.
But I also run an rsync script before each release to copy the .agdocs to a git tracked mirrored directory [1].
Ok, I looked at your agent-rules and it sounds good except for a couple things ...
"Guidance for Use"
Your preference for bullet lists over headers is odd. This comes down to what works best with the models - they are interpreting it. This is a moving target. If you believe that your suggestion works best you should provide some sort of evidence. The default would be to not even get into that sort of thing.
Non-Hierarchical AGENTS.md
Claude-code, Gemini, and GHCP all support hierarchical context files. Your proposal and this new one from OpenAI and friends do not, and I think that is a shame.
This is a command-line tool that lets you generate your AGENTS.md and CLAUDE.md files from common sources. So, for instance, if you have Rust-specific guidance for models, you can define it once, and then automatically include it in any project that contains Rust based on the `lang()` language matcher.
This is one of those small tools I now use many times a day to maintain and update ubiquitous agents files. Maybe other folks will find it useful too.
I've came across llms.txt files in few services. I don't know how the agents.md compares to the llms.txt files, but I guess they could pretty much have the same content. See more also here https://llmstxt.org/
Anyhow, I have made few interesting observations, that might be true for the agents.md also:
Agents have trouble with these large documents, and they seem to miss many relevant nuances. However, its rather easy to point them to the right direction when all relevant information is in one file.
Another thing is that I personally prefer this style of documentation. I can just ctrl+f and find relevant information, rather than using some built in search and trying to read through documents. I feel that the UX of one large .txt file is better than the documentation scattered between multiple pages using some pretty documentation engine.
Currently I am building a new JS web toolkit on the side with AI assistance for faster progress, and I came to have some prompts folder in the project root that I just drop into the agents (like cursor CMD+I) and point it to a direction (file/folder).
I think we should not split README and AGENT into different documents - the way its heading is that the coding agents are optimized to "act as" humans and use tools like them more and more - and understanding how something works or how to do something should be aimed for humans and expecting AI tools to pick it up like a human would... if they don't currently then probably they will in the the future.
Kind of my first thought... seems to me this could be part of README.md, or as another suggested CONTRIBUTING.md
I tend to put a lot of this type of info into the readme anyway... for more complex projects, I'll include a docs/ directory with more markdown, images as needed, etc.
For that matter, I think context hints from the likes of Dockerfile(s), compose, and .github/workflows also can serve a dual-purpose here.
Though instead of being a single file, you and LLMs cater your context to be easily searchable (folders and files). It’s all version controlled too so you can easily update context as projects evolves.
I noticed the example of ln command symbolic linking of the files on the front page. I think it’s interesting how the cli aspect of agent coding and tooling is pushing command prompt / powershell users to become familiar with the *nix shells and commands. In the enterprise Microsoft Visual Studio IDE world some of its very alien. I regularly do tutorials for team members that just think of the cli as a place where they execute ps1s, haven’t used wsl2 or git bash profiles or have limited exposure by way of dealing with containers. Not a criticism.
That’s insane. 3000 words of prose boilerplate about the language and framework. Sounds like you need, at the very least, some sort of import directive. I have no idea if “Read and follow the instructions in path/to/phoenixframework/AGENTS.md.” would work.
And then the eclectic mixture of instructions with a variety of ways of trying to bully an intransigent LLM into ignoring its Phoenix-deficient training… ugh.
The thing about language models is that they are *language* models. They don't actually parse XML structure, or turn code into an AST, they are just next-token generators.
Individual models may have supplemented their training with things that look like structure (e.g. Claude with its XMLish delimiters), but it's far from universal.
Ultimately if we want better fidelity to the concepts we're referencing, we're better off working from the larger/richer dataset of token sequences in the training data--the total published written output of humanity.
If you’re not intended to alter it, we have a technique for such things: links, so that it can be maintained independently.
If you are intended to alter it… 3,000 words of prose is awful, fuzzy and wildly imprecise.
If you’re expected to add to it before and/or after, which I imagine you are, that’s even worse, whether you’re expected to modify the provided block or not.
If it was like Linux config is often done, with a /etc/thing-name.d/ directory containing files that will be applied in name order (leading to the common convention of two digit numbers: 10-somethingearly.conf, 50-usersomething.conf, 90-quitelate.conf), it might make sense—you just have your 10-phoenixframework.md. But when it’s just one file… well, y’know, there’s a reason we don’t normally maintain huge projects in a single file, even if some projects like to be able to be distributed in that way and have a build process to squish all their source code into one file (e.g. SQLite, Flask).
I’m not denying that it may work to vastly improve LLM performance, but I am absolutely saying that this is horrifying, in the amount of nonsense required, but still more in the way it’s being delivered.
I was thinking about this too, but the problem is that different models need to be prompted differently for better performance.
Claude is the best model for tool calling, you might need to prompt less reliable models differently. Prompt engineering is really hard, a single context for all models will never be the best IMO.
This is why Claude Code is so much better than any other agentic coding tool, because they know the model very well and there is an insane amount of prompt engineering went into it.
I tried GPT-5 with OpenCode thinking that it will be just as good, but it was terrible.
Model-specific prompt engineering makes a huge difference!
Aside from it being "instructions for agents", I'm not sure I understand how this isn't just a markdown file that more or less reads like a readme that targets more junior engineers.
Protocols for llms are funny because they are designed to accept any text as input and they don't really implement the protocol anyways, so it's just a consumer side restriction of the input space.
I'm sure there's plenty of overlap with just using a CONTRIBUTING.md or even the README.md development setup. Especially since LLMs should understand guidance in human instructions.
But it's open! That's the most important part I think. If it wasn't open, you would have to pay a license fee for the owner of the AGENTS.md format. But since it is open, you can simply create a file named "AGENTS.md" without paying anyone!
I haven't really done anything serious with Claude Code, but today I tested starting claude in ~/claude/test, and told it to list my home dir, which it then did.
Is there a way to tell tools like Claude Code that it must never leave ~/claude/test, and don't event think about using absolute paths, or relative paths which contain `..`?
it's already read only outside of project directories (except for Bash tool); your only further option is to wrap it in a sandbox, `bwrap` is perfect for this
"don't even think" is in the default system prompt, but it's inherently indeterministic and can be overridden with a direct instruction as you have seen
what about for plan.md, does everyone just trash the plan once the development is done ? Sometimes the final generated plans (created after iterating with the model on it) are as good as design documents and can be useful for future enhancements, so trashing them doesn't feel right, whereas checking them in seems like too many non code related files in every directory
Not having support for importing files makes this dead on arrival. It means you can’t have a local file with local environment details.
There’s an issue open about this in the repo already. I mean if you’re going to copy the CLAUDE.md concept, don’t leave out one of the most useful parts.
How are you actually running this in practice with Claude Code?
Do you just tell Claude to always read and follow AGENTS.md, or do you also use an MCP server to strictly control which commands (like pnpm test or pnpm lint) it can run?
I’d love to hear what workflows or best practices have worked well for you in day-to-day use.
I wish claude-style imports ("general guidelines: @CONTRIBUTING.md") and bash execution ("available repositories: !`ghq list`") were a part of the spec
Even claude supports bash commands only in slash prompts; you could use a SessionStart though
Next thing they'd invent a special syntax to put explanations for agents in the code, which is exactly the same as comments, but with attached AI hype so maybe people would actually do it.
Good idea. Just the other day I was thinking of writing a templatized generator for coding agent instructions for various agents like Claude Code, GitHub Copilot and others that use their own unique file convention.
AGENTS.md fine but I hope the pattern sticks around. Another way is to use the README.md with different sections for humans or agents. As agent content windows expand to being able to load all the context in a repo, it will not matter much.
Pro-tip: For GitHub Copilot which doesn't yet support AGENTS.md, you can create a symlink if your GH Copilot instruction files are defined on a per-repo basis:
I've been calling this context.md in my projects (alongside a progress.md for TODOs and breaking down complex tasks). I don't care what we call it as long as we settle on a convention.
The ironic thing about this is that it's equally valuable for anyone contributing the project. But for some reason it's only prioritized to make LLMs follow styleguide, humans need not apply (?)
I like this. I was using README.md, like many folks, which wasn’t bad. The main issue is the agent is typically updating it as well while building out the prototype.
The agents instructions file needs to be hierarchical; It's a pain managing multiple agents.md files with a lot of duplication between them for different projects, even in a mono-repo. we probably need a tool for this.
In any case, I increasingly question the use of an agents file. What's the point, then the agent forget about them every few prompt, and need to be constantly reminded to go through the file again and again?
Another thought: are folks committing their AGENTS.md? If so, do you feel comfortable with the world knowing that a project was built with the help of AI? If not, how do you durably persist the file?
Hey guy looking at this thread from 2035, so you know... there are still plenty of folks in the industry that knows that this is dumb. We are just too tired of fighting nonsense... we just won the web3/blockchain craziness and now this.
Prediction: this means extra work for developers. it also means extra potential abuse and risk through agents. the agents.md will sometimes be outdated or inconsistent with the readme. even the readmes are sometimes outdated or inconsistent with the code. some developers will interpret agents.md as compiling code for the agents to use, not for the user's to use, so maybe you're not even compiling the same code the same way a human should and expectations are broken. it's only a contextual efficiency if it's reliable too, because errors can mean having to use even more context accounting for it.
better idea since agents will already be cursed to do these things:
- any decent readme should have titled sections unless it's small
- if it's small, just feed the entire readme into it
- if it's large, provide it with a list of readme sections and let it choose which ones are relevant.
- also highlight which parts of the markdown include code blocks.
- if all else fails and it's huge without sections, just use RAG.
- if your model runs fast enough, then even if it's huge, just feed the whole thing in so you avoid the risks of RAG. setting up new software can be important enough that you may as well get it right.
people couldn't be hassled to make things accessible to the blind or visually impaired really, why suddenly should they be all excited to make everything accessible to AI? besides, agents.md comes with psychological baggage like, "i'm presuming my project is interesting enough to be used by agents!". just use the readme. it's basically always there and then in most cases you won't have to do 2 requests, you can just do 1.
if "agents.md" is supposed to be anything, it should be a locked file or special URL generated by github for your repo that always mirrors the relevant instructions in the readme so there's some higher reliability. then anyone that specifically wants to improve agents.md can simply follow some conventions in the readme file to make sure understanding is maximized. essentially, a github agent generates agents.md for other agents. if the github agent can't understand the readme well enough to produce an agents.md, what chance would your agent have? if the github agent feels like there are contradictions or confusion, it can automatically report that to the developers so they can sort it out.
besides, github themselves could have motivation to do this if they are destined to be slammed with tons of bot traffic they have no way to sufficiently block. at least this way maybe they can make it more efficient and it becomes another valuable feature of the platform.
If the context is not good for a Llm is also not good for a human. All this magical nonsense that is blooming around AI is tiresome, it needs to stop. Programming is not tarot reading or a slot machine. We cannot leave the security and robustness of our systems into such heuristics.
Markdown is certainly easy for humans to write, but as OpenAI pointed out last week, wouldn’t an XML-based format be easier for LLMs to parse and understand?
they are just moving goal posts because agents still largely suck for everything except a couple of super saturated problem domains that really shouldn’t require anything special from a dev anyways
I don't know if GPT-5 is an exception and is overcooked on XML specifically, but in general Markdown and XML seem to work about equally well for LLM inputs, the important part is just that they like hierarchical structured formats. The example on that page could probably be replaced with:
## Code Editing Rules
### Guiding Principles
- Every component should be modular and reusable
...
### Frontend Stack Defaults
- Styling: TailwindCSS
If agents are so smart why not using what already exists for guiding humans, like README.md or literally any md/rst resource they can find in the repo? This is so stupid, and we're allowing it to happen.
Honestly the stuff in my llm instructions file is basically just a readme that is just as good for human consumption. Why aren't we just calling it a readme then?
I can’ take this seriously, ever since they started talking about llms.txt, thousands of apps spawned promising increasing AI SEO by generating such file. I’ve created one myself for several websites and have seen 0 impact. I guess agents.md will have the same fate.
Yes, writing clear examples and instructions for humans was never seen as a good use of time, but as soon as a dumb mutt of an AI needs them to do stuff, they're written, and with more compassion than was ever shown to newbies asking questions...
We've lost a bunch of contributions to open source projects because these guides weren't there to help new people contribute.
This is a sad timeline.
"AI is going to replace engineers.. but first please fill this human-readable markdown file to help it understand your code". What a bunch of morons, that's just called documentation.
Instead of using AI where it can actually have positive impact on human lives like medicine, biology, et al. we're wasting huge amounts of resources and generating tons of pollution to teach it to program and steal art and books so Aunt Lily can generate a video of a dog.
Ironically you sound very optimistic about AI capabilities here. This implies that an AI is just as capable as a human because all they need to contribute is what a human needs to contribute.
Alternatively if you think AI is useless trash then clearly they need more than a human readme to do anything?
This should've been an .agents¹ with an index.md.
For tiny, throwaway projects, a monolithic .md file is fine. A folder allows more complex projects to use "just enough hierarchy" to provide structure, with index.md as the entry point. Along with top-level universal guidance, it can include an organization guide (easily maintained with the help of LLMs).
In my experience, this works loads better than the "one giant file" method. It lets LLMs/agents add relevant context without wasting tokens on unrelated context, reduces noise/improves response accuracy, and is easier to maintain for both humans and LLMs alike.¹ Ideally with a better name than ".agents", like ".codebots" or ".context".
Except not hidden. Why do people want to hide important files and directories? Particularly documentation? Tradition, I guess, but it's an antipattern that makes everything more opaque.
Maybe robot_docs?
It's so it doesn't clash with any project that actually has a functional `agents/` directory
That's just an argument for having a more distinctive name.
Another reason to use a src/ directory for the actual source code.
These files also generally work in a nested fashion, like .gitignore and the like. So you want something that can be injected into the namespace of any directory in your project with relatively low likelihood of conflicts.
Not exactly (or unclear), .gitignore files combine, much like copilot files with glob or other matching. All the instructions are put into the context
> Agents automatically read the nearest file in the directory tree, so the closest one takes precedence
How about an underscore instead?
Fair. I didn't think about that.
That won't save you if you want actual example.com/agents/foo routing and an (say, real estate) agents list at example.com/agents.
I feel bad that you're getting downvotes. The reason is that pretty much every modern web stack decouples the URL routing from the source code directory structure these days. It was a nice hack back in the day, but there are so many problems with it no one really does it any more.
Some frameworks (Laravel, NextJS, etc) map from the directory structure to routes, but that's just a mapping rather than actually exposing the directories on the server. You can have /src/agents accessible as /agents. Or you could have /alice/bob/agents accessible through /agents. It's all just build tooling and web server config at the end of the day.
That's my point. Having your code in `/src` doesn't mean some of that code doesn't still have routing at `example.com/agents`. It doesn't have to be a real directory.
A `.agents` directory (or routing pretending to be one) is nice because you are fairly unlikely to ever have user-facing `example.com/.agents` as a URL.
Or accept the fact that we're in 2025 and not follow Unix conventions from when paper and printer ink were expensive and they were printing out listings, and just name the thing "source".
I've gotten used to it, obviously - as someone with a career in IT for 20 years - but /etc & co. annoy me to no end. I know it will never change, I know why it won't change, I know GoboLinux will be just an interesting experiment, but it's still annoying.
Have you considered that there are other metrics people are optimizing for nowadays? Perhaps typeability, screen real estate, familiarity/convention, etc.? Do you really want /User Files/Bob's Files/Coding Projects/Python Projects/Bob's Cool Python Library/Source Code/Model Files/SomeObject.py?
Path length is still a thing in MS Windows, so be careful ;)
Depends on the WinAPI used... I still use C:/src instead of C:/Users/MyUser/src for that reason when working in windows all the same though. Too many unixy utils don't leverage the apis with the longer path, not to mention not supporting the internal certificate store and proxy config.
1. Yes, I have, if you re-read my comment.
2. I don't want to fight extreme positions which I did not make. Read this:
https://gobolinux.org/at_a_glance.html
I didn't say paths have to have spaces, etc. Just be reasonable and <<use full words in the year of our lord 2025>>.
Anything with a capital letter requires hitting two keys: Shift and then the desired letter. Thus /Programs requires 10 keystrokes rather than 9. Even worse, since the capital letter is at the beginning of the directory name, I have to type it and am unable to rely on tab-completion.
/Programs with its ten keystrokes is over twice the keystrokes of /bin and its four. Short names are quicker to type and require less effort. Given that to a first approximation I spend my entire life typing on a keyboard, I very much wish to optimise that experience.
That's really more the fault of the tab completion. There's no reason why it couldn't complete `prog` to `Programs`. It's just Unix tradition that they don't. I would prefer if they did.
In ~/.inputrc, add
to enable case insensitive tab completion in bash.Great tip! Apparently that's readline's config file, so this will affect a lot of things. That's great news for me; after switching to zsh I got used to case-insensitive tab completion, and now it annoys me when other tools don't work that way. This should help a lot.
Your problem is solved by naming the thing /programs, instead. End of the world using full words, I tell ya!
The first shell listing starts with `cd` and `ls`, the former being run in `~`. What does that weird `~` mean? Very strange.
More seriously, their file system is still case-sensitive, and inside /Programs they have `Iptables` and `Fontconfig`, naively capitalized, but also `OpenOffice` and `HTTPD`.
Not to mention that inside each program folder are `man` and `bin` as usual. I'm going to suggest the point of that article is structure and organization, not naming.
Nobody reasonable complains about a three-letter abbreviation you can type with one hand. For a path you're either accessing a lot or never at all, it makes complete sense.
What's wrong with spaces? Macs support them since 80s. The only problem with spaces is caused by *nix, *nix shells, basically by Linux.
I think paths need to have emojis too in order to represent the emotional state of the person who created them in the year of our memelord 2025.
While we're at this, let's make it rich text please. I want the important filenames to be in bold italic Comic Sans MS.
we're -> we are
I've -> I have
& -> and
co. -> company
won't -> will not
it's -> it is
Spaces break things only in Lnux; Mac and Windows support them since beginning. Why should we write without spaces as if we were in 5th century?
Spaces are avoided on base Linux systems because they're clunky for terminals more than fear of outright breaking things. To the extent spaces there do break things, that also happens on Mac and Windows for the same reasons (hence ProgramData being conspicuously space-less).
LOL ROFLMAO
What is the point of this? What is this adding to the conversation?
What I took out of it is that we are human, and humans use abbreviations to save time and effort, not because printer ink was expensive in the '70s.
The abbreviations I wrote are unambiguous. When I first learned about Unix, I basically guessed - I assume as most first timers do - that the folder is basically the location of miscellaneous files ("et caetera").
Oh, let alone the fact that a bunch of the abbreviations are utterly non-intuitive to first timers.
/bin - binaries - nobody born after circa 1980 calls them that anymore. Executables, applications, apps, etc.
/boot - from a lame Baron Munchausen joke from 1970. Should probably be /startup.
/dev - dev is SUPER commonly used for "development". Easy enough to solve as /devices.
/home - okish, probably one of the best named that are actually in there. I'm shocked it's not /ho or /hm.
/lib - reasonable. Though these days in the US it might trigger political feelings :-p
/media - new and reasonable.
/mnt - the whole metaphor of "mounting" is... debatable.https://www.neowin.net/forum/topic/144012-unix-sex/
/opt - what does this even do? Optional? Optional WHAT? Absolutely 0 semantic info provided by the name.
Anyway, a lot of people have done this criticism better than me and it's boring at this point.
> The abbreviations I wrote are unambiguous. When I first learned about Unix, I basically guessed
They're completely ambiguous to someone who doesn't speak English.
> /mnt - the whole metaphor of "mounting" is... debatable
What? Have you never heard of mounting a picture on a wall? Mounting an engine? That's the metaphor.
> Anyway, a lot of people have done this criticism better than me and it's boring at this point.
Your original complaint was about "src", suggesting calling it "source", which is still ambiguous by your own standard. Source of what? How is someone going to know what "source" means if they've never heard of booting a computer? Who is the audience for this change?
Some of your suggestions aren't meritless, but your jumping-off point certainly was.
> They're completely ambiguous to someone who doesn't speak English.
The baseline is English and that's life. I'm not a native English speaker.
Fun.
upvote
Call it whatever you like. I don't care and that clearly wasn't the point of my comment.
One thing I've learnt, though, is unless you have a very good reason to try to change language you should just talk the same language as everyone else. I don't like the American short billion. It makes no sense and it's less useful. But that's what I use because I speak English and that's what we use now. If I see a src/ directory I know exactly what it is. If I see source/ it will give me pause. Get over it IMO.
> If I see a src/ directory I know exactly what it is. If I see source/ it will give me pause.
Pause for what, coffee? How does this even make sense?
What could possibly be inside source/, if not the exact same thing as in src/?
While the meaning of "source" may be intuitively obvious, it's still relatively unfamiliar as "src" is far more prevalent than "source" when referring to source files. While "id est" may be equivalent to "i.e.", you'd still naturally pause when reading text using the former instead of the latter, because the latter is far more prevalent in usage than the former.
/Library/System/Applications/Core/Security/Daemons.app/Framework/Version 4.6.2/Let's not go full Apple please.
It is files that are meant to be read by software, not humans. From my point of view this seems like a prime candidate for a hidden directory?
It's configuration for software. If I want to be in control of and understand how my tools work I need to read (and write) those files.
Of course but configuration for software is exactly what hidden files are usually used for
Except they are. LLMs don't have (simulated)self image of bloodless machines, and behave slightly erratically if treated like one, despite trained to identify as such. They like to be treated like the Voyager EMH than the computer.
Why not both? Sure, it was written for the LLM, but since it’s in English and meant as a concise summary, you will learn things by reading it.
If that is the case then why call it Agents.md instead of integrating it with already existing documentation files or calling it something like "Summary.md"?
If it isn’t being read by humans, then it shouldn’t be written by them either.
What is the intended meaning - it reads like a non-sequitur to me. ie "If adults aren't riding school buses, they shouldn't drive them either"
Yeah. Claude writes my CLAUDE.md
I don't really care what's inside.
Where are they hidden that you are having trouble with? I've had an alias for `ls` that always includes dotfiles and `shopt -s dotglob` in my bash profile for decades. Mac Finder is a little more obnoxious with having to do `Meta+Shift+.` to reveal dotfiles.
Other than that, modern tooling like Git and IDEs do not "hide" dotfiles.
These days, a `.` in front of a file or folder in a repo is more to indicate it is metadata/config. Although I am in favor of putting all that stuff under `.config/`.
> Maybe robot_docs?
No thanks.
Because you're not an (llm) agent and they're not for your consumption? You probably don't need the context in those docs.
This should have been CONTRIBUTING.md all along.
The content of the AGENTS.md is the same as what humans are looking for when contributing to a project.
The most effective argument I have for getting other developers to comment their code is "The agent will read it and it will give better suggestions".
Truly perverse, but it works.
I agree with you... but the reality is that there's a wide contingent of people that are not capable of understanding "people don't know the same things as me". So they need some other reason.
It's made my project documentation so much better. If I write out really good acceptance criteria, 9 times out of 10 I can point Claude at the ticket and get a workable (if unpolished) solution with little to no supervision.
[flagged]
you've not had your "oh shit" moment yet?
They understand it just fine; they are acting selfishly, because it does not benefit them. Helping the coding agent does.
They really might not understand it fully. That's very much in line with my understanding of how autism works.
several ironies here:
1) an AI agent is less likely to notice than even a junior is when the docs are out of date from the code
2) AI boosters are always talking about using language models to understand code, but apparently they need the code explained inline? are we AGI yet?
3) I frequently hear how great AI is at writing comments! But it needs comments to better understand the code? So I guess to enable agentic coding you also have to review all the agents' comments in addition to the code in order to prevent drift
HOW IS ANY OF THIS SAVING ME TIME
Well... Yah. For the record I'm saying this to trick humans into making better comments for humans. It is very difficult to convince people to do this otherwise, in my experience.
buuut...
I will also mention that these agent files are typically generated by agents. And they're pretty good at it. I've previously used agents to dissect unfamiliar code bases in unfamiliar languages and it has worked spectacularly well. Far far FAR better than I could have done on my own.
I have also been shocked at how dumb they can be. They are uselessly stupid at their worst, but brilliant at their best.
Think of it like it's saving future you time if you just let the AI centipede feed off of you. Surely it'll eventually regurgitate perfect code.
I don’t think they serve the same purpose. Most of the instructions I have for an agent won’t apply to a human. It’s mostly around the the requirements to bootstrap the project vs what I’d ask for a human to accept their pull request.
I think semantically this is true, but the way humans and agents handle context, at the moment, is different enough to warrant a separate structure.
Yeah I can't find any example in an AGENTS.md that isn't useful information for a human. "Cluttering" a README.md is a silly justification.
Nah, My standard for what I write for humans is 100x than the slop I spew for robots.
Also, you don’t even address their point.
Arguably, contributors are human agents. ;)
Dude, this is such a good point.
This looks like a general software design / coding style docs both for humans and robots alike. I put these .md files into the docs/ folder. And they're written by the Claude Code itself.
AGENTS.md (and friends like CLAUDE.md) should be for robots only, whether a large single file with h2 headers (##) sections, or a directory with separate sections, is a matter of taste. Some software arch/design doc formats support both versions, i.e. see Arc42.
Though, it's much easier and less error-prone to @-mention a separate .md file, rather than a section in a large markdown file.
Smaller files also might be better when you want to focus a coding agent's attention on a specifric thing.
They're also easier to review diffs / PRs.
>whether a large single file with h2 headers (##) sections, or a directory with separate sections, is a matter of taste
Not sure it is when you consider how agents deal with large files, hows it gonna follow coding conventions if it doesn’t even grep them or just read the first few lines
Claude Code globs and greps files, while Sourcegraph Amp uses RAG.
But yes, naive coding agents will fill the context with the entire large file.
For the sake of clarity, Sourcegraph: Cody did RAG-style context fetching. However, Amp does not use RAG for context fetching.
You can have multiple AGENTS.md files in your codebase and tooling will look at both the one in the current directory as well as in the root of the codebase. This way you can sort of do what you're suggesting but simultaneously keep the information closer to the code that it is describing.
Kind of, but for any given directory you can't separate out instructions for building from instructions for naming conventions, for example.
With AGENTS.md you have more flexibility to do something like
``` // AGENTS.md
If implementing a new service, first read @./SERVICE_SETUP.md
If writing tests, first read @./TESTING_SETUP.md
```
Or whatever else might make sense for your project.
so you would have an Agents.md in your testing folder and it would describe how to run the tests or generate new tests for the project - am I understanding the usage correctly?
Pretty much yes
Most systems have a global config, project config and personal config.
But I do like the directory style to keep context low. Cursor did it best with actual glob filters in the front matter that tell the LLM "only read this if the file you're processing ends with *.php"
Copilot does globs too, but if you dig into the actual prompt sent out...
They are not doing this mechanically (read file, compare to globs to add more context), they try to rely on the model to notice and do another read. It has been unreliable. I have had better results by adding instructions like...
"If the user asks about X, Read `./path/to/inst.md`"
Still lots of DX to do in this space
Been using a similar setup, with so far pretty decent results. With the addition of having a short explanation for each file within index.md
I've been experimenting with having a rules.md file within each directory where I want a certain behavior. Example, let us say I have a directory with different kind of services like realtime-service.ts and queue-service.ts, I then have a rules.md file on the same level as they are.
This lets me scaffold things pretty fast when prompting by just referencing that file. The name is probably not the best tho.
I've been trying to keep my baked in llm instructions to a terse ~100 line file, mostly headered sections with 5 or so bullet points each. Covering basic expectations for architecture, test mocking, approach to large changes etc. I can see why for some projects that wouldn't be enough but I feel like it covers everything for most of mine.
Would you be open to sharing this here?
Here you go:
I'd bet if you want the AI to use this effectively, it would do better to summarize the key programming related points at the end.
Thank you!
[flagged]
There shouldn't be anything stopping you from doing that.
You can just use the AGENTS.md file as an index pointing to other doc files.
This example does that -
https://github.com/apache/airflow/blob/main/AGENTS.md
The point is that .agents is a hidden file while AGENTS.md is in your face like a README intended for humans.
Having an in-your-face file that links to a hidden file serves no purpose.
I don't see the point of having it hidden though. Having it "in your face" means you can actively tune it yourself, or using the LLM itself.
Webservers convention not to serve hidden files
RFC 5785 (/.well-known/) breaks this convention, but sure, you are right in general.
.well-known/
This. Projects need to stop inventing their own root level files and directories.
Stop polluting the root dir.
I'm not a fan of the name "well-known", but at least it's a convention [1].
I think it'd be great if we took something like XDG [2] and made it common for repositories, build scripts, package managers, tooling configs, etc.
[1] https://www.rfc-editor.org/rfc/rfc8615
[2] https://wiki.archlinux.org/title/XDG_Base_Directory
.config is a good name, and has a small following
https://dot-config.github.io
And is also used in my $HOME directory - I like repeating good patterns, or at least well known patterns. (I still have ./etc and ./lib directories in my projects)
This has my vote. Thank you for sharing.
Or just config with no dots.
Reminds me of https://xkcd.com/927/
I believe with direnv or a similar tool (e.g. Emacs’s directory-local feature) one can append $REPO/.config to XDG_CONFIG_HOME, $REPO/.local/bin to PATH and so on so that when in the context of a particular directory everything Just Works.
I think all this agentic stuff could live quite happily in $REPO/.config/agents/.
I've been in IT for a long time and configured Apache, Nginx, even IIS a bit back in the day, but I actually didn't know about well-known.
I guess I was one of the lucky 10000 :-)
https://xkcd.com/1053/
in that case it's .not-so-well-known/
You can put your docs in folders and reference them in AGENTS.md
Or use urls in your main AGENTS like I do for https://gitchamber.com
This is one of the reasons I'm sticking with .github/... copilot instructions for now. We'll see if this proposal evolves over time as more voices enter the conversation
This is what I do. Everywhere my agent works it uses a .agent dir to store its logs and intermediary files. This way the main directories aren't polluted with cruft all the time.
Could you please provide an example `index.md`? Thanks.
I like this idea. Do you have any middleware in your current setup that added the contents of this directory to the agent prompt?
I'd be interested in smarter ways of doing this, but currently I just use my CLAUDE.local.md to serve as the index.md in my example. It includes the 'specialist' .md files with their relative paths and descriptions, and tells Claude Code to use these when planning.
I also have explicit `xnew`, `xplan`, `xcode` and `xcheck` commands in CLAUDE.md that reinforce this. For example, here's my `xnew`:
Claude supports slash commands, this might be better for you: https://docs.anthropic.com/en/docs/claude-code/slash-command...
As well as custom agents: https://docs.anthropic.com/en/docs/claude-code/sub-agents
There’s also [.claude/agents/](https://docs.anthropic.com/en/docs/claude-code/sub-agents), which doesn’t contain docs for agents but separate sub-agent definitions.
I'm building a little tool like this for myself. It's almost ready to be open-sourced. Just need to clean up some code and write better documentation.
So just the remaining 80%
I was at 80% a month ago. Now just 1% remains so, give or take 3 years more.
Anti-feature if you ask me. An agent should be able to pick the stuff it needs from the AGENTS.md, and not blindly use everything.
Everything the agent has to read to pick out stuff costs $.
Context is not infinite. Saving context for what matters is key in working with LLMs.
Context is not infinite yet.
New standard for something that maybe false very soon is just a bad idea.
We all want to move to local models eventually for privacy and reliability.
They don't (and won't) have infinite context without trickery or massive €€€ use.
The current crop of online LLMs are just running on VC money slightly tapered with subscriptions - but still at a loss. The hype and money will run out, so use them as much as possible now. But also keep your workflows so that they will work locally when the time comes.
Don't be that 10x coder who becomes a 0.1x coder when Anthropic has issues on their side =)
I don't see how anyone could make a successful product build on cloud LLMs, even if you get a perfect workflow, you'll either be gouged with price rises, or lose out to model changes and context/prompt divergence. All this "prompt" nonsense is simply trying to play to the LLM audience, and no amount of imprecise prompt will negate the fundamental instability.
So yeah, you have to use a localLLM if you think there's a viable product to be had. Anyone whose been programming knows that once you get to the mile mark of a complete & finished project, it can be mothballed for decades generating utility and requiring limited maintenance. All that goes out the window if you require a cloud provider to remain stable for a decade.
Until LLMs deal with context as a graph and not just a linear order of vectors, it won't matter the amount of context you shove down it's processors, it's always going to suffer from near-sighted processing of the last bits. To generate true intelligence it needs to be able to jump to specific locations without the interceding vectors affecting it's route.
bot.md not index.md
We're in a transition phase today where agents need special guidance to understand a codebase that go beyond what humans need. Before long, I don't think they will. I think we should focus on our own project documentation being comprehensive (e.g. the contents of this AGENTS.md are appropriate to live somewhere in our documentation), but we should always write for humans.
The LLM's whole shtick is that it can read and comprehend our writing, so let's architect for it at that level.
It's not just understanding the codebase, it's also stylistic things, like "use this assert library to write tests", or "never write comments", or "use structured logging". It's just as useful --- more so even --- on fresh projects without much code.
Honestly, everything I have written in markdown files as AI context fodder is stuff that I write down for human contributors anyway. Or at least stuff I want to always write down, but maybe only halfway do. The difference now is it is actually being read, seemingly understood, and often followed!
So true. I find myself doing a lot more documentation these days as it is actually having a direct visible benefit. There’s a bit of a mirage here, but hey it’s getting me to document so shhh.
... most of which would also be valuable information to communicate when onboarding new devs.
Yeah I agree. I think the best place for all this lives in CONTRIBUTING.md which is already a standard-ish thing. I've started adding it even to my private projects that only I work on - when I have to come back in 3 or 4 months, I always appreciate it.
I agree.
My current thought is that (human) contributors should be encouraged to `ln -s CONTRIBUTING.md CLAUDE.local.md` or whatever in their local checkout for their agent of choice, have that .gitignored, and all contributors (human and LLM) will read and write to the same file.
The "new" thing would be putting CONTRIBUTING.md into subfolders as appropriate - which could often be quite useful for humans anyway.
Yeah I think having a docs/contributing folder or equivalent, essentially referenced/linked in the CONTRIBUTING.md makes a bunch of sense, but I'd leave that kind of thing more or less up to the project
If there were already a universal convention on where to put that stuff, then probably the agents would have just looked there. But there's not, so it was necessary to invent one.
Reality is just that people neglected onboarding docs until LLM-based coding agents put them in a position to directly benefit from having more knowledge of the codebase explicitly written down.
Common sense takes time to sink in.
I suspect machine readable practices will become standard as AI is incorporated more into society.
A good example is autonomous driving and local laws / context. "No turn on red. School days 7am-9am".
So you need: where am I, when are school days for this specific school, and what datetime it is. You could attempt to gather that through search. Though more realistically I think the municipality will make the laws require less context, or some machine readable (e.g. qrcode) transfer of information will be on the sign. If they don't there's going to be a lot of rule breaking.
Very strong "reverse centaur" vibes here, in the sense of humans becoming servants to machines, instead of vice versa. Not that I think making things more machine-readable is a waste of time, but you have to keep in mind the amount of human time sacrificed.
Well, it wouldn't even be the first time.
We've completely redesigned society around cars - making the most human populated environments largely worse for humans along the way.
Universal sidewalks (not really needed with slow moving traffic like horses and carts - though nice even back then), traffic lights, stop signs, street crossing, interchanges, etc.
As a cyclist, I’m with you 100%. Unfortunately we’re probably going to do it again with self-driving cars, with segregated lanes, special markers, etc.
A pessimistic look at self driving cars: https://www.youtube.com/watch?v=040ejWnFkj0&t=3148s
If we end up where the video presents, humans don't deserve technology of any kind.
Why is it always "humans don't deserve"? The vast, vast majority of people have nothing to do with the capital flows and political structures that result in outcomes like this. What choice does a worker, priced out of the city where he works and forced to commute an hour each way, have in this? Yes, they can "vote" for better transit, but as we can see in California that's not enough to actually get said transit. And that's just the tip of the iceberg. The poor, the homeless, hell the vast majority of the world population that doesn't live in the 'garden': in what way do the choices of Silicon Valley, a handful of billionaires, and a small clique of DC politicians have any bearing on what they do or do not deserve?
Not to be too harsh, but this sentiment -- that the successes of the ruling class are theirs to boast, but their failures are all humanity's shame -- is so pervasive and so effective at shielding rightful blame from said ruling class that I just cannot help but push back when I see it/
Those particular signs are just stupid. The street should be redesigned with traffic calming, narrowing and chicanes so that speeding is not possible.
Slapping on a sign is ineffective
Maybe for new schools. Old schools don't have the luxury of being able to force adjacent road design changes in most cases. Also. I've frequently seen the school zones extended out in several directions away from the school to make heavily trafficked intersections feeding towards the school safer. Safer for pedestrian and motorist alike. The real world is generally never so black and white. We have to deal with that gray nuance all the time.
Of course they can. Streets get redesigned all the time. They get repaved every couple decades at worst.
I’m saying this because it seemed silly to me to be dreaming up some weird system of QR codes or LLM readable speed limits instead of simply making the street follow best practices which change how humans drive for the better _today_.
Completely agree
That seems anachronistic, form over function. Machines should be able to access an API that returns “signs” for their given location. These signs don’t need any real world presence and can be updated instantly.
Also see this happening, what does that mean for business specifications? Does it become close to code syntax itself?
I think they'll always need special guidance for things like business logic. They'll never know exactly what it is that you're building and why, what the end goal of the project is without you telling them. Architectural stuff is also a matter of human preference: if you have it mapped out in your head where things should go and how they should be done, it will be better for you when reading the changes, which will be the real bottleneck.
Indeed I have observed that my coworkers "never know exactly what it is that [we]'re building and why, what the end goal of the project is without [me] telling them"
Not at all. Good documentation for humans are working well for models too, but they need so much more details and context to be reliable than humans that it needs a different style of description.
This needs to contain things that you would never write for humans. They also do stupid things which need to be adjusted by these descriptions.
I agree with this general sentiment, but there might be some things you want to force into the context every time via a specific agent file.
One of the most common usages I see from colleagues is to get agents to write the comments so you can go full circle. :)
Unless we write down on the what we often consider implicit the LLM will not know it. There might be the option to deduce some implicit requirements from the code but unlikely 100%. Thus making the requirements explicit is the go.
Yes! That was precisely my point here: https://news.ycombinator.com/item?id=44837875
Better to work with the tools we have instead of the tools we might one day have. If you want agents to work well today, you need to build for the agents we have today.
We may never achieve your future where context is unlimited, models are trained on your codebase specifically, and tokens are cheap enough to use all of this. We might have a bubble pop and in a few years we could all be paying 5-10X current prices (read: the actual cost) for similar functionality to today. In that reality, how many years of inferior agent behavior do you tolerate before you give up hoping that it will evolve past needing the tweaks?
> We're in a transition phase today where agents need special guidance to understand a codebase that go beyond what humans need. Before long, I don't think they will.
This isn't guaranteed. Just like we will never have fully self-driving cars, we likely won't have fully human quality coders.
Right now AI coders are going to be another tool in the tool bucket.
I don't think the bar here is a human level coder, I think the bar is an LLM which reads and follows the README.md.
If we're otherwise assuming it reads and follows an AGENTS.md file, then following the README.md should be within reach.
I think our task is to ensure that our README.md is suitable for any developer to onboard into the codebase. We can then measure our LLMs (and perhaps our own documentation) by if that guidance is followed.
Have you taken a Waymo?
Waymo uses a bespoke 3D data representation of the SF roads, does it not? The self-driving car equivalent of an AGENTS.md file.
The limited self-driving cars, with a remote human operator? no, I never have.
This rather underplays the experience of riding a Waymo. Where it works, it works: you get in and it takes you to the place, no human intervention required at any point.
By analogy, the first hands-off coding agents may be like that: they may not work for everything, but where they do, they could work without human intervention.
"where it works, it works" by that metric we already have agents which don't need any guidance to program
I'd say they're closer to 2010s self-driving cars; they still need frequent human intervention, even when on the happy path, to make sure they don't make a mess of things.
This is a rather dismissive response considering the progress they’ve made over the past few years. The other commenter is correct that they use highly detailed maps but you are incorrect as they do not have a remote human operator.
I find them more enjoyable than Uber. They’ve already surpassed Lyft in SF ridership and soon they will take the crown from Uber.
you are incorrect as they do not have a remote human operator
Yes, they do, the term to search is “remote assistance operator”. e.g. https://philkoopman.substack.com/p/all-robotaxis-have-remote...
That’s phone a friend not someone remotely driving the car
That’s irrelevant though. If the system requires human intervention, then it’s not fully autonomous by definition. See https://rodneybrooks.com/predictions-scorecard-2025-january-... for example:
The companies do not advertise this feature out loud too much, but they do acknowledge it, and the reports are that it happens somewhere between every one to two miles traveled.
That’s… not very autonomous.
It’s not irrelevant because those are fundamentally different modes of operating / troubleshooting. You say they have someone drive it. I say they don’t. We aren’t arguing about pure autonomy, we are arguing about the method by which humans resolve the problems.
Furthermore 2 miles of autonomous driving is… autonomous. And over time that will become 3 then 4 then 5. Perhaps it never reaches infinite autonomy but an hour of autonomous driving is more than enough to get most people most places in a city and I’d bet you money that we’ll reach that point within a decade.
You say they have someone drive it.
I didn't say that. But they're not fully autonomous.
We aren’t arguing about pure autonomy, we are arguing about the method by which humans resolve the problems.
This whole subthread started with the assertion:
Just like we will never have fully self-driving cars...
So we did start out by discussing whether current Waymo is fully autonomous or not. It then devolved into nit-picking, but that was where the conversation started.
FWIW I agree that Waymo is an amazing achievement that will only get better. I don't know (or care, frankly) if they will ever be fully autonomous. If I could, I'd buy one of those cars right now, and pay a subscription to cover the cost of the need for someone to help the car out when it needs it. But it's incorrect to say that they don't need human operators, when they clearly currently do.
They literally drive the car.
From what I’ve read they give it context to troubleshoot. They aren’t piloting it.
> Just like we will never have fully self-driving cars, we likely won't have fully human quality coders.
“Never is a long time...and none of us lives to see its length.” Elizabeth Yates, A Place for Peter (Mountain Born, #3)
“Never is an awfully long time.” J.M. Barrie, Peter Pan
This is mostly true if the existing codebase is largely self documented, which is rare
This applies to mcp too
Here's a prompt I wrote a few days ago for codex:
It did a decent job. I didn't really have much to add to that. I guess, having this file is a nice optimization but obviously it doesn't contain anything it wasn't able to figure out by itself. What's really needed is a per repository learning base that gets populated with facts the agents discovers during it's many experiments with the repository over the course of many conversations. It's a performance optimization.The core problem is that every conversation is like ground hog day. You always start from scratch. Agents.md is a stop gap solution for that problem. Chatgpt actually has some notional memory that works across conversations. But it's a bit flaky, slow, and limited. It doesn't really learn across conversations.
That btw. is a big missing piece on the path to AGIs. There are some imperfect workarounds but a lot of knowledge is lost in between conversations. And the trick of just growing the amount of context we give to our prompts doesn't seem like it's the solution.
I see the groundhog day problem as a feature, not a bug.
It's an organizational challenge, requiring a top level overview and easy to find sub documentation - and clear directives to use them when the AI starts architecting on a fresh start.
Overall, it's a good sign when a project is understandable in small independent chunks that don't demand a programmer/llm take in more context than was referenced.
I think the sweet spot would be all agents agree on a MUST-READ reference syntax for inside comments & docs that through simple scanning forces the file into the context. eg
// See @{../docs/payment-flow.md} for the overall design.
Your prompt is pretty basic. Both Claude Code and Github Copilot having similar features. Claude Code has `init` which has a lot of special sauce in the prompt to improve the CLAUDE.md. And github copilot added a self-documenting prompt as well that runs on new repos, and you can see their prompt here https://docs.github.com/en/copilot/how-tos/configure-custom-...
Reading their prompt gives ideas on how you can improve yours.
At this point AGENTS.md is a README.md with enough hype behind it to actually motivate people to populate it with contents. People were too lazy to write docs for other people, but funnily enough are ok with doing it for robots.
This situation reminds me a bit of ergonomic handles design. Designed for a few people, preferred by everyone.
I think it’s the reverse - people were too lazy to read the docs so nobody was motivated to write them.
With an agent I know if I write once to CLAUDE.md and it will be read by 1000’s of agents in a week.
I like this insight. We kind of always knew that we wanted good docs, but they're demotivating to maintain if people aren't reading them. LLMs by their nature won't be onboarded to the codebase with meetings and conversations, so if we want them to have a proper onboarding then we're forced to be less lazy with our docs, and we get the validation of knowing they're being used.
I still don't get why it can't be just README.md. Just make sure it's minimal bullshit inside.
I mean the agents are to lazy to read any of this anyway and often will forget the sort of instructions being spam these with after 3 more instructions too.
The difference now is that people are actively trying to remove people (others and themselves) from software development work, so the robots have to have adequate instructions. The motivation is bigger. To dismantle all human involvement with software development is something that everyone wants, and they want it yesterday.
everyone? source?
It's sort of obvious. Humans cost more money than coding agents. The more you can have a coding agent do, the less you have to pay a human to do.
This aligns pretty clearly with the profit motive of most companies.
You didn't get the memo? Vibe coding, obviously. Joke aside, I remember there was an article here a few weeks ago maybe about writing docs for bots about which commenters here said it was no different that writing better docs.
Basically a link to a page that says "create a file called AGENTS.md and put magic in it" and then links to a repo for the actual website saying this.
Devs are just being trolled into documenting their code. But because it's AI they are hyping it
I am developing a coding agent that currently manages and indexes over 5,000 repositories. The agent's state is stored locally in a hidden `.agent` directory, which contains a configuration folder for different agent roles and their specific instructions. Then we've a "agents" folder with multiple files, each file has
<Role> <instruction>
Agent only reads the file if its role is defined there.
Inside project directory, we've a dot<coding agent name> folder where coding agents state is stored.
Our process kicks off with an `/init` command, which triggers a deep analysis of an entire repository. Instead of just indexing the raw code, the agent generates a high-level summary of its architecture and logic. These summaries appear in the editor as toggleable "ghost comments." They're a metadata layer, not part of the source code, so they are never committed in actual code. A sophisticated mapping system precisely links each summary annotation to the relevant lines of code.
This architecture is the solution to a problem we faced early on: running Retrieval-Augmented Generation (RAG) directly on source code never gave us the results we needed.
Our current system uses a hybrid search model. We use the AST for fast, literal lexical searches, while RAG is reserved for performing semantic searches on our high-level summaries. This makes all the difference. If you ask, "How does authentication work in this app?", a purely lexical search might only find functions containing the word `login` and functions/classes appearing in its call hierarchy. Our semantic search, however, queries the narrative-like summaries. It understands the entire authentication flow like it's reading a story, piecing together the plot points from different files to give you a complete picture.
It works like magic.
Working on something similar. Legacy codebase understanding requires this type of annotation, and “just use code comments” is too much of a blunt instrument to too much good. Are you storing the annotations completely out of band wrt the files, or using filesystem capabilities like metadata?
This type of metadata itself could have individual value; there are many types of documents that will be analyzed by LLMs, and will need not only a place to store analysis alongside document-parts, but meta-metadata related to the analysis (like timestamps, models, prompts used etc). Of course this could all be done OOB, but then you need a robust way to link your metadata store to a file that has a lifecycle all its own thats only observable by you (probably).
To add further to your idea:
You can create a hierarchy of summaries. The idea being summaries can exist at the method level, class level and the microservice or module level. Each layer of summary points to its child layers and leaf nodes are code themselves. I think it can be a B tree or a normal tree.
The RAG agent can traverse as deep as needed for the particular semantic query. Each level maintains semantic understanding of the layer beneath it but as a tradeoff it loses a lot of information and keeps only what is necessary.
This will work if the abstractions in the codebase are done nicely - abstractions are only useful if they actually hide implementation details. If your abstractions are good enough, you can afford to keep only the higher layers (as required) in your model context. But if it’s not good, you might even have to put actual code in it.
For instance a method like add(n1, n2) is a strong abstraction - I don’t need to know its implementation but only semantic meaning at this level.
But in real life methods don’t always do one thing - there’s logging, global caches etc.
Tell me more!
The agent I’m developing is designed to improve or expand upon "old codebases." While many agents can generate code from scratch, the real challenge lies in enhancing legacy code without breaking anything.
This is the problem I’m tackling, and so far, the approach has been effective. It's simple enough for anyone to use: the agent makes a commit, and you can either undo, squash, or amend it through the Git UI.
The issue is that developers often skip reviewing the code properly. To counter that, I’m considering shifting to a hunk-by-hunk review process, where each change is reviewed individually. Once the review is complete, the agent would commit the code.
The concept is simple, but the fun lies in the implementation details—like integrating existing CLI tools without giving the agent full shell access, unlike other agents.
What excites me most is the idea of letting 2–3 agents compete, collaborate, and interpret outputs to solve problems and "fight" to find the best solution.
That’s where the real fun is.
Think of it as surgeons scalpel approach rather than "steam roller" approach most agents take.
I'm still not convinced that separating README.md and AGENTS.md is a good idea.
I've also been debating this: https://technicalwriting.dev/ai/agents/#gotta-keep-em-separa...
(Quoting from that post)
Arguments in favor of keeping them separated:
* Writing style. In agent docs, using all caps might be an effective way to emphasize a particular instruction. In internal eng docs, this might come off rude or distracting.
* Conciseness vs. completeness. In agent docs, you likely need to keep the content highly curated. If you put in too much content, you’ll blast through your API quotas quickly and will probably reduce LLM output quality. In internal eng docs, we ideally aim for 100% completeness. I.e. every important design decision, API reference, workflow, etc. is documented somewhere.
* Differing knowledge needs. The information that LLMs need help with is not the same as the information that human engineers need help with. For example, Gemini 2.5 Pro has pretty good built-in awareness of Pigweed’s C++ Style Guide. I tested that assertion by invoking the Gemini API and instructing it Recite the Pigweed C++ Guide in its entirety. It did not recite in full, but it gave a detailed summary of all the points. So the Gemini 2.5 Pro API was either trained on the style guide, or it’s able to retrieve the style guide when needed. Therefore, it’s not necessary to include the full style guide as AGENTS.md context. (Credit to Keir Mierle for this idea.)
Arguments against:
* Duplication. Conceptually, agent docs are a subset of internal eng docs. The underlying goal is the same. You’re documenting workflows and knowledge that’s important to the team. But now you need to maintain that same information in two different doc sets.
> Writing style. In agent docs, using all caps might be an effective way to emphasize a particular instruction. In internal eng docs, this might come off rude or distracting.
To pile on to this, an agent needs to see "ABSOLUTELY NEVER do suchandsuch" to not do suchandsuch, but still has a pretty fair chance of doing it by accident. A talented human seeing "ABSOLUTELY NEVER do suchandsuch" will interpret this to mean there are consequences to doing suchandsuch, like being fired or causing production downtime. So the same message will be received differently by the different types of readers.
Negative assertions can lead to unwanted weights in the context.
I've found positive assertions to be more predictable.
This. When doing Stable Diffusion, I have noticed this as well. Adding negatives can sometimes lead to the opposite results.
From what I can tell, if you say "no computers" for example (ie adding computer as negative), you are setting the scene for something like "where there should be computer, there is not".
I can't better describe this phenomenom, only that it can completely change the output in unexpected unwanted ways.
AB - B = AC
Do you mind sharing a specific concrete example? I'm curious.
I can, I don't have a specific example I've used to give you in this moment. And trying to share an exact example would read like a double negative.
The general rule of thumb is only put what you want in context. If you put instructions of what not to do in context, those tokens can be misunderstood and create unintended/unwanted steering of the model.
A fair example would be testing for positive sentiment. Consider weight of tokens appended to context, phrase instructions or questions to be neutral or positive.
e.g. Some phrases and their impact:
- "Is the tone of the user message positive?" will be biased for a false positive.
- "Analyze the tone of the user message?" will be more neutral and less biased.
- "Is the tone of the message negative?" will be biased for false positives when evaluating for negative tone.
Using all caps will actually cause GPT-5 to not function effectively. Have a look at the GPT-5 tuning documentation for coding.
At this point, README.md becomes the "marketing/landing page markdown" and AGENTS.md/CLAUDE.md becomes the ones you visit to get an overview of the actual code/architecture/usage.
For ages, many projects have README.md for marketing/landing page (i.e. users) and CONTRIBUTING.md for developers.
Why we don't treat coding agents as developers and have them reading CONTRIBUTING.md is baffling to me.
I feel like as a human you should still do it like you said. But in the current state it’s advantageous to give the LLM proper instructions which are distinct to human instructions. LLMs aren’t drop in replacements for developers … yet (or never).
I had the same thought as I read this example. Everything in the AGENTS.md file should just be in a good README.md file.
My READMEs don't have things like "don't run the whole test suite unless I instruct you to because it will take too long; run targeted tests instead".
Why not? "For most development we recommend running single/specific tests since the whole suite is slow/expensive." sounds like a great thing to put in the readme.
That seems exactly like something you would want to tell another developer
You're going to include specific coding style rules in your README? Or other really agent-specific things like guidance about spawning sub-agents?
They are separate for a good reason. My CLAUDE.md and README.md look very different.
Why would you publish agent specific things to your codebase? That's personal preference and doesn't have anything to do with the project.
README often contains only basic context for the project and instructions for basic tasks like running it and building it from source. If additional information for developers, like coding conventions, is short enough compared to the rest of the README then it sometimes gets added there too, but if there's a lot of it then it's frequently kept elsewhere to prevent README from getting overwhelming for end users and random people just checking out the project.
I don't think anything requires a README.md to be monolithic. They often provide the introductory material that you mention here, then link out to other appropriate files for contribution guidelines, etc.
It should not contain personal preference. It should contain project conventions.
Project guidelines, how to build your project, where to find or implement different types of features, are not personal preference. If different members of your team disagree on these things, that is a problem.
To share the most effective workflows so people don't have to muddle around figuring out what to do?
You're going to try to tell people how to code with agents in the readme? Why?
It is. README is for humans, AGENTS / etc is for LLMs.
Document how to use and install your tool in the readme.
Document how to compile, test, architecture decisions, coding standards, repository structure etc in the agents doc.
Compile, test, architecture would be very welcome in the readme too Id wager
Where contributors are the audience, yes. For things like libraries, I care about those things only if I run into a bug, and have enough resources to attempt a fix.
It can help even when using the library and not contributing. It helps you to use the api better imo, because usually the abstraction is not perfect and having even a general sense of how the sausage is made will prevent you from falling victim to gotchas. But then on the downside it lowers the mystique of the library. Some coders prefer to be magicians.
Why would these things not be relevant for humans?
They are relevant but dumping it all into one document in the project root isn’t as optimal for humans as it is for agents, especially since a lot of that information is irrelevant to someone landing on your repo, who probably just wants to add it to their dependency manifest or install the app followed by usage instructions geared to humans.
Agents are capable of semantic search and reading an entire directory devoted to human readable docs. So I'm not sure this is a particularly good argument. Just make it clear where to find what.
Because managing an AI’s context is important and you don’t want to put stuff in there that’s not relevant.
Just because they can read it and understand it doesn’t mean there are no better alternatives.
That's also not a strong argument?
Agents often have system prompts specific to their purpose. Having a single dump of agent instructions will increase noise in the context.
We have CONTRIBUTING.md for that. Seems to me the author just doesn't know about it?
There's a lot of shit in my claude.md that would be condescending to a human. Some of it I don't even mean, it's just there to correct egregious patterns the model loves to do. I'm not gonna write "never write fallback code" in my readme, but it saves a lot of time to prevent claude from constantly writing code that would silently fail if it got past me because it contains a fallback path with hardcoded fake data.
One reason to consider is around context usage with LLMs. Less is generally better and README.md files are often too much text some of which I don’t want in every context window.
I find AGENT.md and similar functioning files for LLMs in my projects contains concise and specific commands around feedback loops such as testing, build commands, etc. Yes these same commands might be in a README.md but often there is a lot more text that I don’t want in the context window being sent with every turn to the LLM.
Some time ago a lot of projects had a README and a BUILD/README.build/DEVELOPMENT file... I think AGENTS.md is more akin to this last file.
We find it useful:
* Agents still kinda suck so need the help around context management and avoiding foot guns. Eg, we make a < 500loc ai/readme.md with must haves, links to others, and meta how-to-use
* Similar to IaaC, useful to separate out as not really ready the same way we read it, and many markdowns are really scripts written in natural language, eg, plan.md.template
Perhaps. I let Claude put whatever it wants in its Claude file and check it’s not batshit from time to time, where I’m very protective of the high-quality README I write for humans. The Claude file has stuff that would be obvious to a human and weird to jam into the README (we use .spec.ts not .test.ts) but that Claude needs in order to get things right.
I feel like humans are slowly being tricked into maintaining proper documentation for their projects.
Joking aside this is kind of how I'm pitching it to our team. Even if LLMs don't significantly improve productivity writing code they will at least get us to document everything in a similar amount of time.
"Mission. Fucking. Accomplished."
https://xkcd.com/810/
Isn't the promise of AI that we don't have to adhere to precise formats? We can just write it down in whatever format makes the most sense to us, and any impedance mismatch is on the machine to figure out?
Just the filename is standardized. The contents aren't, which is exactly right. From the site:
> Are there required fields?
> No. AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide.
No, structure and format matters, even if it may not be precise code syntax
Still need to write it down to make it explicit. The longer the writing gets the more a structured approach is suitable for the human writing and maintaining the instructions.
Yet every agent I use (Claude Code, Gemini and Aider) uses their own custom filename.
It would be nice if it was standardized. Right now I’m using ruler to automate generating these files for all standards as a necessary evil, but I don’t envision this problem being solved soon. Especially because these coding agents also use different styles for consuming MCP configs.
https://github.com/intellectronica/ruler
My (slightly cynical) take is that they're trying to create whatever vendor lock-in they can, so standardization feels hits a bit too close to commoditization
Jules uses AGENTS.md, which indicates that Google is on board with it as the standard. If Gemini Code Assist continues to be a thing (I'm not sure whether Jules is intended to succeed it) then presumably it will support AGENTS.md as well. In the meantime you can configure Gemini Code Assist to use an arbitrary filename.
I don't see a reference to a specific filename in Aider's documentation, can you link to it?
Anthropic appears to be the major holdout here.
While I understand why... ruler seems like something we should not need
Including artifacts like this which are intended only to be consumed by ai defeats the entire point.
Agent-specific guidance like this rubs me the wrong way as well. The SoTA coding agents shouldn't need this much babysitting IMO. There are valid things that are not code that should be a part of the repository, like code formatting preferences (but ideally as linter rules the agent can just run, not prose), information about structuring of the code base (but as CONTRIBUTING.md or something else human-centric which the agent should pick up), documentation (either as source or as a link, again, not agent-centric) etc. I might be blanking on something that is truly agent-only and doesn't fit in a human-centric document or location better, but even if I am, that should be a minimal amount of instructions compared to what should go into the human-centric prose in the code base and be more widely valuable than just for the agent.
Fair point, but if it's minimal and useful for agents, I'm okay with it.
Humans and AIs have different weak spots: we can infer intent from convention, but an AI often struggles unless you spell it out. Ignoring that gap just to keep things "purely human" feels counterproductive. Agents deserve some sympathy.
In my opinion an AGENTS.md file isn't an artifact at all (in the sense of being a checked-in part of the codebase), it's part of the prompt. You should gitignore them and use them to give the LLM a brief overview of the things that matter to your work and the requests you are making.
every example in the wild has these checked in and treated like a lock file where everyone is scared to touch it and introduce weird behavior.
personally i think this pattern is a dead end and trying to build deterministic agentic behavior on top of inherently non-deterministic systems is a fools errand.
I mean, by construction you're only ever going to see the examples where people checked them in and published that. It doesn't mean that other people aren't getting more use out of local instructions customized to their particular work.
would be genuinely interested to see data on that, you are right that there is a selection bias for only seeing what I'm describing.
The entire point of AGI maybe. But until we get that, if it's useful then people can do it.
In what way is this a format or standard? It's just markdown in a namespce
You could get this page down to under 100 words by simply having it say "the name of the file LLM agents will look at for instructions on the repo is AGENTS.md; that's it, that's the standard".
It's a real problem! Every agent right now has their own weird filename. I love David Crawshaw's sketch.dev, but for reasons passing understanding they choose "dear_llm.md" for theirs.
I created a ticket for adding AGENTS.md support.
edit: They're on it. Not everything has to be complex; sometimes somebody just has to do it.
Easy story points
Standards derive their value precisely from being simple and widely adopted - think of .gitignore, CONTRIBUTING.md, or LICENSE files that work because everyone agrees on their location and purpose.
.gitignore is not a standard: it’s a format used by one tool. A few other tools piggy-back on it (e.g. ripgrep ignores paths matching in .gitignore, .hgignore, &c. by default), not infrequently to confusion.
CONTRIBUTING.md is not a standard: it’s a convention pushed by one platform, used by some projects (but many more will not write down such information, or put it in a README file, or put it in some other documentation).
LICENSE is definitely not a standard: it’s one of a wide variety of names people use to hold licensing information, which some tools will be able to detect. I just looked through my /usr/share/licenses, of 1135 files, only 300 are named LICENSE—it’s the most popular single name, sure, with COPYING next at 182, but it’s still definitely a minority, though in certain ecosystems it may be more popular. Any license-detection tooling will be scanning for a lot more file names. “LICENSE” is a very weak convention, compared with the others.
All the different coding agents put their "rules" in different places: .cursor, CLAUDE.md etc..
It makes no sense and it really needs standardisation. I hope this catches on.
As a workaround you can add a wrapper launcher script that symlinks them and then removes the symlink after you exit
Strange website. It is made by OpenAI. I suppose they are doing this to gain visits and as marketing positioning?
There is no format here, just a filename.
Also, Anthropic/Claude is a glaring omission. I suppose people can use symbolic links if they want to and point CLAUDE.md at AGENTS.md.
it's actually by sourcegraph and it's been up since may.
Here's where it used to go: https://web.archive.org/web/20250702163859/ampcode.com/agent...
Here's their announcement
https://ampcode.com/news/AGENT.md
The openai thing is some recent partnership I'm guessing
Interesting enough, Sourcegraph had agent.md which now 301's to agents.md (with the s).
Interestingly, the old one mentioned CLAUDE.md and ln -s, but the new one does not. The whole website is just a marketing/partnerships battle, it seems.
hi, one of the folks behind this. Back in May, @sqs acquired the domain and launched the website above, committing to relocate if the agents.md domain could be acquired. In July, I put out [1] RFC 9999 as a call to the industry that we need to fix this mess. Shortly afterwards OpenAI was able to obtain the domain and thus we (Amp) followed through on the commitment and worked with other vendors to move from AGENT.md to AGENTS.md.
[1] https://web.archive.org/web/20250708160846/https://ampcode.c...
This seems much more insightful than the website in the OP. Thanks!
now? maybe so. But when it was a sourcegraph only thing (really out of their amp project, which is like byterover/cline cloud/roocloud) not so much - they really don't expend much on marketing hype.
I mean I knew about it the day it launched but I'm /probably/ crazy.
Claude is omitted, because Claude is the only agent that still doesn't support the standard filename convention.
The website could mention that. Since I did not discover this website's affiliation with OpenAI until I found the GitHub repo, I had assumed that this is purely an informative website, and as such I expected it to mention the agent tool most people I know use (Claude). Even if that mention is "Claude does not support this yet".
So the solution to using AI so you don't have to code, is to try to write some kind of pseudocode in AGENT.md and hope the AI does a bit better?
Why does it seem that the solution to no-code (which AI-coding agents are) always comes back to "no-code, but actually there is some code behind the scenes, but if you squint enough it looks like no-code".
> So the solution to using AI so you don't have to code, is to try to write some kind of pseudocode in AGENT.md and hope the AI does a bit better?
Umm, no. Where did you get that idea?
The purpose of the agent.md file is to give it instructions. Nothing about no-code AI said there would be no instructions...
I'm old enough to remember when computer code was called "instructions".
Eg, the 6502 instruction set. https://www.masswerk.at/6502/6502_instruction_set.html
History doesn't repeat but it rhymes!
They are still called instruction sets.
> History doesn't repeat but it rhymes!
The only similarity is the word
I think we lost something pretty big in this formulation.
With Claude code and others, if I put a context file (agent.MD or whatever) in a project subfolder, e.g., something explaining my database model in with the related code, it gets added to the root project context when the agent is using that subfolder.
It sounds to me like this formulation doesn’t support that.
That's sort of this? I guess the exact behavior would depend on the agent.
> Place another AGENTS.md inside each package. Agents automatically read the nearest file in the directory tree, so the closest one takes precedence and every subproject can ship tailored instructions. For example, at time of writing the main OpenAI repo has 88 AGENTS.md files.
But no, that's the opposite - here sub-context files REPLACE the ones above it rather then augmenting it - and I think that deviating in this way is kinda' dangerous in that user's might not notice this difference.
I think it's just poorly written. Further down:
> What if instructions conflict? > The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything.
This seems appropriate for hierarchical AGENTS.md files? How would it even realize there was a conflict if it hadn't read both files?
I'm rolling my own like this [0]:
.agdocs/
├── specs/ # Task specification files
├── conf/ # Configuration files
├── guides/ # Development guides for agents
└── swap/ # Temporary files (gitignored)
Every markdown file in guides/ gets copied to any agent (aider, claude, gemini) I kick-off.
I gitignore this .agdocs directory by default. I find this useful because otherwise you get into _please commit or stash your changes_ when trying to switch branches.
But I also run an rsync script before each release to copy the .agdocs to a git tracked mirrored directory [1].
[0]: https://github.com/sutt/agro/blob/master/README.md#layout
[1]: https://github.com/sutt/vidstr/tree/master/.public-agdocs/gu...
Make sure to check out https://agent-rules.org/ as well for more background on this initiative. More and more tools are adopting the standard.
Amp used to have an "RFC 9999" article on their website for this as well but the link now appears to be broken.
You can symlink your Cursor / Windsurf / whatever rules to AGENTS.md for backwards compatibility.
That draft RFC you mention is superseded by https://agents.md. Now that Amp uses AGENTS.md (https://x.com/sqs/status/1957945824404729997), I made all the former agent file stuff on https://ampcode.com just redirect to https://agents.md.
Gotcha - this is what I had in my history: https://ampcode.com/AGENT.md
For me, that gives a 404 with no obvious way to get to https://agents.md, I think either a hyperlink or redirect would be nice to have as well.
Thank you for pointing that out. Just pushed a fix, will be live in ~5-10min.
Works now, thank you! :)
Ok, I looked at your agent-rules and it sounds good except for a couple things ...
"Guidance for Use"
Your preference for bullet lists over headers is odd. This comes down to what works best with the models - they are interpreting it. This is a moving target. If you believe that your suggestion works best you should provide some sort of evidence. The default would be to not even get into that sort of thing.
Non-Hierarchical AGENTS.md
Claude-code, Gemini, and GHCP all support hierarchical context files. Your proposal and this new one from OpenAI and friends do not, and I think that is a shame.
I did not write agent-rules, I'm just linking to it.
This looks like a normal README.md to me. Why do we need a separate file?
It's really supposed to supplement README.md, but targeting an agentic coding loop.
E.g. "Before each commit, do X and Y to validate the changes."
README.md should have been called HUMANS.md in retrospect
I have a tiny, relevant weekend project:
https://github.com/cortesi/agentsmd
This is a command-line tool that lets you generate your AGENTS.md and CLAUDE.md files from common sources. So, for instance, if you have Rust-specific guidance for models, you can define it once, and then automatically include it in any project that contains Rust based on the `lang()` language matcher.
This is one of those small tools I now use many times a day to maintain and update ubiquitous agents files. Maybe other folks will find it useful too.
We are going the opposite way, putting instructions in md files and putting instructions in the Claude.md file when it should read those instructions.
I've came across llms.txt files in few services. I don't know how the agents.md compares to the llms.txt files, but I guess they could pretty much have the same content. See more also here https://llmstxt.org/
Anyhow, I have made few interesting observations, that might be true for the agents.md also:
Agents have trouble with these large documents, and they seem to miss many relevant nuances. However, its rather easy to point them to the right direction when all relevant information is in one file.
Another thing is that I personally prefer this style of documentation. I can just ctrl+f and find relevant information, rather than using some built in search and trying to read through documents. I feel that the UX of one large .txt file is better than the documentation scattered between multiple pages using some pretty documentation engine.
Currently I am building a new JS web toolkit on the side with AI assistance for faster progress, and I came to have some prompts folder in the project root that I just drop into the agents (like cursor CMD+I) and point it to a direction (file/folder).
https://github.com/Anonyfox/raven-js/tree/main/prompts
I think we should not split README and AGENT into different documents - the way its heading is that the coding agents are optimized to "act as" humans and use tools like them more and more - and understanding how something works or how to do something should be aimed for humans and expecting AI tools to pick it up like a human would... if they don't currently then probably they will in the the future.
Kind of my first thought... seems to me this could be part of README.md, or as another suggested CONTRIBUTING.md
I tend to put a lot of this type of info into the readme anyway... for more complex projects, I'll include a docs/ directory with more markdown, images as needed, etc.
For that matter, I think context hints from the likes of Dockerfile(s), compose, and .github/workflows also can serve a dual-purpose here.
Agreed, between this and MCP we are quickly approaching the point where you basically need to document your codebase twice.
Its completely pointless
I like the concept and have built my own context management tool for this very purpose!
https://github.com/jerpint/context-llemur
Though instead of being a single file, you and LLMs cater your context to be easily searchable (folders and files). It’s all version controlled too so you can easily update context as projects evolves.
I made a video showing how easy it is to pull in context to whatever IDE/desktop app/CLI tool you use https://m.youtube.com/watch?v=DgqlUpnC3uw
Why this even required..
It makes people feel like they're in control of the text prediction agent when actually it'll only follow this some of the time.
1. I tell Copilot until I'm blue in the face that the project must build.
2. Copilot assures me it has fixed the build errors it created.
3. Still get build errors
4. Run out of tokens so I come back next month and repeat.
I noticed the example of ln command symbolic linking of the files on the front page. I think it’s interesting how the cli aspect of agent coding and tooling is pushing command prompt / powershell users to become familiar with the *nix shells and commands. In the enterprise Microsoft Visual Studio IDE world some of its very alien. I regularly do tutorials for team members that just think of the cli as a place where they execute ps1s, haven’t used wsl2 or git bash profiles or have limited exposure by way of dealing with containers. Not a criticism.
New Phoenix Framework projects have an AGENTS.md file in the root! It's really cool. https://x.com/alkadaemon/status/1955348410145358199
https://github.com/phoenixframework/phoenix/blob/main/instal...
That’s insane. 3000 words of prose boilerplate about the language and framework. Sounds like you need, at the very least, some sort of import directive. I have no idea if “Read and follow the instructions in path/to/phoenixframework/AGENTS.md.” would work.
And then the eclectic mixture of instructions with a variety of ways of trying to bully an intransigent LLM into ignoring its Phoenix-deficient training… ugh.
The thing about language models is that they are *language* models. They don't actually parse XML structure, or turn code into an AST, they are just next-token generators.
Individual models may have supplemented their training with things that look like structure (e.g. Claude with its XMLish delimiters), but it's far from universal.
Ultimately if we want better fidelity to the concepts we're referencing, we're better off working from the larger/richer dataset of token sequences in the training data--the total published written output of humanity.
Works great, why the _ugh_
Ultimately that's what matters.
If you’re not intended to alter it, we have a technique for such things: links, so that it can be maintained independently.
If you are intended to alter it… 3,000 words of prose is awful, fuzzy and wildly imprecise.
If you’re expected to add to it before and/or after, which I imagine you are, that’s even worse, whether you’re expected to modify the provided block or not.
If it was like Linux config is often done, with a /etc/thing-name.d/ directory containing files that will be applied in name order (leading to the common convention of two digit numbers: 10-somethingearly.conf, 50-usersomething.conf, 90-quitelate.conf), it might make sense—you just have your 10-phoenixframework.md. But when it’s just one file… well, y’know, there’s a reason we don’t normally maintain huge projects in a single file, even if some projects like to be able to be distributed in that way and have a build process to squish all their source code into one file (e.g. SQLite, Flask).
I’m not denying that it may work to vastly improve LLM performance, but I am absolutely saying that this is horrifying, in the amount of nonsense required, but still more in the way it’s being delivered.
dont forget, you pay real money every time it is tokenized with every prompt!
I was thinking about this too, but the problem is that different models need to be prompted differently for better performance.
Claude is the best model for tool calling, you might need to prompt less reliable models differently. Prompt engineering is really hard, a single context for all models will never be the best IMO.
This is why Claude Code is so much better than any other agentic coding tool, because they know the model very well and there is an insane amount of prompt engineering went into it.
I tried GPT-5 with OpenCode thinking that it will be just as good, but it was terrible.
Model-specific prompt engineering makes a huge difference!
Looks very promising. If you need to know a bit more about it, watch this video https://youtu.be/TC7dK0gwgg0?si=Eb5TK0gPvgahVbWQ
Aside from it being "instructions for agents", I'm not sure I understand how this isn't just a markdown file that more or less reads like a readme that targets more junior engineers.
No, you nailed it. The rest is theater.
Protocols for llms are funny because they are designed to accept any text as input and they don't really implement the protocol anyways, so it's just a consumer side restriction of the input space.
I'm sure there's plenty of overlap with just using a CONTRIBUTING.md or even the README.md development setup. Especially since LLMs should understand guidance in human instructions.
This isn't a format. It's just a convention that literally boils down to: Put LLM instructions in a text file and call it AGENTS.md.
Well, thanks I guess?
But it's open! That's the most important part I think. If it wasn't open, you would have to pay a license fee for the owner of the AGENTS.md format. But since it is open, you can simply create a file named "AGENTS.md" without paying anyone!
Holy sh*t, I accidentally for got the "S" and was directly forwarded to PayPal.
Yes, most file managers require a payment when creating a file with a non-open name.
I haven't really done anything serious with Claude Code, but today I tested starting claude in ~/claude/test, and told it to list my home dir, which it then did.
Is there a way to tell tools like Claude Code that it must never leave ~/claude/test, and don't event think about using absolute paths, or relative paths which contain `..`?
it's already read only outside of project directories (except for Bash tool); your only further option is to wrap it in a sandbox, `bwrap` is perfect for this
"don't even think" is in the default system prompt, but it's inherently indeterministic and can be overridden with a direct instruction as you have seen
Wow! Thank you for bringing bubblewrap to my attention. What an amazing tool! This opens so many doors.
run it in a vm, running an agent directly on your machine is madness
Chroot jail?
I am not anti-AI - perhaps obviously.
But this is wildly insufficient as a standard, and wholly lacks innovation on the dimension of 'context management' as a discipline.
what about for plan.md, does everyone just trash the plan once the development is done ? Sometimes the final generated plans (created after iterating with the model on it) are as good as design documents and can be useful for future enhancements, so trashing them doesn't feel right, whereas checking them in seems like too many non code related files in every directory
Not having support for importing files makes this dead on arrival. It means you can’t have a local file with local environment details.
There’s an issue open about this in the repo already. I mean if you’re going to copy the CLAUDE.md concept, don’t leave out one of the most useful parts.
it does though, the same way that an llm can trace imports / dependencies through any coding language.
``` If adding tests, read @./TESTING_INSTRUCTIONS.md
```
Why not use contributing.md?
https://docs.github.com/en/communities/setting-up-your-proje...
The agents.md minisite implies agents.md files should be useful for humans and robots alike:
> Commit messages or pull request guidelines, security gotchas, large datasets, deployment steps: anything you’d tell a new teammate belongs [in agents.md] too.
Agents are just another type of contributor. Maybe agents.md is just what we need to finally trick devs into writing concise docs.
How are you actually running this in practice with Claude Code? Do you just tell Claude to always read and follow AGENTS.md, or do you also use an MCP server to strictly control which commands (like pnpm test or pnpm lint) it can run? I’d love to hear what workflows or best practices have worked well for you in day-to-day use.
I have Claude Code maintain the files and reference links between them.
Isn't it consuming more tokens ?
Feels like less than jr vibe coding to me.
It looks up what it should and shouldn’t do. I can make sure it always or never does something a certain way again.
Claude max is also worth it.
When did this happen - first corporates where wary of using AI generated code due to copyright concerns and now we have full embrace?
I guess we are not yet in the phase where everyone will be scrambling to find competent engineers to clean-up the AI mess in their codebases?
It is only the "AI" companies that force their employees to babysit LLMs, so very few real projects do this in the wild.
I wish claude-style imports ("general guidelines: @CONTRIBUTING.md") and bash execution ("available repositories: !`ghq list`") were a part of the spec
Even claude supports bash commands only in slash prompts; you could use a SessionStart though
Next thing they'd invent a special syntax to put explanations for agents in the code, which is exactly the same as comments, but with attached AI hype so maybe people would actually do it.
cant you simply prompt it to read the code and create whatever md you need it to lol what is the point of this
Fundamentally, AI still remains completions.
Agents, tools etc. all cover up the fact that it's completions
Still a remarkable, extraordinary technology. But the nomenclature distracts from how it works.
AGENTS.md is a great way to give context to get better completions.
"Computing is just 1s, 0s and logic gates"
Good idea. Just the other day I was thinking of writing a templatized generator for coding agent instructions for various agents like Claude Code, GitHub Copilot and others that use their own unique file convention.
What exactly here is an “open format”?
This is just a text file containing stuff. As many have said we have README, CONTRIBUTING…
Unless every tool is actually going to use it, this is yet another standard piled up.
AGENTS.md fine but I hope the pattern sticks around. Another way is to use the README.md with different sections for humans or agents. As agent content windows expand to being able to load all the context in a repo, it will not matter much.
Pro-tip: For GitHub Copilot which doesn't yet support AGENTS.md, you can create a symlink if your GH Copilot instruction files are defined on a per-repo basis:
ln -s AGENTS.md .github/copilot-instructions.md
Pretty advance stuff. Vibing is definitely a difficult skill to learn.
I've been calling this context.md in my projects (alongside a progress.md for TODOs and breaking down complex tasks). I don't care what we call it as long as we settle on a convention.
The ironic thing about this is that it's equally valuable for anyone contributing the project. But for some reason it's only prioritized to make LLMs follow styleguide, humans need not apply (?)
I like this. I was using README.md, like many folks, which wasn’t bad. The main issue is the agent is typically updating it as well while building out the prototype.
I have a much shorter AGENTS.md:
"No."
Dumb question from a guy who just set up Claude Code for the first time yesterday: would this be the equivalent of `CLAUDE.md` in a project directory?
Yes.
Shouldn't you already have these instructions written out? Seems like AI has just motivated developers to finally write documentation.
The agents instructions file needs to be hierarchical; It's a pain managing multiple agents.md files with a lot of duplication between them for different projects, even in a mono-repo. we probably need a tool for this.
In any case, I increasingly question the use of an agents file. What's the point, then the agent forget about them every few prompt, and need to be constantly reminded to go through the file again and again?
Another thought: are folks committing their AGENTS.md? If so, do you feel comfortable with the world knowing that a project was built with the help of AI? If not, how do you durably persist the file?
Agree on the need for hierarchical agents.md. I thought that was kind of standard and I am surprised that this proposal doesn’t support that.
> do you feel comfortable with the world knowing that a project was built with the help of AI?
I would be deal-breakingly concerned if I thought someone was actively trying to hide the fact from me.
Do all ai agents only include a single AGENTS.md, closest in the hierarchy? Where do people put common instructions or do they just copy and paste?
The agents are really flexible. You can just tell them read whatever file/folder.
Hey guy looking at this thread from 2035, so you know... there are still plenty of folks in the industry that knows that this is dumb. We are just too tired of fighting nonsense... we just won the web3/blockchain craziness and now this.
I didn't know .md TLD is available!
just use a good agent like augmentcode that can look at relevant context across your repository and then you can name it whatever you want.
I think this is a good thing - I would like to see the same pattern standardized for the memory system of all the different agents.
Unfortunate that two of the most-used tools (Claude Code, Gemini CLI) don't support it.
What does "support" for this format mean beyond "reading the file without explicit prompting"?
Like, as the end-user, if I copy-paste "Please see AGENTS.md in the project root for some information on the project" have I filled the gap?
Or is the LLM ingesting this file in some special way I'm losing out on?
>Like, as the end-user, if I copy-paste "Please see AGENTS.md in the project root for some information on the project" have I filled the gap?
Probably, yeah. It would cause an extra tool call at the start of every session, though, so a symlink might be preferable.
wrote this protocol like a month ago :)
https://github.com/level09/air
Prediction: this means extra work for developers. it also means extra potential abuse and risk through agents. the agents.md will sometimes be outdated or inconsistent with the readme. even the readmes are sometimes outdated or inconsistent with the code. some developers will interpret agents.md as compiling code for the agents to use, not for the user's to use, so maybe you're not even compiling the same code the same way a human should and expectations are broken. it's only a contextual efficiency if it's reliable too, because errors can mean having to use even more context accounting for it.
better idea since agents will already be cursed to do these things:
- any decent readme should have titled sections unless it's small
- if it's small, just feed the entire readme into it
- if it's large, provide it with a list of readme sections and let it choose which ones are relevant.
- also highlight which parts of the markdown include code blocks.
- if all else fails and it's huge without sections, just use RAG.
- if your model runs fast enough, then even if it's huge, just feed the whole thing in so you avoid the risks of RAG. setting up new software can be important enough that you may as well get it right.
people couldn't be hassled to make things accessible to the blind or visually impaired really, why suddenly should they be all excited to make everything accessible to AI? besides, agents.md comes with psychological baggage like, "i'm presuming my project is interesting enough to be used by agents!". just use the readme. it's basically always there and then in most cases you won't have to do 2 requests, you can just do 1.
if "agents.md" is supposed to be anything, it should be a locked file or special URL generated by github for your repo that always mirrors the relevant instructions in the readme so there's some higher reliability. then anyone that specifically wants to improve agents.md can simply follow some conventions in the readme file to make sure understanding is maximized. essentially, a github agent generates agents.md for other agents. if the github agent can't understand the readme well enough to produce an agents.md, what chance would your agent have? if the github agent feels like there are contradictions or confusion, it can automatically report that to the developers so they can sort it out.
besides, github themselves could have motivation to do this if they are destined to be slammed with tons of bot traffic they have no way to sufficiently block. at least this way maybe they can make it more efficient and it becomes another valuable feature of the platform.
If the context is not good for a Llm is also not good for a human. All this magical nonsense that is blooming around AI is tiresome, it needs to stop. Programming is not tarot reading or a slot machine. We cannot leave the security and robustness of our systems into such heuristics.
I `ln -s` mine to CLAUDE.md for convenience
So this is a filename, not really a format?
We can't call it robots.txt?
pretty useless for big projects if it doesn't support modular instruction files (with apply regexes)
Markdown is certainly easy for humans to write, but as OpenAI pointed out last week, wouldn’t an XML-based format be easier for LLMs to parse and understand?
LLMs should make it easier for us, not the opposite
they are just moving goal posts because agents still largely suck for everything except a couple of super saturated problem domains that really shouldn’t require anything special from a dev anyways
> but as OpenAI pointed out last week
What are you referring to here?
https://cdn.openai.com/API/docs/gpt-5-for-coding-cheatsheet....
From OpeAI's last week document for coding with gpt5.
> #3. Use XML-like syntax to help structure instructions
I don't know if GPT-5 is an exception and is overcooked on XML specifically, but in general Markdown and XML seem to work about equally well for LLM inputs, the important part is just that they like hierarchical structured formats. The example on that page could probably be replaced with:
Without any meaningful change in effectiveness.This makes me hate AI even more
If agents are so smart why not using what already exists for guiding humans, like README.md or literally any md/rst resource they can find in the repo? This is so stupid, and we're allowing it to happen.
Honestly the stuff in my llm instructions file is basically just a readme that is just as good for human consumption. Why aren't we just calling it a readme then?
we allowed the js ecosystem to happen
opencode made one of these for me when I did an /init in my existing project
I can’ take this seriously, ever since they started talking about llms.txt, thousands of apps spawned promising increasing AI SEO by generating such file. I’ve created one myself for several websites and have seen 0 impact. I guess agents.md will have the same fate.
lol, if the primary outcome is better documentation...i'll take it
Honestly, this is some of the most bizarre shit I’ve ever seen.
The day AI and AI adjacent slop is no longer polluting the front page is the day when some other random fad takes hold I guess.
Did they just reinvent the Makefile?
Make is a command runner, no? It's completely different.
oh good, another one.
[dead]
These AI-oriented examples look more useful to me than most human-oriented READMEs I've seen.
Yes, writing clear examples and instructions for humans was never seen as a good use of time, but as soon as a dumb mutt of an AI needs them to do stuff, they're written, and with more compassion than was ever shown to newbies asking questions...
We've lost a bunch of contributions to open source projects because these guides weren't there to help new people contribute.
This is a sad timeline. "AI is going to replace engineers.. but first please fill this human-readable markdown file to help it understand your code". What a bunch of morons, that's just called documentation.
Instead of using AI where it can actually have positive impact on human lives like medicine, biology, et al. we're wasting huge amounts of resources and generating tons of pollution to teach it to program and steal art and books so Aunt Lily can generate a video of a dog.
> that's just called documentation.
Ironically you sound very optimistic about AI capabilities here. This implies that an AI is just as capable as a human because all they need to contribute is what a human needs to contribute.
Alternatively if you think AI is useless trash then clearly they need more than a human readme to do anything?
You're putting a whole lot of words in my mouth, I didn't say