19 ms·

AGENTS.md – Open format for guiding coding agents

• torginus 1y ago
  I feel like humans are slowly being tricked into maintaining proper documentation for their projects.
  • falcor84 1y ago
    "Mission. Fucking. Accomplished." https://xkcd.com/810/ https://xkcd.com/810/
  • driverdan 1y ago
    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.
• lerp-io 1y ago
  cant you simply prompt it to read the code and create whatever md you need it to lol what is the point of this
• ivanjermakov 1y ago
  I'm still not convinced that separating README.md and AGENTS.md is a good idea.
  • diggan 1y ago
    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.
    • andyferris 1y ago
      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.
      • mrklol 1y ago
        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).
  • stingraycharles 1y ago
    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.
    • darepublic 1y ago
      Compile, test, architecture would be very welcome in the readme too Id wager
      • silversmith 1y ago
        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.
        • darepublic 1y ago
          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.
    • sponnath 1y ago
      Why would these things not be relevant for humans?
      • throwup238 1y ago
        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.
  • blinkymach12 1y ago
    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.
    • esafak 1y ago
      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".
      • viraptor 1y ago
        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.
      • ecb_penguin 1y ago
        That seems exactly like something you would want to tell another developer
    • sothatsit 1y ago
      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.
      • bongodongobob 1y ago
        Why would you publish agent specific things to your codebase? That's personal preference and doesn't have anything to do with the project.
        • CuriouslyC 1y ago
          To share the most effective workflows so people don't have to muddle around figuring out what to do?
  • petesergeant 1y ago
    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.
  • trailrunner46 1y ago
    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.
  • kaycebasques 1y ago
    I've also been debating this: https://technicalwriting.dev/ai/agents/#gotta-keep-em-separated 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.
    • CGamesPlay 1y ago
      > 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.
      • skhameneh 1y ago
  • lmeyerov 1y ago
    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
  • rogeliodh 1y ago
    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.
• eats_indigo 1y ago
  In what way is this a format or standard? It's just markdown in a namespce
  • tptacek 1y ago
    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.
    • esafak 1y ago
      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.
      • TZubiri 1y ago
        Easy story points
  • ethan_smith 1y ago
    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.
    • chrismorgan 1y ago
      .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.
• stingraycharles 1y ago
  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 https://github.com/intellectronica/ruler
  • ameliaquining 1y ago
    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.
  • 4b11b4 1y ago
    While I understand why... ruler seems like something we should not need
  • conradkay 1y ago
    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
• sergiotapia 1y ago
  New Phoenix Framework projects have an AGENTS.md file in the root! It's really cool. https://x.com/alkadaemon/status/1955348410145358199 https://x.com/alkadaemon/status/1955348410145358199
  • chrismorgan 1y ago
    https://github.com/phoenixframework/phoenix/blob/main/installer/templates/phx_single/AGENTS.md 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.
    • sergiotapia 1y ago
      Works great, why the _ugh_ Ultimately that's what matters.
      • chrismorgan 1y ago
        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.
• alphazard 1y ago
  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?
  • sqs 1y ago
    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.
  • 4b11b4 1y ago
    No, structure and format matters, even if it may not be precise code syntax
  • seb1204 1y ago
    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.
• blinkymach12 1y ago
  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.
  • tptacek 1y ago
    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.
    • naniwaduni 1y ago
      ... most of which would also be valuable information to communicate when onboarding new devs.
      • ameliaquining 1y ago
        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.
        • naniwaduni 1y ago
          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.
          • deleted 1y ago
            [deleted]
• _mu 1y ago
  Make sure to check out https://agent-rules.org/ 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.
  • sqs 1y ago
    That draft RFC you mention is superseded by https://agents.md https://agents.md. Now that Amp uses AGENTS.md (https://x.com/sqs/status/1957945824404729997 https://x.com/sqs/status/1957945824404729997), I made all the former agent file stuff on https://ampcode.com https://ampcode.com just redirect to https://agents.md https://agents.md.
    • _mu 1y ago
      Gotcha - this is what I had in my history: https://ampcode.com/AGENT.md https://ampcode.com/AGENT.md For me, that gives a 404 with no obvious way to get to https://agents.md https://agents.md, I think either a hyperlink or redirect would be nice to have as well.
      • sqs 1y ago
        Thank you for pointing that out. Just pushed a fix, will be live in ~5-10min.
        • _mu 1y ago
          Works now, thank you! :)
  • tomComb 1y ago
    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.
• _mu 1y ago
  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.
