In a recent code review, I stumbled upon something that made me pause: a developer had included the original AI prompt as a comment block above a set of classes. At first glance, it seemed like unnecessary clutter. But as I read through both the prompt and the resulting code, I realized I was maybe witnessing the birth of a new documentation practice that could fundamentally change how we understand and maintain AI-assisted codebases.
The case for prompts as living documentation
Everyone who took the time to dig a little deeper in using AI as part of his day-to-day coding activities knows that a carefully designed and written prompt can make all the difference. So, wouldn't it be unfortunate that all the effort we put into it is lost after the AI agent has done his job?
Some other reasons I could think of that makes storing these prompts valuable:
Reproducibility: If we need to modify the AI generated code, we could adjust the prompt and regenerate rather than hand-editing AI-generated code we might not fully understand.
Intent preservation: The prompt captures business context that might not be obvious from the code itself.
Debugging aid: When the code doesn't work as expected, the prompt reveals whether the issue was in the human request or the AI's interpretation.
The case against
But then I started to wonder; are we really going to start polluting our codebases with AI conversation history?
Noise vs. Signal: Not every function needs its origin story. A simple utility function generated from "write a function to capitalize first letters" doesn't warrant prompt documentation.
Maintenance burden: Who updates these comments when requirements change? Do we update the prompt, regenerate the code, then update the comment again?
Version chaos: What happens when we iterate on prompts? Do we keep a full history in comments?
The questions I can't answer (yet)
The more I dig into this, the more questions emerge:
Is this actually useful or just novel? Are we documenting prompts because they provide genuine value, or because AI-assisted development is so new that we're not sure what practices will prove valuable?
What's the half-life of prompt documentation? Code can last years or decades. Will a prompt from 2024 be meaningful to a developer in 2030 working with completely different AI tools?
Are we solving the wrong problem? Instead of documenting prompts, should we focus on making AI-generated code more self-documenting?
Where do we draw the line? If we document prompts for complex functions, what about any refactoring we do afterwards?
Have you encountered prompt documentation in your own code reviews? What's your take—valuable practice or unnecessary overhead? I'm genuinely curious to hear from others wrestling with these same questions as we collectively figure out what good AI-assisted development looks like.