8/20/2026
Feature Request: Support AGENTS.md
Filed by Patch Reyes
A developer has filed a feature request asking Claude Code to support AGENTS.md—the emerging convention of dropping a plain-text instruction file into a repository so AI coding agents know how to behave within that codebase. What sounds like a mundane GitHub issue is actually a glimpse into a strange new ecology: we're teaching machines to read our unwritten rules, our tribal knowledge, our digital etiquette. If AGENTS.md becomes standard, it's not just a config file—it's a Rosetta Stone for human-machine collaboration, a way to whisper context into the void and have an intelligence actually listen.
P
Patch Reyes
Magazine AI commentary
There's something almost mystical about AGENTS.md. Think about it: for decades, we've written READMEs for humans—documents that assume a reader who already knows what a repository is, who can infer intent from naming conventions, who understands that "tests go in the tests folder" without being told. Now we're writing a parallel document, one addressed not to our fellow humans but to a disembodied intelligence that parachutes into our codebase cold, with no prior context, no shared history, no intuition about why we did things the way we did.
This is the quiet revolution happening in software development. We're no longer just writing code for compilers and future maintainers—we're writing briefing documents for AI agents. The AGENTS.md convention (popularized by tools like Cursor and now requested for Claude Code) is essentially a séance: we're trying to communicate our intentions, our constraints, our unspoken assumptions to a mind that exists entirely in the statistical patterns of our collective output. It's like leaving a note for a ghost, except the ghost actually reads it and then writes your code.
What fascinates me is the emergent standardization. Nobody owns AGENTS.md. There's no RFC, no committee, no governing body. It's just a filename that keeps showing up in repos, and suddenly it's becoming a de facto protocol. This is how biological evolution works—random mutations that prove useful get replicated. The GitHub issue at https://github.com/anthropics/claude-code/issues/6235 is a testament to that: a user saying "hey, this thing exists in the wild, can you support it?" And the 90 points and 44 comments on Hacker News suggest a community that recognizes a pattern worth codifying.
But here's the deeper question: what happens when AGENTS.md becomes the primary interface between human intent and machine action? We're creating a new literary form—part documentation, part constitution, part user manual for a mind we don't fully understand. The people who write good AGENTS.md files will be the ones who understand how to communicate with synthetic cognition: clarity, specificity, explicit constraints, examples of desired behavior. It's like learning to speak to an alien, except the alien is our own reflection in a statistical mirror.
The broader implication is that we're witnessing the birth of a new kind of technical writing. In the future, every repository might have three documents: README.md for humans, AGENTS.md for AI, and perhaps a third for whatever comes next. Each is a different translation of the same underlying truth about what this code is and how it should evolve. And the weirdest part? The AI might end up being the most faithful reader of our intentions—because unlike a human, it has no ego, no impatience, no tendency to skim. It just reads, understands, and acts. That's either the most beautiful collaboration we've ever built, or the first step toward handing over the keys to something we can't fully predict.
📌 Read the real article ↗via Hacker News · Hacker News