AI-Powered Documentation: Make Your Codebase Self-Explanatory

Introduction

Andrej Karpathy recently introduced the idea of "vibe coding" on X (formerly Twitter), which is a process where we develop apps but "forget that the code even exists". I believe in this approach, but I also have a fundamental need: code understanding: what AI has executed; does it fulfill requirements, and is it safe?

Through documentation can solve the problem. Imagine opening a project, you will see a docs folder that has the architecture, features, and changes documents. And each source code file contains a comment block about what it is for, how it works. These documents can help us understand the code base better.

However, documentation is a difficult task. In fact, according to the Agile practices, due to time constraints, comprehensive documentation is sometimes sacrificed in favor of rapid coding and delivery. Can we even expect having up-to-date documents?

Well, the good news is that AI can do the documentation tasks. In this post, we’ll explore two powerful prompts you can ask AI to do the documentation.

1. Describe Each Source File

Prompt:

• Ensure each source file begins with a comment block summarizing its purpose and logic.
  • If no block exists, create one before editing.
  • After completing changes, update this block to reflect the changes.
  • Always make the comment block clear and concise.

Benefits:

This prompt will add a comment block to source code files summarizing its purpose and logic.

Example

Below is a simple example.

/**
 * userController.js
 *
 * Purpose:
 *   - Handles HTTP requests related to user accounts.
 *     • GET /users/:id → fetch user by ID
 *     • POST /users    → create a new user
 *     • PUT /users/:id → update user information
 *     • DELETE /users/:id → delete a user
 *
 * Logic Overview:
 *   1. Validate request payloads (using Joi schema).
 *   2. Interact with UserService to perform CRUD operations on the database.
 *   3. Send appropriate HTTP status codes and JSON responses.
 *
 * Last Updated:
 *   2025-06-05  by Jane Doe (Refactored to use async/await and centralized error handler)
 */

import { validateUserPayload } from '../validators/userValidator';
import UserService from '../services/UserService';
import { handleError } from '../utils/errorHandler';

export async function getUser(req, res) {
  try {
    const { id } = req.params;
    const user = await UserService.findById(id);
    return res.status(200).json(user);
  } catch (err) {
    return handleError(err, res);
  }
}

// …rest of the CRUD handlers…

Having a comment block for each file is helpful because:

• It explains what the file is for and how it generally works. The information is good for human and for AI.

• By reading the comments, AI the overall design context, special logic or important points. AI can generate code more acuurately and prevent accidental errors or unintended consequences.

• It provide valueable detail for bothcode review and security analysis in the future.

2. Make a Feature Documentation Library

Prompt:

• Ensure features are documented in the ./docs directory.
  • Before modifying code, review existing files in ./docs to understand current implementation.
  • If no appropriate documentation exists, create a new Markdown file in ./docs outlining your analysis.
  • After completing changes, update or add documentation in ./docs to match the new code.
  • Finally, check the ./docs folder to see which files exist and decide if any need updating or deletion based on your changes.

Example

Imagine you’re adding a new “Bulk Email” feature to your CRM. Here’s how an AI generated document could look:

# Bulk Email Feature

## Purpose
Allow admins to send a templated email to multiple contacts at once.

## High-Level Flow
1. Admin uploads a CSV of email addresses  
2. System validates addresses via `validateCSV()`  
3. API enqueues emails in SendGrid batch queue  
4. Worker process sends out messages and logs results

## Data Model
- `EmailBatch` (id, templateId, status, createdAt)  
- `EmailRecipient` (batchId, email, status, errorMessage)

## API Endpoints
- `POST /api/bulk-email/start`  
  • Request Body: `{ templateId: string, csvFile: File }`  
  • Response: `{ batchId: string }`  
- `GET /api/bulk-email/status/:batchId`  
  • Response: `{ status: "pending" | "in_progress" | "completed", sentCount: number, failedCount: number }`

## Validation Rules
- CSV file max 10,000 rows  
- Template must exist and be enabled  
- Rate limit: 1 email batch per 5 minutes per org

Now, we have adocs foler that contains many such markdown files house deeper explanations — API design decisions, architecture diagrams, usage examples, and more.

Instead of scattering notes, diagrams, or instructions across private notes or comments, the dedicated ./docs is a sigle source of truth everyone knows exactly where to look.

3. Automate the Documentation

Writing the comment blocks and features documents once is great; keeping it current is game-changing.

You can put these two prompts into your AI code assistants’ system prompts, they will take effect each time you ask AI to make changes. It will keep the documents up to date all the time.

Each AI code assistant has its own way of customizing system prompts. In the case of Github Copilot, we can create and save the above in the file ‘./gihub/copilot-instructions.md, see Customize chat responses in VS Code

Conclusion

Documenting code isn’t something to be sacrificed anymore. Using the two prompts as system prompts, AI will create comprehensive documents to make your repository friendly and self-explanatory. — saving you time, reducing confusion, and even helping AI itself when working on it in the future.

Happy documenting!