CLAUDE.md works fine for static instructions -- "use this formatter, prefer this style." But the moment agents need to track state across sessions -- what tasks are pending, what decisions were made, what data they collected -- youre stuffing structured data into an unstructured format. I kept finding myself with 500-line CLAUDE.md files that were half prose instructions and half JSON blobs the agent was supposed to parse.

I switched to ctlsurf for this. It gives agents structured blocks they read and write through MCP -- typed datastores, key-value state, append-only logs, checklists -- so the project owns the memory, not the agent session. The agent queries only what it needs instead of loading an entire markdown file into context.

The AGENTS.md vs CLAUDE.md debate in this thread is interesting but its optimizing the wrong layer. The real problem isnt what you name the file, its that flat text is a lossy format for the kind of state agents actually need to persist.