A Manager's Dilemma

At the end of last year, my team took over a core business system that had been running for seven years. The original maintenance team was down to one person, who was about to resign. What they left us with: over 300,000 lines of code, scattered Chinese comments, a Word-version architecture diagram from five years ago, and that classic handover line — "all the logic is in the code."

As the head of a small team, my biggest worry wasn't poorly written code, but the fact that knowledge existed only in someone's head. New hires didn't dare make changes, veterans didn't dare touch it, and every release felt like defusing a bomb. Spending two months having two senior engineers document everything purely by hand? The business roadmap simply wouldn't allow it. But doing nothing meant the technical debt would snowball, and the risk from personnel turnover would be completely unmanageable.

What I needed wasn't "AI to write code for me," but AI to make the knowledge embedded in existing code explicit, turning it into a shared team asset.

Think Through the Process Before Acting

My principle: AI doesn't directly modify code; it only produces "documentation-layer" output — comments, module descriptions, architecture diagrams, and call relationship lists. This way, even if the AI makes mistakes, production code stays clean and the risk is contained. The overall process has five steps:

Step 1: Define scope and priorities. Not all code is worth documenting. I had the team first list high-risk modules: frequently changed ones, ones with a history of production incidents, and ones with external dependencies. We identified six core modules, roughly 80,000 lines.

Step 2: Feed it context. Feed the module code to the AI in batches (long-context models like the Claude, DeepSeek, and GPT series), along with database table structures and whatever scattered documentation existed. The granularity should be "one complete module" — too fine-grained loses context, too coarse exceeds the window.

Step 3: AI draft, human review. All AI-generated comments and architecture descriptions must be reviewed by an engineer familiar with the business. A common AI mistake is treating "the current state" as "the design intent" — for example, for a piece of obviously patchy, ugly code, the AI will solemnly explain that it exists "to elegantly handle edge cases." This is where review adds value — correcting the AI's wrong guesses.

Step 4: Commit documentation to version control. All AI-generated documentation lives alongside the code repository and goes through the normal code review process for merging. From then on, documentation shares the same lifecycle as code.

Step 5: Establish an incremental process. Set a team rule: when new code is merged, the submitter is responsible for having the AI synchronously update the corresponding module's architecture documentation. Backfilling documentation isn't a one-time campaign — it's an ongoing process.

A Reusable Prompt Template

This is the template we actually used, after three rounds of iteration, for your reference:

你是一位资深软件架构师，正在帮助团队补齐遗留系统的文档。

# 角色
- 你只输出文档，不修改任何代码逻辑
- 你区分「代码做了什么」（事实）和「推测的设计意图」（需标注[推测]）

# 任务
1. 为下列代码补齐中文注释：
   - 每个文件顶部：模块职责、依赖关系、被谁调用
   - 每个函数：功能、入参出参含义、副作用、已知风险点
2. 输出一份模块级架构说明，包含：
   - 核心数据流（输入从哪来、处理过程、输出到哪去）
   - 与其他模块的调用关系
   - 疑似技术债清单（命名混乱、重复逻辑、硬编码配置等）

# 输出格式
- 注释以「// 【补注】」开头，便于后续人工评审时定位
- 架构说明使用 Markdown
- 不确定的内容必须标注[待人工确认]，禁止编造

# 代码如下
<在此粘贴代码>

Two key design decisions: first, "distinguishing fact from speculation" — this is the core of risk control, preventing AI's imagination from being enshrined in documentation as truth; second, the "supplementary note" marker, which lets reviewers spot AI-added content at a glance.

Before and After: What Happened One Month Later

Efficiency. Our estimate was that documenting eight modules purely by hand would take two senior engineers over a month; with AI drafts plus human review, it actually took two engineers about a week. This isn't "AI replacing people" — it shifted human time from "typing up documentation" to "judging right from wrong" — the latter being the part that truly requires experience.

Collaboration. Previously, when new colleagues had questions, they had to corner the departing veteran; now the module architecture documentation lives right in the repository. New-hire onboarding time went from "barely able to make small changes after a month" to "able to independently handle routine iterations within a week." The handover risk shifted from "can this system even be maintained" to "which section of the docs needs further enrichment."

Risk control. The most tangible benefit showed up during a production incident: a downstream service threw an error, and where it used to require digging through code and hunting down people, this time the on-call engineer located the problematic module directly using the call relationships in the architecture documentation, significantly cutting resolution time. In addition, the [pending human confirmation] markers helped us catch a dozen or so AI misinterpretations during review, and incidentally exposed several pieces of legacy code whose origins even the veterans couldn't explain — these went onto the refactoring candidate list.

Cost. The total API costs worked out to far less than two person-months of engineer time (check official pricing pages for specific model prices; costs vary greatly across models, long-context models bill by token, and it's advisable to do a cost trial with a small module first). We called models via API rather than the web interface, making it easy to incorporate into unified usage monitoring and budget management.

A Few Tips for Managers

1. AI output must go through human review, and reviewers must know the business — otherwise the documentation has zero credibility, which is more dangerous than having none at all.
2. Don't try to document all code in one go. Rank by risk and start with the modules most likely to blow up.
3. Put documentation in the code repository and review process, making it part of engineering standards — not some "final_v3_revised.docx" sitting in a cloud drive.
4. Manage all AI calls uniformly through the API, making it easy to control budgets, audit usage, and wire in more automation later.

Legacy systems aren't scary; what's scary is knowledge that lives only in a few people's heads. AI can't understand the business for you, but it can reduce your team's cost of understanding by an order of magnitude — that's worth spending a week to try once.

If you want to get started, register an API account and begin with a small module: https://api.thistoken.ai/register

---

Every example in this post runs with a single API key — get yours at https://api.thistoken.ai/register and start in minutes.