AI 写代码注释和文档：让老项目变清晰的流程

这篇能做出什么

跟着本文走完，你会拿到四样可以直接放进仓库的产物：

1. 一份仓库地图：每个文件负责什么、关键函数有哪些、谁依赖谁；

2. 关键函数与类的 docstring、必要的行内注释，且代码逻辑一行未动；

3. 一份 README 与架构说明，能直接给新同事或外部交付方看；

4. 一套可重复执行的提示词、脚本与校验命令，下次接到老项目还能再跑一遍。

适用场景：接手别人的项目、翻出半年没看的自己的项目、需要把内部系统交付给另一个团队。整个过程的核心思路只有一条——先让 AI 读，再让 AI 写，最后人工校准。

前置条件清单

• 一个 Git 仓库，工作区干净（git status 没有未提交改动）。
• 能运行项目的语言环境，例如 Python 3 或 Node.js，具体版本以官方文档当前版本为准。
• 一个能读取整个代码库的 AI 编码工具：IDE 插件或命令行工具都可以，选型以官方文档当前版本为准。
• 可选：pre-commit、ruff、pydocstyle 之类的 lint 工具，用来兜底检查。
• 时间预算：小仓库半小时，几万行的仓库按目录分批做，留出几小时。
• 一次脱敏判断：确认代码能否发送给所选工具；涉密项目改用可本地部署的方案，或只发送脱敏片段。

第 1 步：建分支，留好退路

批量改注释属于「改动面大、风险低但难 review」的操作，先开分支并记录起点：

```bash

git checkout -b docs/ai-comments

git rev-parse HEAD > .docs-baseline.txt

```

之后任何时刻都能用下面这条命令看到总改动规模：

```bash

git diff "$(cat .docs-baseline.txt)" --stat

```

第 2 步：先让 AI 读，不急着写

老项目的核心问题是「没人知道哪个文件管什么」。这一步只产出地图，不碰任何文件。把下面的提示词粘进工具：

```text

你是代码库分析助手。请只读不改，扫描当前仓库，输出 Markdown 表格：

要求：

1. 只根据实际代码内容判断，不确定的写“不确定”，不要猜测。

2. 每个结论附依据的行号范围，格式 file.py:12-40。

3. 不要修改任何文件。

```

产出大致长这样：

```markdown

```

把结果存成 docs/repo-map.md。后面所有注释和文档都以它为基础，同时它也是新同事的入职材料。

第 3 步：写下项目的注释规范

AI 不知道你团队的偏好，会把「i 加一」这种废话写满全屏。在仓库根目录放一份 CONVENTIONS.md，每次调用工具时作为上下文带上：

```markdown

注释与文档规范

函数 docstring（Google 风格）

• 必须包含：一句话摘要、Args、Returns、Raises
• Args 中每个参数写类型与含义
• 业务规则写在 Notes 里，例如“满 300 减 50 仅限自营商品”

注释原则

• 解释“为什么”，不复述“做了什么”
• 反例：# 给 count 加 1
• 正例：# 补偿历史订单的重复计数，见 issue #421
• 不写没有负责人和日期的 TODO

禁止

• 不修改任何代码逻辑
• 不编造不存在的参数、返回值、异常

```

这份文件写一次，后续所有步骤复用，也方便交给同事。

第 4 步：单文件试点

先挑一个 200 行以内、逻辑独立的文件。提示词：

```text

按照仓库根目录 CONVENTIONS.md 的规范，为 src/order/settle.py 中所有公开函数补全 docstring 和必要的行内注释。

约束：

• 只添加注释与 docstring，不改动任何可执行代码字符。
• Args / Returns 必须与函数体实际使用一致；无法确认的标注“待确认”。
• 输出 unified diff，不要输出整个文件。

```

返回的改动大致是这样：

```python

def apply_discount(amount: int, user_level: int) -> int:

"""按用户等级计算折后金额。

Args:

amount: 订单原始金额，单位分。

user_level: 用户等级，1 为普通用户，2 及以上参与折扣。

Returns:

折后金额，单位分，不会小于 0。

Notes:

折扣规则来自运营配置表，调整前先核对配置。

"""

if user_level < 2:

return amount

return max(amount - 5000, 0)

```

这里有个必须人工确认的点：amount 的单位是分还是元？AI 只能从代码里推断，这类业务约定要你来补。改完立刻提交：

```bash

git add -A && git commit -m "docs: annotate settle.py"

```

第 5 步：按批处理，小步提交

不要一次性让 AI 改上百个文件，diff 会大到没法审。按目录或每批 5~10 个文件推进。若工具提供命令行接口（参数以官方文档当前版本为准），可以写个循环骨架：

