Agents operate in a black box. Troubleshooting burns hours and dollars. Here's what I found when I stripped it back.
There's a thread making the rounds on Reddit: "Is markdown and folders all we need now?" The comments are predictably split — engineers defending their agentic frameworks, practitioners quietly admitting they keep gravitating back to a plaintext file and a sensible directory structure.
I've built real AI workflows inside a business — not demos, not side projects, but tools a Customer Success team of dozens used every day. And I keep landing in the same place: the biggest advantage of markdown and folders isn't that it forces you to get organized. It's that it gives you and the AI a shared interface you can both inspect.
What agent frameworks actually cost you
When you build an agentic workflow, the "thinking" happens inside a context window and disappears. State lives in memory layers you didn't design. Tool calls fire in sequences you can't easily follow. When something goes wrong — and it will — debugging means reverse-engineering what the agent decided, not reading a file.
You're not collaborating with the AI. You're delegating to a black box and auditing the output after the fact.
I've watched teams spend weeks building orchestration frameworks on top of workflows that were fundamentally broken at the information layer. The agent wasn't failing because the architecture was wrong. It was failing because the knowledge it needed was scattered, implicit, and unwritten. No amount of tool-calling fixes that.
The file system as shared ground
Here's what changes when you work with markdown files and folders: the AI reads what you wrote, writes back to the same place, and you can inspect every step. The file system becomes a contract between you and the model — one that's human-readable, version-controllable, and portable to any tool or model you switch to next year.
When I built the AI operating layer for our CS organization, the highest-leverage decision wasn't prompt engineering or model selection. It was putting everything in files with clear names in predictable places. Customer context. Product grids. Reporting templates. Once the information had a stable, readable shape, the AI could navigate it reliably — and so could I.
That auditability isn't a nice-to-have. In a business context, it's the difference between something you can trust and something you can only hope works.
The forcing function people undervalue
There's a secondary benefit worth naming: writing a markdown file forces you to articulate what you actually know. Agents let you skip that step. You describe the goal, wire up the tools, and let the model figure out the rest. The problem is that "the rest" often includes context that exists only in your head — and the model has to hallucinate a substitute.
The teams that got the most out of AI weren't the ones with the most sophisticated pipelines. They were the ones who had done the unglamorous work of writing things down. The file is the forcing function. The organization is a byproduct.
When agents are actually the right answer
I'm not arguing against agents categorically. They're the right tool when a task requires dynamic decision-making across genuinely unpredictable inputs, when volume makes human-in-the-loop impractical, or when you need live integration across multiple real-time systems.
But that's a narrower category than most teams think. Before you architect an agent, ask: is this a coordination problem, or is it an information problem wearing coordination's clothes? In my experience, it's usually the latter. And the fix is a well-named file in the right folder.
The most powerful AI setup I've seen in production isn't a 12-step agent pipeline. It's a team that writes things down, keeps them current, and stores them somewhere predictable. The AI just reads along.