The Phone Call Managers Fear Most

1. The Call Every Manager Dreads

At the end of last year, my team took over a legacy system handed off from another department. On handover day, they sent us a compressed archive: over 300,000 lines of code, not a single comment, architecture documentation frozen three years ago and inconsistent with reality. Of the two colleagues who wrote the code, one had already left the company, and the other was on a long leave.

Two weeks after the handover, the business side came with a request: modify a billing logic. I assigned two senior engineers to read the code. Three days later, their feedback was: "We can change it, but we can't guarantee we won't break something else." To a manager, that sentence means: the risk of this system is uncontrollable.

I believe many managers of small teams have encountered similar scenarios:

• Knowledge is concentrated in a few individuals. Whoever understands a piece of code becomes a single point of failure.
• Onboarding takes too long. With a limited hiring budget, new hires are still reading code a month in.
• Impact assessment before changes is guesswork. During requirement reviews, no one can accurately state the blast radius of a given module.
• Documentation is a liability, not an asset. No one has time to write docs, and whatever gets written is outdated quickly.

The essence of the problem isn't "lack of documentation," but a widening gap between the team's understanding and the actual state of the code, with no manpower to close it.

2. What AI Can Do in This Scenario

My judgment was this: let AI serve as the "minesweeping sapper doing the first pass," not as a "replacement for engineers." Specifically, three tasks:

Task one: batch-comment the code. The cost of AI reading a single file is nearly zero. Have it read the logic file by file and output function-level and module-level comments, with humans only spot-checking.

Task two: produce architecture documentation drafts. Let AI reverse-engineer module boundaries, call relationships, and data flows from the code, generating an initial architecture doc that engineers then correct. The difference between a draft and a blank page is a full week of person-days.

Task three: build a risk inventory. Have AI flag high-risk spots: core logic without test coverage, hardcoded configuration, obviously outdated patterns. This list directly determined the priorities of my subsequent scheduling.

These three tasks all point to one management goal: turning "no one can explain this" into "here's a draft to argue about." Documentation accuracy doesn't need to hit 100% on day one—but there must first be an artifact the team can annotate and correct.

3. The Process We Actually Ran

I designed the whole process in four steps, with the emphasis on process and risk control rather than the model itself.

Step one: define scope and control input granularity. 300,000 lines can't be fed in all at once. We split the codebase by directory into roughly 200 "analysis units," each sized to fit entirely within the model's context. We first had AI output an overview of the module inventory and dependency relationships, and based on that I confirmed the analysis order—starting from the core modules with the most dependents.

Step two: generate by role, not everything at once. For the same code, we had AI output three different deliverables in three different roles:

1. Comments (for future code readers)
2. Module documentation (for people doing requirement assessment)
3. Risk flags (for me, making scheduling decisions)

The quality of separately generated outputs was clearly higher than everything generated together in one pass, and it also made it easier to assign different reviewers to each.

Step three: human-machine cross-review—this is the step I value most as a manager. The rules were explicit:

• Everything AI produces is "pending verification" by default and does not go directly into the main branch of the codebase.
• Comments are spot-checked by the original module maintainers: 100% human review for the core billing modules, 10% sampling for peripheral tooling code.
• Architecture documentation is walked through in a meeting; anyone who finds a factual discrepancy annotates it on the spot.
• All AI-generated content carries a marker (e.g., "AI-generated, human reviewer: XXX" in the file header), so that if errors are found later, they can be traced back to the reviewer.

Step four: bake the deliverables into the process. Comments get merged into the codebase; architecture docs go into the wiki; the risk inventory becomes the quarterly refactoring candidate list. More importantly, we agreed that from now on, newly merged code must include AI-generated comments in the PR, confirmed by the reviewer. This turns a "one-time campaign" into an "ongoing mechanism."

4. Before and After

Efficiency:

These figures are rough internal estimates from our team, for order-of-magnitude reference only; results will vary greatly across codebases.

Risk: After the handover, our biggest worry was "unknown blast radius of changes." The AI-generated risk inventory identified more than a dozen pieces of core logic without test coverage, and we prioritized writing tests for them. In the next release, regression defects dropped noticeably—this change can't be precisely attributed, but the team was clearly more confident during requirement assessments.

Collaboration: In the past, during requirement review meetings, engineers often said "I'm not sure about this part." Now, people open the architecture doc and point: "Here's the call chain; the blast radius is these two modules." The subject of discussion shifted from "memory and guesswork" to "documentation and annotations." Meetings got shorter, and there was less wrangling.

5. A Reusable Prompt Template

This is the core template we used in step two; with minor modifications it can work for your codebase:

你是一位资深软件架构师，正在帮助团队为一个缺乏文档的遗留代码库补齐说明。

## 背景信息
- 技术栈：{{填写语言/框架/数据库}}
- 系统用途：{{一句话描述业务}}
- 本文件在整体中的位置：{{模块路径}}

## 你的任务（按顺序完成）
1. 为下列代码中每个函数/类添加中文注释：
   - 用途（一句话）
   - 参数与返回值中不直观的部分
   - 副作用（写库、发请求、改全局状态）
2. 总结本文件的核心职责，不超过5句话。
3. 标记你发现的风险点，每条注明行号和理由：
   - 硬编码配置/密钥
   - 无错误处理的IO操作
   - 可能的并发或事务问题
   - 明显过时或不安全的写法

## 输出要求
- 只输出你能从代码中确证的内容，不确定的地方明确写「待人工确认」
- 不要猜测不存在的业务背景
- 注释语言与代码库现有风格保持一致

## 代码如下
{{粘贴代码}}

The most critical line in the template is "clearly mark uncertain areas as pending manual confirmation." This turns the AI hallucination problem from "hidden landmines" into "explicit to-dos," which makes review far more efficient.

6. Final Thoughts

On the tooling side, we used a model with long-context support, integrated with our team's existing code hosting workflow; API costs are per the pricing page on the official site. For the entire project, the cost worked out far lower than having two senior engineers spend a full month writing documentation.

If you want to replicate this process in your own team, start with a pilot on a medium-sized module, get the "generate—review—institutionalize" loop working end to end, and then scale up. If you're still choosing a suitable model service, check out this platform—registration here: https://api.thistoken.ai/register

A legacy codebase isn't a burden; what's missing is just documentation that lets people quickly understand it. And for that, AI has done the most expensive first pass for you.

---

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