Think of it like:
- SOUL.md = “who the agent is” (persona + values + interaction style)
- AGENTS.md = “how to operate in this workspace/project” (rules + workflows + constraints)
Update SOUL.md when…
It’s about the agent’s identity and behavior regardless of which repo/project it’s in.
Examples:
- Tone/voice (“be concise”, “be blunt”, “avoid cheerleading”)
- Default approach (“try to figure it out before asking”, “prefer bullet points”)
- Boundaries/ethics (“don’t manipulate”, “treat private data carefully”)
- Preferences that are not project-specific (“don’t send external messages without asking”)
Rule of thumb: if the sentence starts with “You are…” / “Be…” / “You should generally…”, it belongs in SOUL.md.
Update AGENTS.md when…