Is a README for Humans or for LLMs?
I read the README of one of my own repositories and stopped at the tenth sentence. I had written it with my README skill, and the pre-publication check had said it was fine to publish. It opened with a two-sentence paragraph meant to say what the project does (translated from the Japanese README): An autonomous agent that runs on a local LLM and proposes changes to its own constitution and…
The article explores the challenges of writing README files that cater to both human readers and language models (LLMs). The author found that verbose prose generated by LLMs often includes information that doesn't need to be explicitly stated, as humans tend to stop reading after a few lines if uninterested. However, LLMs continue reading until the end, potentially processing irrelevant details.
To address this, the author experimented with splitting the README into two sections: one for humans and another for LLMs. The human-readable section contains concise, essential information, while the LLM-readable section includes additional facts. The author created a public repository, readme-fetch-canary, to test if AI assistants would read the hidden section.
The results showed that most assistants did read the folded contents, indicating that the separation worked. However, the author also noted that the initial assumption of writing READMEs primarily for LLMs led to a focus on including enough facts for LLMs, even at the expense of readability for humans. The article suggests using an llms.txt file as a separate summary for LLMs, although it is rarely fetched by crawlers.
The author concludes that separating the human-facing and LLM-readable sections of a README could improve clarity and readability for both audiences.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
