The Vibe Coding Trick: Using Diátaxis to Tame AI-Generated Code

Every developer who used AI to generate code knows the intoxicating rush: you describe a feature in plain English, and the code appears. Andrej Karpathy called this "vibe coding" in early 2025, and it took off. But there's a dark side: vibe-coded codebases are often undocumented, unstructured, and fragile. The code works, but nobody—including the AI—knows why.

I hit that wall after three weeks of vibe-coding a customer analytics dashboard for my consulting firm. The tool worked, but when I tried to hand it over to a colleague, I couldn't explain how it was built. That's when I discovered Diátaxis—a documentation framework by Daniele Procida. And it turned out to be the exact fix for my vibe-coding problem.

What is Diátaxis?

Diátaxis (from Greek "through arrangement") is a systematic approach to technical documentation. Procida presented it in his 2016 paper and it has since become the backbone of many major documentation sites. The core idea is simple: all documentation falls into four distinct types, each serving a different user need.

The genius is that mixing these types leads to confusion. Tutorials should not be reference manuals. How-to guides are not tutorials. Every piece of documentation fits exactly one slot.

The Problem: My Vibe-Coded Mess

In April 2025, I started using an LLM-powered IDE to build a dashboard that pulls data from Stripe and Google Analytics. The dashboard would show client acquisition metrics in real time—a simple tool, but perfect for vibe coding. I wrote prompts, the AI wrote code, and it worked. If you're planning a similar integration, ASI Biont supports connecting to Stripe and Google Analytics via API — more at asibiont.com/courses.

Within days, the codebase became a swamp. I asked the AI to add features, and it returned snippets. I pasted them. Then I asked for a fix, and it generated a patch that clashed with earlier assumptions. The AI had no memory of the architecture because the architecture didn't exist. There was no single document explaining what the project did, how the data flowed, or why I chose certain libraries.

Soon I had a tool that nobody else could use—or even read. My innovation was a tangle of generated code with zero documentation.

The Solution: Diátaxis as a Development Methodology

Instead of just writing docs, I used Diátaxis as a lens for how I interacted with the AI. Every time I asked for a feature, I framed it according to one of the four types.

1. Tutorials – Teach the AI. For recurring tasks, I wrote a "tutorial" for the AI: a minimal example of a microservice, so it could mimic the pattern. For instance, I created a tutorial for adding a new API endpoint, complete with error handling conventions.

2. How-to guides – Ask for recipes. When I needed to fix a bug, I wrote a how-to prompt: "The app crashes when fetching data from Stripe; here's the error message and the relevant code; fix it." This forced me to isolate the context, just like a good how-to guide isolates a task.

3. Reference – Enforce consistency. I created a REFERENCE.md file with the naming conventions, database schema, and environment variables. Every prompt I gave the AI included: "Consult REFERENCE.md before generating code." This reduced hallucinated dependencies dramatically.

4. Explanation – Capture decisions. After each significant feature, I asked the AI to generate an "explanation" of the architecture. I then edited it. This became the mental map for further development.

Results

• Readability: My colleague, who had never touched the project, was able to understand the core flow in an afternoon by reading the explanation document.
• Onboarding time: Down from "never" to a day.
• AI-generated code consistency: Because the AI now had a reference, the generated code followed the same patterns. I measured a noticeable drop in "WTF moments" (though I didn't track it scientifically).
• Maintainability: Instead of patching over patches, I could treat the codebase as a system. A month later, I refactored the entire dashboard with AI assistance in one sitting—because the structure was clear.

Why Diátaxis Works for Vibe Coding

Diátaxis works because it addresses the root problem of AI-generated software: a lack of intention. Vibe coding often means letting the AI make decisions. Diátaxis forces you to decide what you need before the AI writes anything. It transforms the AI from an autonomous generator into a disciplined tool.

Think of it this way: an LLM is the world's most eager junior developer. Without structure, it produces a million lines of enthusiastic code that no one understands. With Diátaxis, you give it a curriculum, a set of recipes, a reference manual, and a company history. The same developer becomes ten times more productive.

Key Takeaways

1. Start with Explanation. Before writing code, write a short paragraph about the problem you're solving. Ask the AI to generate code only after that context exists.
2. Maintain a Reference file. Let it evolve. Use it in every prompt.
3. Use Tutorials to bootstrap the AI. Feed it small examples to teach it your conventions.
4. Write How-to prompts. Treat each bug fix as a small recipe.
5. Review everything. Diátaxis doesn't replace human judgment; it organizes it.

References

• Procida, D. (2016). "Diátaxis: A new architecture for technical documentation." Retrieved from diataxis.fr
• Karpathy, A. (2025, April). Tweet introducing "vibe coding." Twitter.