Skip to main content

The prompt as documentation: Should AI-generated code include its origin story?

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.

Popular posts from this blog

.NET 8–Keyed/Named Services

A feature that a lot of IoC container libraries support but that was missing in the default DI container provided by Microsoft is the support for Keyed or Named Services. This feature allows you to register the same type multiple times using different names, allowing you to resolve a specific instance based on the circumstances. Although there is some controversy if supporting this feature is a good idea or not, it certainly can be handy. To support this feature a new interface IKeyedServiceProvider got introduced in .NET 8 providing 2 new methods on our ServiceProvider instance: object? GetKeyedService(Type serviceType, object? serviceKey); object GetRequiredKeyedService(Type serviceType, object? serviceKey); To use it, we need to register our service using one of the new extension methods: Resolving the service can be done either through the FromKeyedServices attribute: or by injecting the IKeyedServiceProvider interface and calling the GetRequiredKeyedServic...

Azure DevOps/ GitHub emoji

I’m really bad at remembering emoji’s. So here is cheat sheet with all emoji’s that can be used in tools that support the github emoji markdown markup: All credits go to rcaviers who created this list.

Kubernetes–Limit your environmental impact

Reducing the carbon footprint and CO2 emission of our (cloud) workloads, is a responsibility of all of us. If you are running a Kubernetes cluster, have a look at Kube-Green . kube-green is a simple Kubernetes operator that automatically shuts down (some of) your pods when you don't need them. A single pod produces about 11 Kg CO2eq per year( here the calculation). Reason enough to give it a try! Installing kube-green in your cluster The easiest way to install the operator in your cluster is through kubectl. We first need to install a cert-manager: kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.5/cert-manager.yaml Remark: Wait a minute before you continue as it can take some time before the cert-manager is up & running inside your cluster. Now we can install the kube-green operator: kubectl apply -f https://github.com/kube-green/kube-green/releases/latest/download/kube-green.yaml Now in the namespace where we want t...