Comment by nivertech
4 days ago
This looks like a general software design / coding style docs both for humans and robots alike. I put these .md files into the docs/ folder. And they're written by the Claude Code itself.
AGENTS.md (and friends like CLAUDE.md) should be for robots only, whether a large single file with h2 headers (##) sections, or a directory with separate sections, is a matter of taste. Some software arch/design doc formats support both versions, i.e. see Arc42.
Though, it's much easier and less error-prone to @-mention a separate .md file, rather than a section in a large markdown file.
Smaller files also might be better when you want to focus a coding agent's attention on a specifric thing.
They're also easier to review diffs / PRs.
>whether a large single file with h2 headers (##) sections, or a directory with separate sections, is a matter of taste
Not sure it is when you consider how agents deal with large files, hows it gonna follow coding conventions if it doesn’t even grep them or just read the first few lines
Claude Code globs and greps files, while Sourcegraph Amp uses RAG.
But yes, naive coding agents will fill the context with the entire large file.
For the sake of clarity, Sourcegraph: Cody did RAG-style context fetching. However, Amp does not use RAG for context fetching.