• spawarotti 1y ago
  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.
  • nicklo 1y ago
    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.
    • blinkymach12 1y ago
      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.
  • wfhrto 1y ago
    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.
    • samename 1y ago
      everyone? source?
      • lenerdenator 1y ago
        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.
• TZubiri 1y ago
  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.
• tomComb 1y ago
  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.
  • neuronexmachina 1y ago
    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.
    • tomComb 1y ago
      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.
      • andyferris 1y ago
        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?
• CharlesW 1y ago
  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). index.md ├── auth.md ├── performance.md ├── code_quality ├── data_layer ├── testing └── etc 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".
  • asabla 1y ago
    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.
  • riffic 1y ago
    .well-known/
    • echelon 1y ago
      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 https://www.rfc-editor.org/rfc/rfc8615 [2] https://wiki.archlinux.org/title/XDG_Base_Directory https://wiki.archlinux.org/title/XDG_Base_Directory
• spullara 1y ago
  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.
• prmph 1y ago
  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?
  • tomComb 1y ago
    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.
  • petesergeant 1y ago
    > 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.
• deleted 1y ago
  [deleted]
• faangguyindia 1y ago
  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.
  • jzig 1y ago
    Tell me more!
    • faangguyindia 1y ago
      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.
• legostormtroopr 1y ago
  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".
  • ecb_penguin 1y ago
    > 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...
    • pmg101 1y ago
      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 https://www.masswerk.at/6502/6502_instruction_set.html History doesn't repeat but it rhymes!
      • ecb_penguin 1y ago
        They are still called instruction sets. > History doesn't repeat but it rhymes! The only similarity is the word
• meowface 1y ago
  Unfortunate that two of the most-used tools (Claude Code, Gemini CLI) don't support it.
  • neutronicus 1y ago
    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?
    • meowface 1y ago
      >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.
• deleted 1y ago
  [deleted]
• cortesi 1y ago
  I have a tiny, relevant weekend project: https://github.com/cortesi/agentsmd 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.
  • rblatz 1y ago
    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.
• indigodaddy 1y ago
  opencode made one of these for me when I did an /init in my existing project
• deleted 1y ago
  [deleted]
• aeon_ai 1y ago
  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.
  • deleted 1y ago
    [deleted]
• alfg 1y ago
  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.
• ec109685 1y ago
  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?
  • jpalomaki 1y ago
    The agents are really flexible. You can just tell them read whatever file/folder.
• albert_e 1y ago
  README.md should have been called HUMANS.md in retrospect
• nunez 1y ago
  Did they just reinvent the Makefile?
  • koakuma-chan 1y ago
    Make is a command runner, no? It's completely different.
• ekusiadadus 1y ago
  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?
  • mongol 1y ago
    LLMs should make it easier for us, not the opposite
    • thrown-0825 1y ago
      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
  • Osyris 1y ago
    > but as OpenAI pointed out last week What are you referring to here?
    • ekusiadadus 1y ago
      https://cdn.openai.com/API/docs/gpt-5-for-coding-cheatsheet.pdf 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
      • fallpeak 1y ago
        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 Without any meaningful change in effectiveness.
• ekusiadadus 1y ago
  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.
  • j45 1y ago
    I have Claude Code maintain the files and reference links between them.
    • ekusiadadus 1y ago
      Isn't it consuming more tokens ?
      • j45 1y ago
        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.
• EarlKing 1y ago
  I have a much shorter AGENTS.md: "No."
• masters3d 1y ago
  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.
• tediousgraffit1 1y ago
  lol, if the primary outcome is better documentation...i'll take it
• JaiRathore 1y ago
  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
• stellalo 1y ago
  So this is a filename, not really a format?
• throwawaybob420 1y ago
  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.
• bhaney 1y ago
  These AI-oriented examples look more useful to me than most human-oriented READMEs I've seen.
  • porker 1y ago
    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.
• surrTurr 1y ago
  pretty useless for big projects if it doesn't support modular instruction files (with apply regexes)
• baalimago 1y ago
  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 (?)
• masci 1y ago
  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.
  • Sammi 1y ago
    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?
  • thrown-0825 1y ago
    we allowed the js ecosystem to happen
• brainlessdev 1y ago
  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.
  • kristopolous 1y ago
    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.md https://web.archive.org/web/20250702163859/ampcode.com/agent... Here's their announcement https://ampcode.com/news/AGENT.md 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).
    • brainlessdev 1y ago
      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.
      • kristopolous 1y ago
        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.
      • ghuntley 1y ago
        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.com/AGENT.md https://web.archive.org/web/20250708160846/https://ampcode.c...
