Stop /init your AGENTS.md and CLAUDE.md

Naive me asked the Cursor team to add this into Cursor, luckily they didn't

I used to ask Cursor team to add a /init AGENTS[.]md because Claude Code has it, but luckily they didn’t because it can cause more harm than good, and you shouldn’t too even if your agent IDE/harness provides it (or at least until you understand it more, not like silly old me)

First let’s understand what AGENTS.md is and why it exists. AGENTS[.]md is created as a standard for all agents (think Cursor, Codex, Gemini etc) to have understanding about the repository or folder, can think of it like a README file for agents.

And it’s actually sits in the same layer as the rules files (which explicitly mandate the agent what can or cannot be done), meaning the AGENTS[.]md is sent with every single prompt.

Long AGENTS[.]md = More token consumption = Less context window for agents to do the real work

How I would like to think AGENTS[.]md is a file to give agents context that they couldn’t figure out organically.

If they are able to figure out the repo structure, build steps, conventions then having it in AGENTS[.]md is not helpful, and it’s just taking up the context window for them to work on the real task. Using human engineer as an analogy, when work on UI work, I shouldn’t need to remember the full CI/CD now, until I need it later when I push my work.

What I think is more correct in approaching this,

1. Observe how the agents behave, discuss with your teammates, whether it’s a documentation issue or context management issue, before putting it in AGENTS[.]md

2. Aim to write good documentation to onboard both human and agents, make it discoverable, use frontmatter for summary to reduce tokens spent for agents

3. Treat AGENTS[.]md as a directory, where it links to the relevant documentation for conventions, CICD, architecture etc, agents read them when they think they need it

4. Outdated AGENTS[.]md is worse than having no AGENTS[.]md at all, several researches have shown this, so better to keep what’s important inside, and maintain/update it over time

5. If agents couldn’t find the context and need to rely on AGENTS[.]md, then human engineers (or new engineers on the team) likely couldn’t find it too

6. Do A/B test, challenge every line in the file if they need to exist there, each line = more tokens = less context window for real work

Here are some articles that I read that helped me learn more about AGENTS[.]md and shaped my approach to it.

1. https://addyosmani.com/blog/agents-md/

2. https://www.aihero.dev/a-complete-guide-to-agents-md

What’s your approaches to AGENTS[.]md? I’m curious to learn from different perspective as well, or if you think the AI generated AGENTS[.]md is actually better, would love to hear more