As a human dev, can I humbly ask you to separate out your LLM "readme" from your human README.md? If I see a README.md in a directory I assume that means the directory is a separate module that can be split out into a separate repo or indeed storage elsewhere. If you're putting copy in your codebase that's instructions for a bot, that isn't a README.md. By all means come up with a new convention e.g. BOTS.md for this. As a human dev I know I can safely ignore such a file unless I am working with a bot.

▲

kergonath 3 days ago | parent | next [-]

I think things are moving towards using AGENTS.md files: https://agents.md/ . I’d like something like this to become the consensus for most commonly used tools at some point.

There was a discussion here 3 days ago: https://news.ycombinator.com/item?id=44957443 .

▲

Terr_ 2 days ago | parent | prev | next [-]

> If I see a README.md in a directory I assume that means the directory is a separate module that can be split out into a separate repo or indeed storage elsewhere.

While I can understand why someone might develop that first-impression, it's never been safe to assume, especially as one starts working with larger projects or at larger organizations. It's not that unusual for essential sections of the same big project to have their own make-files, specialized utility scripts, tweaks to auto-formatter, etc.

In other cases things are together in a repo for reasons of coordination: Consider frontend/backend code which runs with different languages on different computers, with separate READMEs etc. They may share very little in terms of their build instructions, but you want corresponding changes on each end of their API to remain in lockstep.

Another example: One of my employer's projects has special GNU gettext files for translation and internationalization. These exist in a subdirectory with its own documentation and support scripts, but it absolutely needs to stay within the application that is using it for string-conversions.

▲

alex-moon a day ago | parent [-]

You're absolutely right - I explained my reasoning poorly. Let me try again: a README.md marks a conceptual project root. It's a way of flagging to developers: "The code in this directory builds, deploys and/or runs separately to other code in this repo." It's a marker that says you need to think of this directory as something that could meaningfully be split out into a separate repo or storage, but isn't because it only makes sense in the context of this repo. It's common in public repos with docs and examples dirs in the project root. The docs are built separately. The examples are meant to be standalone and could be implemented that way even if they actually import code from the parent repo instead of requiring it as a third party dependency.

	▲	Terr_ a day ago \| parent [-]
		> [A README.md is] a way of flagging to developers: "The code in this directory builds, deploys and/or runs separately to other code in this repo." I disagree, that's merely correlated to the real purpose: A file-level README is something an author adds when they anticipates something about the mental-state of future readers. In particular, that a reader won't arrive already-prepared to understand or navigate. While that often happens at "project roots", it is by no means exclusive to them, and it can still happen in sections with extremely tight dependencies or coupling that could never exist independently. Analogy: While many roads begin with a speed-limit sign, it is not true that every speed-limit sign indicates you've entered a new road.

▲

mattmanser 3 days ago | parent | prev [-]

While I agree keep Readme a for humans, Readme literally means read me.

Not 'this is a separate project'. Not 'project documentation file'.

You can have read mes dotted all over a project if that's necessary.

It's simply a file that a previous developer is asking you to read before you start making around in that directory.