• anonyfox 1y ago
  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 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.
  • thrown-0825 1y ago
    Agreed, between this and MCP we are quickly approaching the point where you basically need to document your codebase twice. Its completely pointless
  • tracker1 1y ago
    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.
• thrown-0825 1y ago
  Including artifacts like this which are intended only to be consumed by ai defeats the entire point.
  • tomashubelbauer 1y ago
    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.
  • mustaphah 1y ago
    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.
  • fallpeak 1y ago
    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.
    • thrown-0825 1y ago
      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.
• tappio 1y ago
  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/ 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.
• donperignon 1y ago
  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.
• iammrpayments 1y ago
  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.
• pietz 1y ago
  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?
  • meindnoch 1y ago
    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!
    • pietz 1y ago
      Holy sh*t, I accidentally for got the "S" and was directly forwarded to PayPal.
      • meindnoch 1y ago
        Yes, most file managers require a payment when creating a file with a non-open name.
• genesem 1y ago
  Why this even required..
  • cube00 1y ago
    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.
• modernerd 1y ago
  Why not use contributing.md? https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors 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.
• whirlwin 1y ago
  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
  • donperignon 1y ago
    Pretty advance stuff. Vibing is definitely a difficult skill to learn.
• kissgyorgy 1y ago
  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!
• smnscu 1y ago
  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.
• jcutrell 1y ago
  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.
  • kordlessagain 1y ago
    No, you nailed it. The rest is theater.
• CMay 1y ago
  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.
• jerpint 1y ago
  I like the concept and have built my own context management tool for this very purpose! https://github.com/jerpint/context-llemur 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 https://m.youtube.com/watch?v=DgqlUpnC3uw
• varispeed 1y ago
  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?
  • bgwalter 1y ago
    It is only the "AI" companies that force their employees to babysit LLMs, so very few real projects do this in the wild.
• pmarreck 1y ago
  I `ln -s` mine to CLAUDE.md for convenience
• abhisek 1y ago
  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.
• super256 1y ago
  This looks like a normal README.md to me. Why do we need a separate file?
  • __alias 1y ago
    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."
• AbuAssar 1y ago
  I didn't know .md TLD is available!
• qwertox 1y ago
  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 `..`?
  • bavell 1y ago
    Chroot jail?
  • anuramat 1y ago
    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
    • qwertox 1y ago
      Wow! Thank you for bringing bubblewrap to my attention. What an amazing tool! This opens so many doors.
  • thrown-0825 1y ago
    run it in a vm, running an agent directly on your machine is madness
• CompoundEyes 1y ago
  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.
• i4k 1y ago
  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.
• anuramat 1y ago
  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
• witx 1y ago
  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.
  • zulban 1y ago
    > 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?
    • witx 1y ago
      You're putting a whole lot of words in my mouth, I didn't say
• stillsut 1y ago
  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 https://github.com/sutt/agro/blob/master/README.md#layout [1]: https://github.com/sutt/vidstr/tree/master/.public-agdocs/guides https://github.com/sutt/vidstr/tree/master/.public-agdocs/gu...
• adidoit 1y ago
  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.
  • jcmontx 1y ago
    "Computing is just 1s, 0s and logic gates"
• level09 1y ago
  wrote this protocol like a month ago :) https://github.com/level09/air https://github.com/level09/air
• mmaunder 1y ago
  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.
  • __alias 1y ago
    it does though, the same way that an llm can trace imports / dependencies through any coding language. ``` If adding tests, read @./TESTING_INSTRUCTIONS.md ```
• lenerdenator 1y ago
  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?
  • steveklabnik 1y ago
    Yes.
• perrygeo 1y ago
  Shouldn't you already have these instructions written out? Seems like AI has just motivated developers to finally write documentation.
• phplovesong 1y ago
  This makes me hate AI even more
• laweijfmvo 1y ago
  > build steps, tests, and conventions that might clutter a README or aren’t relevant to human contributors. what in fresh hell is the world coming to
  • kordlessagain 1y ago
    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.
  • astrobe_ 1y ago
    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.
  • witx 1y ago
    Devs are just being trolled into documenting their code. But because it's AI they are hyping it
• dizlexic 1y ago
  oh good, another one.
• sbochins 1y ago
  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.
• eric-p7 1y ago
  We can't call it robots.txt?
• yoz-y 1y ago
  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.
• kotauchisunsun 1y ago
  [dead]
• smsm42 1y ago
  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.
• proflead 1y ago
  Looks very promising. If you need to know a bit more about it, watch this video https://youtu.be/TC7dK0gwgg0?si=Eb5TK0gPvgahVbWQ https://youtu.be/TC7dK0gwgg0?si=Eb5TK0gPvgahVbWQ