Natural Language is Now Code

TL;DR: With AI agents writing our code, natural language has become the new high-level programming language. But we’re still treating documentation like an afterthought while throwing away the actual source code of our AI-generated systems. Our tools haven’t kept up (they’re still designed for a “code first” world), so we need to adapt existing tools for document workflows and harness the power of natural-language-as-code. I’ll show you examples of both.

The Great Inversion

For decades, code was truth. Documentation was that thing we promised ourselves we’d write. Eventually. Maybe.

Now? The documents describing context and goals drive the creation of code, much like C++ once drove assembly generation. We’ve inverted the relationship between documentation and implementation. The problem? Our natural language “compilers” (LLMs) are leaky abstractions.

But there’s a bigger problem most developers haven’t noticed yet.

Vibe Coding: Throwing Away Your Source Code

Let’s talk about why vibe coding is a bad idea for anything other than prototyping. I struggled for a while with why it didn’t sit well with me. I’ve come to realize why: when you have an ephemeral conversation with an AI and convert it directly to code, that conversation contains all the reasoning, all the context, all the decisions that led to that code.

Then you throw it away.

This is literally like writing C++, compiling it to assembly, and deleting the source files.

The Current “Solutions” Don’t Work

So you decide to be responsible. You ask the AI to generate a markdown document capturing your conversation. But the chances it’s completely tight are low. We need to fix it! Now what?

Current development environments push you toward two equally frustrating options:

1. Manual editing: Edit the markdown yourself, then feed it back to the AI. Tedious. Defeats the purpose of having an AI assistant.
2. Micro-management: Give the AI instructions one at a time. “Drop this section.” “Add that bit.” Death by a thousand prompts. And a thousand ticks of the clock.

Both approaches made sense in the era of smart autocomplete. They make zero sense when your collaborator can understand context and intent.

Wisdom from Douglas Adams

I struggled with this problem for months. Tried forked documents. Tried elaborate versioning schemes. Nothing felt right.

Then I remembered Douglas Adams’ observation about Newton and the cat flap. As Adams wrote, “It is a rare mind indeed that can render the hitherto non-existent blindingly obvious.”

The solution was staring me in the face. How do humans collaborate on documents?

We leave comments.

The Workflow That Actually Works

Here’s what I do now:

1. Generate: Ask the AI to create a document. Optionally, have other AIs review it.
2. Commit: Do an initial commit identifying this as the AI version.
3. Comment: Insert markdown comments directly in the file. Real comments. Like this:<!-- You're overdoing this. It's just MVP, we don't need rate limiting and DDOS protection yet. Let's put a pin in these features. -->
4. Commit again: The version with my comments goes into history.
5. Iterate: Ask the AI to address the comments. Have it summarize what changed. Get other AIs to review if needed.
6. Final commit: Review and commit the clean version.

Everything is preserved. Every decision, every piece of feedback, every iteration. If we need forensics later, it’s all there.

From Problem to Power

This approach isn’t just solving the leaky compiler problem. It’s opening new possibilities.

I recently faced an interesting challenge. I wanted to make my agent-human co-development methodology easy to integrate into existing projects. But every environment is different. You can’t write a universal install script. And you can’t ask humans to handle it because they won’t understand what you’re trying to accomplish.

My solution? No install script. Instead, I created an INSTALL.md file with instructions written for an AI to interpret.

Now adoption is simple. Tell users to type this into their AI: “Here’s the URL of the installation instructions.” The AI handles the rest.

Natural language has become executable.

The New Discipline

We need to bring the same rigor to documentation that we once reserved for code. Version control for specifications. Testing for natural language “programs.” Code review for context documents.

The tools proposing solutions (Kiro, SpecKit, and others) are all orbiting this central insight: documentation is no longer about describing code. Documentation is the code.

We’re just compiling it to a lower-level language that happens to look like Python or JavaScript.

What This Means for You

Start treating your conversations with AI as source code. Version them. Review them. Refactor them.

Stop throwing away your source to keep the compiled output.

The shift has already happened. Natural language is code. The only question is whether you’ll treat it with the discipline it deserves.

What’s your take on this shift? How are you managing the transition from code-as-truth to documentation-as-source? I’d love to hear what’s working (and what isn’t) in your workflows.