Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

AGENTS.md – Open format for guiding coding agents

agents.md

Post reply on HN
Print view View original

171–180 of 398 posts

Re: AGENTS.md – Open format for guiding coding agents

#171

Post by superfish »

skhameneh wrote: post #138
CGamesPlay wrote: post #133

Earlier quoted context omitted.

> 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…

Negative assertions can lead to unwanted weights in the context. I've found positive assertions to be more predictable.

Do you mind sharing a specific concrete example? I'm curious.

Re: AGENTS.md – Open format for guiding coding agents

#172

Post by bryanrasmussen »

awbraunstein wrote: post #168
CharlesW wrote: post #36

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 ├── da…

You can have multiple AGENTS.md files in your codebase and tooling will look at both the one in the current directory as well as in the root of the codebase. This way you can sort of do what you're suggesting but simultaneously keep the information closer to the code that it is describing.

so you would have an Agents.md in your testing folder and it would describe how to run the tests or generate new tests for the project - am I understanding the usage correctly?

Re: AGENTS.md – Open format for guiding coding agents

#173

Post by pmg101 »

ecb_penguin wrote: post #74
legostormtroopr wrote: post #57

So the solution to using AI so you don't have to code, is to try to write some kind of pseudocode in AGENT.md and hope the AI does a bit better? Why does it seem that the solution to no-code (which AI-coding agents are) always comes back to "no-code, but actually there is some code behind the scenes, but if you squint enough it looks like no-code".

> So the solution to using AI so you don't have to code, is to try to write some kind of pseudocode in AGENT.md and hope the AI does a bit better? Umm, no. Where did you get that idea? The purpose of the agent.md file is to give it instructions. Nothing about no-code AI said there would be no instructions...

I'm old enough to remember when computer code was called "instructions".

Eg, the 6502 instruction set. https://www.masswerk.at/6502/6502_instruction_set.html

History doesn't repeat but it rhymes!

Re: AGENTS.md – Open format for guiding coding agents

#175

Post by grim_io »

deadbabe wrote: post #166
nephanth wrote: post #157

Earlier quoted context omitted.

It is files that are meant to be read by software, not humans. From my point of view this seems like a prime candidate for a hidden directory?

If it isn’t being read by humans, then it shouldn’t be written by them either.

Yeah. Claude writes my CLAUDE.md

I don't really care what's inside.

Re: AGENTS.md – Open format for guiding coding agents

#177

Post by seb1204 »

alphazard wrote: post #11

Isn't the promise of AI that we don't have to adhere to precise formats? We can just write it down in whatever format makes the most sense to us, and any impedance mismatch is on the machine to figure out?

Still need to write it down to make it explicit. The longer the writing gets the more a structured approach is suitable for the human writing and maintaining the instructions.

Re: AGENTS.md – Open format for guiding coding agents

#178

Post by steveklabnik »

CharlesW wrote: post #118
jitix wrote: post #81

Earlier quoted context omitted.

I like this idea. Do you have any middleware in your current setup that added the contents of this directory to the agent prompt?

I'd be interested in smarter ways of doing this, but currently I just use my CLAUDE.local.md to serve as the index.md in my example. It includes the 'specialist' .md files with their relative paths and descriptions, and tells Claude Code to use these when planning. I also have explicit `xnew`, `xplan`, `xcode` and `xcheck` commands in CLAUDE.md that reinforce this. For example, here's my `xnew`: ## Remember Shortcuts…

Claude supports slash commands, this might be better for you: https://docs.anthropic.com/en/docs/claude-code/slash-command...

As well as custom agents: https://docs.anthropic.com/en/docs/claude-code/sub-agents

Re: AGENTS.md – Open format for guiding coding agents

#180

Post by porker »

bhaney wrote: post #176

These AI-oriented examples look more useful to me than most human-oriented READMEs I've seen.

Yes, writing clear examples and instructions for humans was never seen as a good use of time, but as soon as a dumb mutt of an AI needs them to do stuff, they're written, and with more compassion than was ever shown to newbies asking questions...

We've lost a bunch of contributions to open source projects because these guides weren't there to help new people contribute.

Post reply on HN