You’ve probably noticed your AI agent keeps doing the same dumb things. You rewrite the prompt. It still messes up. You add more instructions. It gets confused. Sound familiar?
That sinking feeling when you realize your carefully crafted Claude.md file is just a pile of contradictory, ambiguous English—and your agent is acting like a schizophrenic intern. You’re not alone. Everyone is doing it wrong.
Here’s the uncomfortable truth: Natural English is a terrible programming language for deterministic AI behavior. You wouldn’t write code in prose. So why are you writing your agent’s brain in it?
I read Zander’s breakdown of the Claude.md chaos, and the top comment nails it: “The guidance contradicts itself and almost none of it is dated.” That’s the problem. We treat these files as static documentation, not executable context. We write beautiful, human-readable paragraphs that an AI will misinterpret in six different ways.
Stop. Just stop.
Here’s the fix nobody’s talking about: Your Claude.md should be a constrained language, not a love letter. Version it. Date it. Treat it like code. Write a small, opinionated vocabulary of commands your agent can understand—no ambiguity, no vague adjectives, no “be helpful” nonsense.
I saw this firsthand in a project last month. We had a Claude.md that was 800 words of beautiful prose. The agent ignored half of it. We rewrote it as a 150-word spec with strict rules, versioned, dated, and using a custom shorthand. The agent’s behavior flipped from erratic to predictable overnight.
Your AI agent is only as good as the spec you give it. And if that spec is written in the same language you use to order coffee, you’re asking for trouble.
The twist? Most people think more words = more clarity. The opposite is true. More words create more contradictions. The best Claude.md files are short, brutal, and machine-optimized. They’re not written for humans to read—they’re written for the agent to execute.
So here’s your challenge: Go look at your Claude.md right now. If it’s longer than 200 words, you’ve already lost. If it’s not dated, you have no idea what version the agent is running. If it uses natural English paragraphs, you’re burning iteration cycles.
Version it. Date it. Constrain it. Or keep watching your AI agent do the same dumb things, day after day. Your choice.
FAQ
Q: What question would a skeptic ask?
A: Isn't natural language the whole point of using an AI agent? Why would I want to restrict it to a constrained language?
Q: What's the practical implication?
A: You'll waste fewer iterations, get consistent behavior, and actually trust your AI agent to automate tasks without constant supervision. The trade-off is a steeper initial learning curve for writing the spec.
Q: What's the contrarian take?
A: The real contrarian view is that most Claude.md files are over-engineered. A simple, well-structured prompt in plain English works fine for simple tasks. The constrained language approach only matters when you need deterministic, multi-step workflows.