Claude Code can load AGENTS.md. That solves file discovery, not instruction quality.
A weak file sounds like advice: "Be careful with auth." "Test thoroughly." "Follow best practices." Those lines do not pin a repository-specific command, so the agent fills the gaps with guessed commands and generic conventions.
A useful AGENTS.md is an operating brief. It names the real build and test commands, the conventions that differ from defaults, the actions that are off limits, and the checks required before a PR. Keep it short enough to stay visible and specific enough to verify in a diff.
Treat it like teammate onboarding, not a novel the model skims past.
Friend link (no paywall):
https://medium.com/@glennlenormand/how-to-write-an-agents-md-claude-code-will-actually-follow-098a62919b92?sk=43f65fa10278b2258ab70c83d6a0665b
Top comments (0)