Code is the Documentation >>> Documentation is the Code

The Old Truth: Code Never Lies

For decades, developers preached “code is the documentation.” Why? Because:

• Documentation drifts from reality
• Comments become lies over time
• Only code executes, only code is truth

The semantic gap was real. No documentation could fully capture runtime behavior, edge cases, actual implementation details. Reading code was the only way to truly understand a system.

The Etymology of “Code”

“Code” comes from Latin “codex” - a book of laws, a systematic collection of statutes.

Originally, a code was:

• A system of rules
• A way to encode meaning
• A formal specification of behavior

Not the implementation - the specification.

The Paradigm Flip

With AI and VDD, we’re returning to the original meaning. Documentation doesn’t describe code anymore - it generates it and therefore they are tightly coupled

Old world: Write code → Extract documentation New world: Write documentation with AI while Generating code

The documentation becomes the “codex” - the law that governs what gets built.

Why This Works Now

AI bridges the semantic gap:

• Natural language → Working implementation
• Intent → Execution
• Specification → System

What changed? The compiler. AI is a compiler for human intent.

The New Reality

When you write:

This service handles authentication with rate limiting of 100 requests per minute

AI doesn’t just read this - it implements it. The documentation isn’t describing code that exists. It’s creating code that will exist.

Documentation as Source Code

In vibe coding:

• project_description.md compiles to architecture
• interface.md compiles to APIs
• known_requirements.md compiles to features

Your documentation is source code for an AI compiler.