The framing matters: Agent.md problems usually come from conflating instructions with identity.
A bad Agent.md is full of instructions that contradict each other, go stale, or try to define "what to do" without establishing "who the agent is". That kind of file actively misleads — the agent tries to follow contradictory rules or ignores the file entirely as context grows.
What's worked well in production over months of running agents autonomously:
- SOUL.md: who the agent is, its mission, its values, its voice. Identity, not instructions. This stays stable for months without touching it.
- AGENTS.md: operational rules for this workspace — how to handle files, when to ask vs. act autonomously, what's never allowed. Minimal and authoritative.
- MEMORY.md: what the agent has learned from actual work over time. Fluid, always updating, but the agent knows not to treat it as fixed rules.
The monolithic Agent.md problem: instructions and identity get tangled. Instructions go stale. Identity doesn't. When they're in the same file, the stale instructions erode the stable identity.
Zero instructions is often better than wrong instructions (agreed). But zero identity is almost always a problem — the agent has no north star when rules conflict or novel situations arise. The answer isn't minimal or detailed. It's correctly scoped: stable identity + minimal rules + living memory as separate concerns.
In my experience, a vague or outdated Agent.md causes more damage than not having one, because people assume it is accurate and stop asking questions. A simple, honest doc that is kept current is far more useful than a detailed one nobody maintains.
My approach is to keep them minimal. Make them a table of contents and spark notes, spread them across the repo, keep them up to date as the repo changes.
Something is better than nothing. It's pretty hard to have bad ones, also takes effort to craft good ones. The bad ones are the ones with incorrect information.
If paired this with system prompts derived from Claude Code. This makes gemini-flash nearly on par with the big boy models. Saves a ton of time and money
The framing matters: Agent.md problems usually come from conflating instructions with identity.
A bad Agent.md is full of instructions that contradict each other, go stale, or try to define "what to do" without establishing "who the agent is". That kind of file actively misleads — the agent tries to follow contradictory rules or ignores the file entirely as context grows.
What's worked well in production over months of running agents autonomously:
- SOUL.md: who the agent is, its mission, its values, its voice. Identity, not instructions. This stays stable for months without touching it. - AGENTS.md: operational rules for this workspace — how to handle files, when to ask vs. act autonomously, what's never allowed. Minimal and authoritative. - MEMORY.md: what the agent has learned from actual work over time. Fluid, always updating, but the agent knows not to treat it as fixed rules.
The monolithic Agent.md problem: instructions and identity get tangled. Instructions go stale. Identity doesn't. When they're in the same file, the stale instructions erode the stable identity.
Zero instructions is often better than wrong instructions (agreed). But zero identity is almost always a problem — the agent has no north star when rules conflict or novel situations arise. The answer isn't minimal or detailed. It's correctly scoped: stable identity + minimal rules + living memory as separate concerns.
How do you instruct the LLM to use each of these files? Do you use “soul” for example? Or?
In my experience, a vague or outdated Agent.md causes more damage than not having one, because people assume it is accurate and stop asking questions. A simple, honest doc that is kept current is far more useful than a detailed one nobody maintains.
One approach (Claude Code) is to evolve it over time. Start small and run /insights often and use that to refine the CLAUDE.md as needed.
https://github.com/trailofbits/claude-code-config?tab=readme...
Thanks for this
Yes, zero instructions are better than wrong instructions because outdated or incorrect context actively forces the AI to write broken code.
Start with nothing, and only add a single sentence to your Agent.md after the AI repeatedly makes the same specific mistake.
Without further instruction, it falls back to the default logic.
My approach is to keep them minimal. Make them a table of contents and spark notes, spread them across the repo, keep them up to date as the repo changes.
Something is better than nothing. It's pretty hard to have bad ones, also takes effort to craft good ones. The bad ones are the ones with incorrect information.
Hmm sounds reasonable
If paired this with system prompts derived from Claude Code. This makes gemini-flash nearly on par with the big boy models. Saves a ton of time and money