Clay Tercek

AGENTS.md Is Not a README

Date

Open source projects are getting plagued by agent files. AGENTS.md, CLAUDE.md, .cursor/rules, .github/copilot-instructions.md, committed skills, the works. The convention, pushed hard by the people who make these tools, is to commit them. The agents.md spec frames the file as “a README for agents,” project infrastructure that belongs in source control next to your CI config. GitHub has written up lessons from 2,500+ repos treating it as shared documentation.

I think this is mostly a mistake.

These files are inherently personal. The way I drive an agent is not the way you drive an agent, and committing my workflow into a shared repo quietly assumes the whole team should converge on one. I don’t think that’s true, and I don’t think it’s desirable. Your agent workflow can and should be bespoke. It’s closer to your editor config or your shell aliases than to your test suite. Nobody commits their .vimrc to the project repo and expects everyone to adopt it.

The usual argument for committing the file is that it documents the architecture, the repo layout, the build and release process, the conventions a new collaborator needs. All of that should be shared. But none of it is agent information. It’s documentation, and documentation belongs in the README, where humans will actually read it. Putting it in AGENTS.md just hides your project docs somewhere only the robots look. As spawarotti put it on Hacker News:

“At this point AGENTS.md is a README.md with enough hype behind it to actually motivate people to populate it with contents. People were too lazy to write docs for other people, but funnily enough are ok with doing it for robots.”

The shareable content was never agent content. It’s the docs we should have been writing for each other all along.

This instinct isn’t fringe, but it’s a minority position. You can watch the debate play out in real time: a Hacker News commenter says flatly, “I would .gitignore all of those files. Is this not what is done in industry?” and gets mostly disagreement. The split is always the same: shared rules enforce consistency, but they also flatten everyone into one person’s setup.

So why does everyone commit them anyway?

Because the alternative is genuinely worse right now.

The reason to colocate agent instructions with the code is that git gives you branch-awareness for free. Say you’re on a feature branch and you tweak AGENTS.md to describe a module that only exists on that branch. Then you switch back to main. Because the file is tracked, your changes travel with the branch, so main’s agent never sees references to code that doesn’t exist yet. Anyone who has tried git-ignoring their agent files knows the opposite feeling: a single global instruction file that’s perpetually slightly wrong for whatever branch you’re actually on.

So you’re stuck between two bad options. Commit the file and impose your workflow on the team, or ignore it and lose the branch-awareness that made it useful.

What we have today

The tools do offer escape hatches, they’re just incomplete.

Claude Code, for instance, has a real hierarchy (documented here): a user-level ~/.claude/CLAUDE.md that applies across all projects and never gets committed, a team-shared project ./CLAUDE.md, and a personal ./CLAUDE.local.md that you’re meant to add to .gitignore. AGENTS.md has an open proposal to standardize a global ~/.config/agents/AGENTS.md, explicitly modeled on how git handles ~/.gitconfig versus a repo’s .git/config.

That git analogy is the right one. Git solved exactly this problem decades ago: global defaults in ~/.gitconfig, repo overrides in .git/config, and personal per-repo ignores in .git/info/exclude that never touch the shared .gitignore. The local layer is never committed. We just haven’t fully ported that model to agent memory.

The gap is branch-awareness. CLAUDE.local.md is per-worktree, not per-branch. None of the personal-config options track your branches the way a committed file does.

That gap is what pushed me to build offstage, a small Go CLI that keeps personal files colocated with a project without committing them to the project’s repo. It’s backed by a separate private git repo, and it’s branch-aware: files are stored under <project-id>/<git-branch>, so each branch gets its own notes, synced across machines via git hooks. It’s been working for me, but I’m floating it as one option, not a recommendation, and your mileage may vary. It’s a partial fix at best: if a branch gets merged via a PR, offstage has no way to know, so you have to manually run offstage merge to reconcile. The branch lifecycle and the file lifecycle drift apart the moment the merge happens somewhere offstage can’t see.

A better solution

The real fix is more foundational than a sync tool. A few directions I think are worth exploring:

None of these fully exist yet. For now I commit a deliberately minimal AGENTS.md and keep everything bespoke in offstage. But I think the long-term answer is for agents to treat memory the way git treats config: layered, with the personal layer kept firmly off the shared record.

References