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.
edit: They're on it. Not everything has to be complex; sometimes somebody just has to do it.
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.
It makes no sense and it really needs standardisation. I hope this catches on.
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.
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.
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.
Ultimately that's what matters.
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.
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.
> Are there required fields?
> No. AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide.
The LLM's whole shtick is that it can read and comprehend our writing, so let's architect for it at that level.
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.
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 find them more enjoyable than Uber. They’ve already surpassed Lyft in SF ridership and soon they will take the crown from Uber.
Yes, they do, the term to search is “remote assistance operator”. e.g. https://philkoopman.substack.com/p/all-robotaxis-have-remote...
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.
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.
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.
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.
“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
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.
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.
If we end up where the video presents, humans don't deserve technology of any kind.
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/
Slapping on a sign is ineffective
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_.
Analyze the repository and add a suitable agents.md
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.
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.
Reading their prompt gives ideas on how you can improve yours.
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.
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?
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.
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.
"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 situation reminds me a bit of ergonomic handles design. Designed for a few people, preferred by everyone.
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.
This aligns pretty clearly with the profit motive of most companies.
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.
> 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.
> 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?
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).
index.md
├── auth.md
├── performance.md
├── code_quality
├── data_layer
├── testing
└── etc
¹ Ideally with a better name than ".agents", like ".codebots" or ".context".
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.
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.
I guess I was one of the lucky 10000 :-)
I think all this agentic stuff could live quite happily in $REPO/.config/agents/.
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.```As well as custom agents: https://docs.anthropic.com/en/docs/claude-code/sub-agents
# 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.Maybe robot_docs?
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.
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.
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.
I've -> I have
& -> and
co. -> company
won't -> will not
it's -> it is
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.
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.
The baseline is English and that's life. I'm not a native English speaker.
/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 /home -> Users (it's not 1998 anymore)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>>.
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.
/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.
set completion-ignore-case on
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.
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/?
$HOME/accept/the/fact/that/were/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/main.c> Agents automatically read the nearest file in the directory tree, so the closest one takes precedence
I don't really care what's inside.
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.
You can just use the AGENTS.md file as an index pointing to other doc files.
This example does that -
Having an in-your-face file that links to a hidden file serves no purpose.
New standard for something that maybe false very soon is just a bad idea.
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 =)
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.
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"
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
``` // 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.
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.
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
But yes, naive coding agents will fill the context with the entire large file.
Or use urls in your main AGENTS like I do for https://gitchamber.com
The content of the AGENTS.md is the same as what humans are looking for when contributing to a project.
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.
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
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.
Also, you don’t even address their point.
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?
I would be deal-breakingly concerned if I thought someone was actively trying to hide the fact from me.
<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.
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.
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.
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).
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".
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...
Eg, the 6502 instruction set. https://www.masswerk.at/6502/6502_instruction_set.html
History doesn't repeat but it rhymes!
> History doesn't repeat but it rhymes!
The only similarity is the word
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?
Probably, yeah. It would cause an extra tool call at the start of every session, though, so a symlink might be preferable.
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.
But this is wildly insufficient as a standard, and wholly lacks innovation on the dimension of 'context management' as a discipline.
What are you referring to here?
From OpeAI's last week document for coding with gpt5.
> #3. Use XML-like syntax to help structure instructions
## Code Editing Rules
### Guiding Principles
- Every component should be modular and reusable
...
### Frontend Stack Defaults
- Styling: TailwindCSS
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.
"No."
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.
We've lost a bunch of contributions to open source projects because these guides weren't there to help new people contribute.
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.
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).
I mean I knew about it the day it launched but I'm /probably/ crazy.
[1] https://web.archive.org/web/20250708160846/https://ampcode.c...
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.
Its completely pointless
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.
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.
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.
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.
Well, thanks I guess?
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.
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.
ln -s AGENTS.md .github/copilot-instructions.md
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!
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.
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
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?
E.g. "Before each commit, do X and Y to validate the changes."
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 `..`?
"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
Even claude supports bash commands only in slash prompts; you could use a SessionStart though
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?
.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...
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.
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.
``` If adding tests, read @./TESTING_INSTRUCTIONS.md
```
> build steps, tests, and conventions that might clutter a README or aren’t relevant to human contributors.
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.
ivanjermakov•5mo ago
diggan•5mo ago
andyferris•5mo ago
Why we don't treat coding agents as developers and have them reading CONTRIBUTING.md is baffling to me.
mrklol•5mo ago
stingraycharles•5mo ago
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.
darepublic•5mo ago
silversmith•5mo ago
darepublic•5mo ago
sponnath•5mo ago
throwup238•5mo ago
goosejuice•5mo ago
stingraycharles•5mo ago
Just because they can read it and understand it doesn’t mean there are no better alternatives.
goosejuice•5mo ago
Agents often have system prompts specific to their purpose. Having a single dump of agent instructions will increase noise in the context.
crazylogger•5mo ago
furyofantares•5mo ago
blinkymach12•5mo ago
esafak•5mo ago
viraptor•5mo ago
ecb_penguin•5mo ago
sothatsit•5mo ago
They are separate for a good reason. My CLAUDE.md and README.md look very different.
bongodongobob•5mo ago
CuriouslyC•5mo ago
bongodongobob•5mo ago
ameliaquining•5mo ago
blinkymach12•5mo ago
sothatsit•5mo ago
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.
petesergeant•5mo ago
trailrunner46•5mo ago
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.
kaycebasques•5mo ago
(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.
CGamesPlay•5mo ago
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.
skhameneh•5mo ago
I've found positive assertions to be more predictable.
superfish•5mo ago
skhameneh•5mo ago
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.
taikahessu•5mo ago
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
ghuntley•5mo ago
lmeyerov•5mo ago
* 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
rogeliodh•5mo ago