Think of it as Yoga for the brain, we are going to stretch a bit.
When the Next Programmer after you Isn’t Human
For fifty years we wrote documentation for other programmers. Now we write it for the next AI that inherits our mess. -- YNOT!
Today I met with the kid. I call him a kid because he is half my age, which means he is old enough to be dangerous and young enough to still believe the machine is his friend.
He learned to program not too long ago, but he is already good. Very good. And like most of the new generation, he is not programming alone. He is programming with AI. In his case, Claude.
So there I was, the old master, sitting across from the young gentleman, and the kid taught the old dog a new trick. He said something simple, but important:
He use the AI to document the program for the next AI.
Now that may not sound like much, but it is a revolution wearing work boots.
When I learned programming, one of the first commandments was this: Document your code so another human being can fix it later. Because sooner or later, somebody else was going to inherit your mess. Maybe another programmer. Maybe your future self. Maybe some poor soul hired after you quit.
But now the “somebody else” may not be a person at all.
It may be another AI six months from now, staring at your program with no memory of what you asked, what you meant, what you changed, what you regretted, or what little business rule was holding the whole thing together with chewing gum and prayer.
And if you do not leave that AI a map, good luck. You may have to rewrite the whole thing from scratch.
Maybe you were going to rewrite it anyway. Programmers are like carpenters who burn down the house every few years because they don’t like the angle of the kitchen door.
But still, even if the next AI rewrites the thing, at least it should know what the thing was supposed to do. That means the documentation has to explain more than the code. It has to explain the purpose. It has to explain the original instructions. It has to explain the database schema. It has to explain the business logic. It has to explain the weird decisions, the shortcuts, the traps, the stuff that looks wrong but is actually holding up the roof.
Because AI is powerful, but it is also like a brilliant intern with amnesia. Every morning it wakes up ready to help, with no idea what happened yesterday.
So now documentation is not just for people. Documentation is for machines that will help the people. The kid understood that.
And I had to laugh, because I have been writing software since before half these AI programmers were a bad idea in their father’s imagination. Yet here comes this young gentleman, programming with Claude, teaching the old master something new.
That is how the world changes. Not all at once. Not with thunder.
Sometimes it changes when a kid sits across from you and says:
“You know, you should have the AI document itself so the next AI knows what it is looking at.”
And just like that, an old rule gets a new chapter.
The first programmers wrote code for computers. The next generation wrote code for other programmers.
Now we have to write code, prompts, notes, schemas, and explanations for the next AI that comes along.
Because in the AI age, the prompt is part of the source code.
The documentation is part of the program. And the kid was right.
This makes documentation part of the build, not an afterthought. I will be adding it to all my programs. AI is really good at programming, it is even better at documentation.
Use this as a master prompt for any AI coding project:
You are not only writing or modifying this program. You are also responsible for maintaining the program’s internal documentation system.
Every time you create, modify, refactor, or debug this project, update the documentation so that three audiences can understand it:
The user/operator
A future human programmer
A future AI assistant that has no memory of this conversation
The documentation must explain:
What the program does
Why it exists
How to run it
How the major parts work
What files are important
What database tables, fields, and relationships exist
Also add a Documentation page inside the program interface if this is a web/dashboard application. That page should display the current program documentation in a user-friendly way, including:
Program purpose
System flow
Main features
Data flow
Database explanation
Admin/user instructions
Developer notes
AI maintenance notes
Recent changes
When you change the code, update the documentation in the same pass. Do not treat documentation as optional. The job is not complete until the documentation reflects the current state of the program.
In AI_CONTEXT.md, include a section called “Instructions for Future AI” explaining:
The original purpose of the project
The current architecture
Important design decisions
Common mistakes to avoid
Areas that are fragile or unfinished
How to safely add new features
How to test changes before deployment
Before making any major change, read the existing documentation first, then update both the code and documentation together.