```bash

#!/usr/bin/env bash

set -euo pipefail

files=$(find src -name '*.py' ! -path '*/tests/*' ! -path '*/migrations/*' | sort)

i=0

for f in $files; do

echo "==> $f"

替换为所选工具的实际命令

ai-code annotate --prompt-file prompts/annotate.md "$f"

i=$((i+1))

if [ $((i % 8)) -eq 0 ]; then

git add -A

git commit -m "docs: annotate batch $i"

fi

done

git add -A

git commit -m "docs: annotate remaining files" || true

```

ai-code annotate 是占位名，换成实际工具的命令即可。关键是每批都能单独回滚、单独 review。

第 6 步：汇总成对外文档

有了仓库地图和各模块 docstring，再让 AI 汇总成人看的文档：

```text

基于 docs/repo-map.md 和各模块 docstring，生成 README.md 与 docs/ARCHITECTURE.md。

README 需要：项目做什么、目录结构、本地启动步骤、常见任务（跑测试、跑 lint）。

ARCHITECTURE 需要：模块依赖图（Mermaid）、数据流向、每个模块职责与关键入口函数。

要求：只使用仓库中真实存在的信息；启动命令必须能在脚本或配置里找到依据，找不到就写“待补充”。

```

架构图通常会被生成成这样：

```mermaid

graph LR

API[api/] --> Service[service/]

Service --> Repo[repository/]

Repo --> DB[(数据库)]

```

图必须人工核对方向。AI 容易把调用关系画反，用 grep -r "from service" src 之类的命令抽查几处 import 就能发现。

第 7 步：提交前的校验清单

1. 逻辑零改动。用 diff 过滤，只允许注释行变化：

```bash

git diff -U0 | grep -E '^[+-]' | grep -vE '^(\+\+\+|---)' \

| grep -vE '^[+-]\s*(#|"""|//|/\*|\*)'

```

这条命令还有输出，就说明动到了代码行，回退重做。

2. 事实核对。随机抽 10 条 docstring，对照函数体检查参数、返回值、异常。常见错误是 AI 补了一个代码根本不会抛出的 Raises: ValueError。

3. 术语统一。「订单」和「单子」不要混用，同一个概念在日本项目里尤其容易写乱。

4. 敏感信息扫描：

```bash

grep -rniE '(password|secret|token|10\.[0-9]+\.)' src docs || true

```

5. lint 通过：

```bash

ruff check src

```

常见坑与排错

坑 1：注释复述代码。 i += 1 # i 加一 对读者没有价值。修法是在 CONVENTIONS.md 里给正反例，并在提示词中加一句「每条注释必须包含代码本身看不出的信息，否则不要写」。

坑 2：编造参数与返回值。 老项目常有 **kwargs 或返回多种类型的情况。要求 AI 对不确定处写「待确认」，然后人工补齐，不要让它猜。

坑 3：docstring 风格与既有代码冲突。 有的仓库用 Google 风格，有的用 NumPy 或 reStructuredText。先统计现有 docstring 哪种居多，写进规范文件，避免一半一半。

坑 4：上下文超限导致文件被截断。 大文件处理到一半停下，docstring 只写了一半。按函数或类切块，或只对公开接口（不带下划线的函数）生成文档。

坑 5：AI 顺手重构代码。 例如把 for 循环改成推导式、顺手改变量名。提示词里写明「只改注释」，提交前跑第 7 步的过滤命令兜底。

坑 6：换行符变化淹没真实改动。 跨平台协作的仓库容易整文件显示为改动。设置 git config core.autocrlf input，并在 .gitattributes 中固定文本文件行尾。

坑 7：私有代码外发。 先读清楚所选工具的数据使用条款；涉密项目用可本地部署的方案，或只发送脱敏片段。

坑 8：文档写完就过期。 只在这次生成、之后不管，半年后又是一堆错误信息。把「改动模块时同步更新对应文档片段」写进 PR 模板。

下一步建议

• 把规范接入 CI：在 PR 模板里加一条「新增公开函数必须有 docstring」，或用 lint 规则强制。
• 让文档跟着代码走：每次改动只重新生成受影响模块的文档片段，而不是全量重跑。
• 把 docs/repo-map.md 当成入职材料：新同事入职时先读它，比直接翻代码省时间。
• 定期抽查：每月抽几个模块，人工核对 docstring 与实现是否仍然一致。
• 清理存量「待确认」标记：那些地方往往藏着还没搞清楚的业务规则，值得单独开一次讨论。