Documentation debt compounds faster than technical debt. A function with zero comments is annoying; a 3,000-line service file with zero comments, written 18 months ago by someone who quit, is a project killer. AI coding tools have genuine leverage here — but only if you match the right tool to the right documentation level.

There are four distinct levels where AI can help, and each requires a different workflow:

• Level 1: Inline comments (the why, not the what)
• Level 2: Docstrings, JSDoc, and TSDoc
• Level 3: README files and module-level docs
• Level 4: Architecture Decision Records and system diagrams

This guide covers all four, with specific tool setups and honest assessments of where each breaks down.

---

Level 1: Inline comments

Inline comments are the most abused form of documentation. The failure mode AI makes worse, not better: generating comments that restate what the code already says.

# BAD — Copilot default behavior on obvious code
x = x + 1  # Increment x by 1

That comment is noise. What you actually want is the why:

# Retry counter starts at 0; max 3 retries enforced downstream
x = x + 1

AI cannot generate the why from code alone — that lives in your head, a Jira ticket, or a Slack thread from six months ago. What AI can do is prompt you to write it.

Cursor workflow for inline comments:

Open Cursor Chat (Cmd/Ctrl+L), select a block of code, and ask: “What would a new engineer need to know about this block that isn’t obvious from reading it?” The response isn’t the comment — it’s a list of non-obvious facts. You pick the ones worth preserving and write them yourself. This takes 60 seconds per function and produces comments that survive future refactors.

Copilot /explain for unfamiliar code:

When you inherit code rather than write it, Copilot’s /explain command (in VS Code Chat panel) works well as a first-pass comprehension tool. Select the block, type /explain, and it generates a plain-English walkthrough. The practical use: copy the explanation, strip the obvious parts, and add what’s left as a block comment above the function. You edited the comment, so you’ll understand it in six months.

The baseline rule that holds regardless of tool: never let AI write inline comments unsupervised on code you just wrote. It doesn’t know why you wrote it — only you do.

---

Level 2: Docstrings, JSDoc, and TSDoc

This is where AI genuinely earns its keep. Function signatures contain the inputs and outputs; the docstring’s job is to document the contract, constraints, and edge cases. AI can infer a strong first draft from the signature and body.

Cursor

In Cursor Chat, paste a function and ask: “Write a Google-style Python docstring for this function. Include Args, Returns, Raises, and note any constraints on input values.” The key is specifying the docstring convention — Google, NumPy, reST — so output is consistent with the rest of the file.

For TypeScript/React components, ask for JSDoc with @param, @returns, and @example. Cursor’s inline autocomplete will also pick up the pattern after a few manual docstrings and continue writing them as you type new functions.

GitHub Copilot

Microsoft’s training module on documentation generation identifies two primary methods:

