I think I'd be happier with a standard .agents directory and have all of these in there. I imagine each agent is going to need its own tweaks to get it to work just right with their system prompts, just as Claude already has it's project-specfic .claude directory for hooks and commands and whatnot.
I'd rather .agents/claude or something so we can get these files out of the root directory, which, at least for typescript projects, is already a confetti-like jumble of json files for every little "simple" tool that needs its own configuration file.
I get why package.json isn't enough. But would a .config directory standard really have hurt us so much?
Ideally (and in practice, so far) they shouldn't change that much. The agent instructions should be close to a human explanation, and they are pretty good at parsing instructions anyway. In my experience you can symlink the same file to all paths and they work as expected.
If I'm writing for a human contributor, I'm gonna have a pretty high bar for the quality of that writing.
An agent on the other hand, one who is in that sweet spot where they're no longer ignorant, and not yet confused... It's nice to have them dump their understanding to agent_primers/subsystem_foo.md for consumption by the next agent that touches that subsystem. I don't usually even read these until I suspect a problem in one. They're just nuggets of context transfer.
Yes! I want an option to always add README.md to the context; It would force me to have a useful, up to date document about how to build, run, and edit my projects.
Ultimately if this stuff is actually intelligent it should be using the same sources of information that we intelligent beings use. Feels silly to have to have to jump through all these hoops to make it work today
They’re definitely not, Claude and all other agents frequently forget the build and test commands present in CLAUDE/etc.md for my various repos (even though most of them were were initialized by the AI).
I had the other direction in mind: you can put together some text that the average LLM will figure out, but that will be really annoying for your average developer.
Eg if you write your instructions in a mixture of base 64, traditional Chinese, morse code and Polish, the LLM will still figure it out.
That sounds nice and I have the same pain, but not sure AGENT.md is the right abstraction either. After all, these models are indeed different and will respond differently even given the same prompting. Not to mention that different wrappers around those models have different capabilities.
e.g. maybe for CURSOR.md you just want to provide context and best practices without any tool-calling context (because you've found it doesn't do a great job of tool-calling), while for CLAUDE.md (for use with Claude Code) you might want to specify tools that are available to it (because it does a great job with tool calling).
Probably best if you have an AGENT.md that applies to all, and then the tools can also ingest their particular flavor in addition, which (if anything is in conflict) would trump the baseline AGENT file.
I asked claude code for a guidelines file so it would collaborate with windsurf. This is what it proposed:
---
This project uses shared planning documents for collaboration with Claude Code. Please:
1. First read and understand these files:
- PLAN.md - current project roadmap and objectives
- ARCHITECTURE.md - technical decisions and system design
- TODO.md - current tasks and their status
- DECISIONS.md - decision history with rationale
- COLLABORATION.md - handoff notes from other tools
2. Before making any significant changes, check these documents for:
- Existing architectural decisions
- Current sprint priorities
- Tasks already in progress
- Previous context from Claude Code
3. After completing work, update the relevant planning documents with:
- Task completion status
- New decisions made
- Any changes to architecture or approach
- Notes for future collaboration
Always treat these files as the single source of truth for project state.
problem is that claude doesn't actually read those or keep them in context unless you prompt it to. it has to be in CLAUDE.md or it'll quickly forget about the contents
CLAUDE.md is placed in front of the first input for your session, right after the system prompt. That’s all. It’s not given any more weight than the rest of the context, and idk what compacting the conversation does to it.
I really like the idea of standardizing on AGENT.md, although it's too bad it doesn't really work with the .cursor/rules/ approach of having several rules files that get included based on matching the descriptions or file globs in frontmatter. Then again, I'm not sure if any other agents support an approach like that, and in my experience Cursor isn't entirely predictable about which rules files it ends up including in the context.
I guess having links to supplementary rules files is an option, but I'm not sure which agents (if any) would work well with that.
Yep, that's a peeve of mine. I've resorted to using AGENT.md, and aliasing Claude, Gemini, etc to a command that calls them with an initial instruction to read that file. But of course they will forget after some time.
The whole agentic coding via CLI experience could be much improved by:
- Making it easy to see what command I last issued, without having to scroll up through reams of output hunting for context
- Making it easy to spin up a proper sandbox to run sessions unattended
- Etc.
Maybe for code generation, what we actually need is a code generator that is itself deterministic but uses AI, instead of AI that does code generation.
I've experimented a little with LLM agents (only Claude Code). I definitely don't want the agent to write the commit messages (they should be written by a human as they're for human consumption) so I manually added the co-author trailer. It's morally correct to provide attribution.
Never. It's a marketing strategy. Some percentage of users will check these files into their repos, and some percentage of repo browsers will think "what is this X.md?" Given how much money people are spending on these things the value of having a unique filename must be enormous.
It’s a marketing strategy that works here and now, but “never” is a very long time. What could be seen as pioneers claiming names today could be also seen as retrogressive stubbornness tomorrow and lose its marketing value.
I just wish the AGENTS.md standard wasn't a single file. I have a lot of smaller context documents that aren't applicable to every task, so I like to throw them into a folder (.ai/ or .agents/) and then selectively cat them together or tell the agent to read them.
You could have a python script that generates the MD file on the fly, based on how you want to prompt the model. I think it's kind of funny, how deep we are getting with tools instructing tools instructing tools.
FWIW at least with Claude and Jules on a project I have a decent setup where I put all of the real content in an agents.md and then use “@agents.md” in CLAUDE.md. If all of the tools supported these kinds of context references in markdown it wouldn’t be that hard to have a single source of truth for memory files.
Yeah I suspect some of these providers will become Microsoft in the '90s type bully holdouts on implementing the emerging conventions. But ultimately with CLI interface you have workarounds to all the major providers read in your system guidelines. But in an IDE - e.g. like MS had with VisualStudio - you more lock-in potential for your config files.
I'm at a point where I symlink differnet sets of docs to try to focus context so much I feel like maybe I need a git submodule with different branches of context I want. I left managing people to now manage AI
The deeper problem are the custom commands, hooks and subagents. The time has come that you need to make a strategic choice. Once you have heavily invested into CC, it is not easy to turn to an alternative.
Side remark:
CC is very expensive when using API billing (compared to e.g. GPT-5). Once a company adopts CC and all developers start to adapt to it at full scale, the bill will go out of the roof.
For example: i'm using Claude Code mostly + Gemini CLI. Gemini CLI is not such powerful as CC, also it won't work with some mcp's. So i have different *.md files.
https://agent.md [redirect -> https://ampcode.com/AGENT.md] https://agent-rules.org