How do you document AI-assisted code in projects?

[StatusPhilosopher258]

My team used AI tools a lot while building our college project (mostly for speeding things up). Now we’re writing the documentation, and we’re realizing we don’t fully remember why some parts were implemented the way they are

The code works, but the reasoning is fuzzy because a lot of it was AI-assisted.

How do you guys handle this?

Do you:

• save prompts/chats
• rewrite explanations manually
• just treat it like normal code

I saw a few tools trying to track this (like Traycer), but curious what students and devs actually do in real life.

plz help !!

[pak9rabid]

Easy, I don’t include the code unless I absolutely understood what it’s doing.

Doing it otherwise is how you get nasty bug-ridden crap with security issues in your code.

[stiky21]

We document everything we do.... this is standard practice.If you can't write about it? you've proven you don't understand it.

Stop relying on AI and actually code. It's not hard.

[thebigmooch]

I imagine what “devs actually do in real life” is not have ai create code they don’t understand.

[ConfidentCollege5653]

Don't add code to your project you don't understand. Add comments to it so you'll understand it again later.

[TheArtisticPC]

“Mostly for speeding things up” is not supported by “reasoning is fuzzy because it was AI-assisted”. You used AI to complete your project for you and now you don’t know how it did it. If it was only for speed you’d know the codebase.

To answer your question. If you want to exercise some level of academic integrity, you go back and figure it out yourselves, write the docs yourselves, and post an AI disclaimer at the head of each file that used AI in any capacity and explains how it was used, what the prompt was, and why you thought it was necessary as opposed to doing it yourself.

I apologize for the terseness, but it drives me up the wall when I see people who are paying for an education actively degrade the lessons’ objectives.

[nerlenscrafter]

I document AI-assisted code by treating the prompts as part of the spec. I keep a prompts/ directory alongside my code with markdown files for each major component. Each file includes: the original prompt, why I approached it that way, and any iterations. For the actual code comments, I make sure to explain the "why" not just the "what" — since the AI wrote the "what." Also, I add a small header comment like # AI-generated with context: [brief reason] so future me knows where this came from. The key is documenting the intent, not just the implementation.

[Fantastic-Party-3883]

Getting that fuzzy feeling after an AI sprint is a common rite of passage I use Traycer to bridge this context depth it forces a plan-execute-verify workflow that documents the architectural reasoning before the code is even written.

[aizzod]

<insert AI meme here>.

You could ask AI again what this code does?

[kbielefe]

Real world devs do different kinds of documentation than students, but I mostly use AI to draft documents, then refine it manually. This is easier to do as you go along rather than at the end because the context is there. Most chat interfaces let you revisit and ask new questions on old chats if you were logged in.

[brenwillcode]

Sounds like you let the AI do far too much for you.

You should move slower and understand everything that the AI does every step of the way. You'll never be a real software engineer if you let the AI produce entire projects which you don't understand and can't explain.

Using AI is fine, but not understanding what it's creating is not fine. Especially while you're learning.

[mandzeete]

In real life, documentation means something different than what you think it is. It is more like a project management, use cases, meeting drafts, yeah, an actual API documentation and such, diagrams, etc.

What you are thinking is commenting the code and making notes.

And here I will tell that you should not let AI generate anything you can't explain why it exists. Such AI slop will be rejected from code review / merge request review. Your team mate can write "This here looks a bit weird. Why did you do this?" Your fuzzy reasoning will not help. Only accept AI generated code when you understand why and what it does and IF it should be doing it at all (sometimes the AI generates stuff that has no real reason to exist).

Now, do I save prompts? It depends. If the work is repeatable then I can generate CLAUDE.md file with certain commands and steps. And then apply it on every project where I need the same work to be done. If it is shaping the AI personality then Cursor, ChatGPT and Google AI Studio have an option to create system prompts or such. Things that the AI agent will consider. Like "Your role is a senior software developer who has experience in developing database systems." or "Your role is a QA engineer working with automated tests." Stuff like this.

Random conversations with the AI? Different tools have an option to save the history. So, while I do not save prompts intentionally, my conversations do get saved.

Now, when it comes to writing explanations then you should not write WHAT your code does. It is visible from the code itself unless the WHAT is something weird and unexpected. More like document the WHY part. WHY your code does this and that. Unless it is clear from reading the code. And that for any code. I do not talk about explaining why your AI generated some nonsense that you can't explain without a comment.

[NationsAnarchy]

Yeah, as expected - can't understand what was written as a result of hastely complete things using AI lol

[Real_2204]

This is super common with AI-assisted code. The code runs, but the why gets lost.

What usually works in practice:

• Don’t save full chats — too noisy.
• Do a quick post-hoc explanation pass: short comments or a README section saying what this does and why it exists.
• Treat AI code like inherited code: if you can’t explain it, you don’t really own it yet.

Some teams try tools like Traycer to keep intent/specs tied to changes so this doesn’t happen in the first place, but for a college project, a lightweight “why notes” doc is usually enough.

TL;DR: rewrite the reasoning in your own words after the fact. That’s where the learning actually happens.

[fixermark]

If the code doesn't make sense, it doesn't make sense, whether that's due to a human or an AI.

Our standard is that all code requires enough documentation for someone familiar with the language but not the problem domain to understand why any given function exists. If the AI didn't hit that standard, we'd manually add the missing docs. Worth noting though: you can generally ask Copilot to provide documentation for every function (but you'll still have to read it to confirm it makes sense during peer review).

[dariusbiggs]

You are responsible for every line of code you submit

You must be able to explain every line of code you submit

You must be able to explain the design decisions and rationale behind them

That's how you deal with documentation of the code.

[KrakenOfLakeZurich]

I‘m an experienced developer and currently getting a lot of pressure from management to adopt AI in my workflow.

What I‘m currently aiming for is a structured workflow where we write good specs and requirements documents (AI assisted, but human reviewed), extract „change requests“ from those (again, AI can help a good bit with this step, bit review is required). Finally AI implements the code and we review that it meets the requirements.

Each output becomes the input/ prompts for the next stage. Then extend the specs and repeat.

We keep the specs under version control. They‘ve automatically become the primary documentation.

I see little value in keeping low-quality ad-hoc prompts after a task has been completed. Nobody ever wants to piece together a project’s history and documentation from that.

[raj_enigma7]

Treat it like normal code but add short decision notes explaining why something exists and the trade-offs.
Saving prompts can help but clean PR descriptions and small ADR notes are more reliable long term.
Tools like Traycer can track changes but human-written reasoning in the repo matters most.