1. Inline suggestion: Type """ (Python) or /** (JS/TS) above a function and wait. Copilot completes the docstring from context. Works best when the function name is descriptive and the body is under ~40 lines.

2. Chat-based: Select the function, open Copilot Chat, type “Write a docstring for this function”. More reliable than inline completion for complex functions with multiple return paths.

Copilot’s docstrings tend to be accurate on the happy path but miss error conditions. After generating, always manually add Raises: or @throws entries for any exception the function can produce.

Aider

Aider’s strength for docstrings is batch generation across a file or module. (If you’re not set up with Aider yet, the Aider + Ollama setup guide covers installation and model selection.) The workflow:

1. Launch aider with the target file: aider src/api/handlers.py
2. Switch to ask mode: /ask
3. Prompt: “Which functions in this file are missing docstrings or have incomplete ones?”
4. Review the list, then switch to code mode: /code Add Google-style docstrings to the functions you identified. Preserve existing docstrings.

Aider commits automatically after the change, so you get a clean git history entry per batch. Use --no-auto-commits if you want to review before committing.

Cline

Cline’s Plan/Act mode maps well to documentation tasks. In Plan mode, it analyzes your codebase and proposes a documentation strategy without touching files. In Act mode, it executes. Workflow:

1. Open Cline, enable Plan mode (top toolbar toggle in VS Code extension)
2. Prompt: “Audit the Python files in src/services/ and list functions with missing or stub docstrings”
3. Review the plan Cline generates
4. Switch to Act mode to write the actual docstrings

The advantage over Aider: Cline can navigate multiple files in one session without you specifying each one. The disadvantage: it’s slower and more talkative — better for a weekend documentation sprint than an inline quick fix.

---

Level 3: README and module-level documentation

README quality is the fastest signal of project health to any new contributor. AI can write a passable skeleton in 90 seconds; the problem is the skeleton is always too generic.

The generic README trap

Ask any AI tool to “write a README for this project” and you get:

## Installation
npm install

## Usage
See examples below.

## Contributing
Pull requests welcome.

That’s not a README — it’s a template placeholder with your project name inserted. The fix: feed the AI specific questions to answer, not an open-ended request.

Effective Cursor Agent prompt for README:

You are writing a README.md for a developer who knows nothing about this project.
Answer these specific questions from the codebase:
1. What problem does this solve in one sentence?
2. What are the 3 most common use cases?
3. What does someone need to have installed to run this (with versions)?
4. What is the one command to get a working dev environment?
5. What are the 2-3 non-obvious configuration options that trip people up?

This produces a README with real content instead of scaffolding. You still rewrite the intro and add any context the AI can’t infer — external dependencies, team conventions, production gotchas — but the structure is there.

Module-level docs with Aider

For large codebases, Aider’s architect mode is the right tool for module-level documentation. Architect mode uses two models: one proposes the documentation structure, the other writes the actual content. Launch with aider --architect --model claude-sonnet-4-6 src/ and ask it to create a docs/modules.md mapping each module to its responsibility, public API, and key dependencies.

The output needs human editing — AI doesn’t know which modules are stable vs. experimental, or which are deprecated-but-still-imported — but generating the first draft from code analysis takes 3 minutes instead of 3 hours.

---

Level 4: Architecture Decision Records

ADRs are the highest-value documentation artifact and the hardest to generate with AI. An ADR captures not just what architecture decision was made, but why — what alternatives were considered, what trade-offs drove the choice, what context existed at the time.

AI can document the what. The why requires human input.

Setting up an ADR workflow with Cline

The most practical AI-assisted ADR workflow uses Cline to scan for undocumented architectural decisions, then prompts you to fill in context:

1. Create an ADR template and an ADR/ directory
2. Open Cline and prompt in Plan mode: “Scan this codebase for architectural decisions that should be documented: choice of database, API framework, auth strategy, caching layer, any major third-party integrations. List each with a one-line description.”
3. Review the list — Cline will correctly identify most structural choices
4. For each item, switch to Act mode: “Create an ADR file for [decision]. Fill in the Context and Decision sections from the code. Leave Consequences and Alternatives Considered blank — I will fill those in.”
5. Fill in the Consequences and Alternatives yourself

This approach is documented in practice by engineering teams using Claude Code to manage ADR generation continuously — the agent creates ADRs as architectural changes happen, rather than reconstructing them from memory weeks later.

The AGENTS.md shift

A 2026 development worth tracking: architecture documentation is increasingly written for AI consumers, not just humans. Faisal Feroz’s analysis in AI Advances argues that AGENTS.md (a living document describing how AI coding agents should interact with your codebase) is becoming as important as traditional ADRs. If you’re using Cursor Rules, Cline’s .clinerules, or Aider’s .aider.conf.yml, you’re already writing agent-targeted architecture documentation.

The practical implication: an ADR that documents why the API layer was split from the data layer is useful for humans. An AGENTS.md entry that says “never moDify schema.sql directly — always generate a migration file” is useful for both humans and AI agents executing changes.

---

Tool comparison by documentation level

Documentation level	Best tool	Why
Inline comments (why-focused)	Cursor Chat	Fast Q&A to surface non-obvious facts; human writes the comment
Single-function docstrings	Copilot inline	Lowest friction; type the delimiter and it autocompletes
Batch docstrings across a file	Aider (/ask → /code)	Processes whole file at once; auto-commits each batch
README generation	Cursor Agent	Best at answering specific questions about project structure
Module-level overview docs	Aider (architect mode)	Two-model proposal/editing loop produces coherent module map
Architecture Decision Records	Cline Plan/Act	Scans multi-file codebase; Plan mode avoids premature writes

---

What AI gets wrong about documentation

Over-documents the obvious. AI generates comments like # Open database connection above conn = db.connect(). These add noise. Budget 20-30 minutes after any AI documentation run to delete the self-evident comments.

Under-documents the non-obvious. The function that has a subtle off-by-one in edge case handling, the middleware that must run before auth (not after), the retry logic that assumes idempotency — AI will miss all of these because they require knowledge of the system that isn’t in the code.

Stale the moment the code changes. AI-generated docstrings don’t update themselves. A docstring that was accurate when generated becomes misleading after three refactors. The discipline: if you’re modifying a function, the docstring is part of the diff. Copilot’s inline suggestions will update the docstring as you change the signature if you ask it to, but it won’t do this automatically.

---

Honest take

For inline comments: use Cursor to identify what’s non-obvious, but write the comment yourself. This takes slightly longer than letting AI write it and produces documentation that actually helps future readers.

For docstrings at scale: Aider in batch mode is the fastest path to a documented codebase. Run it file by file on your src/ directory over a weekend, review each batch, then enforce docstrings in code review going forward.

For architecture docs: the human-AI split is 30/70 in the wrong direction. AI handles 30% (structure, identifying decisions that exist); you handle the other 70% (why those decisions were made, what alternatives were rejected, what context would change the answer). Treat AI as a documentation scaffolding tool, not a documentation author.

The underlying problem AI can’t solve: if you never wrote documentation because you didn’t have time, AI gives you a draft in seconds — but you still need to review it. The bottleneck was never typing speed. The AI’s real value is lowering the activation energy enough that you actually do the documentation task instead of deferring it to next sprint.

If you’re embedding AI into a broader code quality workflow, the documentation layer pairs naturally with test-driven AI coding (where tests serve as executable specs) and AI-assisted refactoring (where good docstrings are the first safety net before a refactor). And if you’re using Cursor Rules to govern how the AI agent behaves in your project, the Cursor custom rules guide shows how to enforce documentation standards in .cursor/rules files so the agent generates docstrings by default on every new function.

---

Sources

• Generate Documentation Using GitHub Copilot Tools — Microsoft Learn (updated April 2026)
• Documenting and explaining legacy code with GitHub Copilot — GitHub Blog
• Building AI-Enhanced Documentation: From Code Comments to Living Architecture Docs — Kinde
• AI code documentation automation — Graphite
• AI-generated Architecture Decision Records — Adolfi.dev
• AGENTS.md vs Architecture Decision Records — Faisal Feroz, AI Advances
• Chat modes — Aider documentation
• Cline documentation — docs.cline.bot

Last updated May 17, 2026. Tool features and pricing change frequently; verify current state before purchasing.