收益：
- 能够根据目标受众和 AI 来源生成自述文件、文档字符串和变更日志草稿
- 能够将文档中的“内容/如何”和“原因”层分开，并以人类身份添加“原因”
- 通过亲自运行安装步骤并将文档作为代码更改的一部分来验证安装步骤
软件中最常被忽视但最持久的部分是文档。即使几个月后，代码仍然可读；写它的人已经不在了，上下文也被遗忘了，只剩下所写的内容。一个好的README（解释项目是什么以及如何安装和运行它的介绍性文档）、解释性代码注释和最新的API文档（解释如何使用接口的参考）直接决定了团队的速度。人工智能消除了文档中的大量“写作疲劳”——但它也带来了一个陷阱：人工智能可以从代码中推断出它的作用，但通常不知道为什么要这样做。
在本单元中，您将学习如何使用 AI 生成 README、代码注释、文档字符串（每个函数/类编写的注释块）、API 文档和变更日志；以及如何人性化地保存文档中最有价值的部分：“为什么”。
“什么”和“为什么”的区别
有两层文档。第一个是内容/方式：“此函数对列表进行排序”，“运行此命令进行安装”。这些可以从代码和结构中提取出来；人工智能在这里表现出色。其次，为什么：“为什么我们让这个服务异步而不是同步”，“为什么这个限制值为 30 秒”，“为什么我们选择这个库而不是另一个”。这些都没有写在代码里；它是设计决策、约束和过去痛苦的产物。
人工智能不知道“为什么”；充其量，它只是做出一个合理的猜测——这是危险的，因为错误的理由比没有理由更糟糕。因此，分工很明确：人工智能起草“什么/如何”，你添加“为什么”。最有价值的注释是那些说出了代码不能说的内容的注释。
提示：不要用注释重复代码本身明确说明的内容（例如 i = i + 1 // 将 i 加一）。人工智能有时会产生这种多余的评论；消除它们并将精力投入到“为什么”评论上。
一步一步：使用 AI 生成文档
- 指定目标受众。 “一个刚刚起步的开发人员”、“将使用这个 API 的外部团队”、“未来的我”——观众为语言和深度定下了基调。
- 给出来源。将相关代码、现有 README、示例用法添加到提示中。无来源的文件是伪造的邀请。
- 拼版结构。自述文件的标准部分（目的、安装、使用、配置、贡献）、文档字符串的项目格式。
- 标记“为什么”空格。要求人工智能将其不知道理由的决策标记为“此处需要‘为什么’注释”；然后你填写这些空白。
- 核实。实际运行安装步骤；尝试示例代码。不起作用的自述文件比根本没有自述文件更糟糕。
三个迷你箱
案例 1 — 自述文件加速入职。缺少开源工具的自述文件；新贡献者平均需要花费 2 个小时来完成安装。该团队将安装脚本和 package.json 提供给 AI 并起草了一份结构化的自述文件，然后在干净的机器上运行这些步骤并添加了两个缺少的依赖项。后续贡献者的平均安装时间减少到 25 分钟。
案例 2——编造的“为什么”陷阱。一位开发人员要求 AI 在超时值（timeout=30）旁边提供注释。 AI写了一个合理但不正确的理由“容忍高网络延迟”；真正的原因是下游服务的合同 30 秒限制。这种误解导致后来的开发商不必要地提高了价值，从而引发了事件。教训：代码所有者必须验证合理性。
案例 3 — Docstring 标准已实现自动化。具有 40 个函数的辅助模块没有文档字符串。 AI 被赋予项目格式（Google 风格）并为每个函数生成参数、返回和异常描述；开发人员审查了这些并修复了一些不正确的类型声明。记录 40 个函数的时间从大约半天减少到一个小时。
四个可复制模板
结构化自述文件草案：
目标受众：{{例如新贡献者}}。根据以下文件编写自述文件草案。部分：目的、功能、要求、安装、操作、配置、测试、贡献。从实际文件中提取安装/运行命令；配件。用“[验证]”标记您不确定的地方。来源：{{package.json/脚本/示例代码}}
文档字符串/API 参考：
以 {{project style: Google/NumPy/JSDoc}} 格式将文档字符串写入这些函数：简短摘要、参数（类型 + 含义）、返回、引发的异常、1 个简短示例。不要重复代码明确说明的内容。将需要“为什么”的设计决策标记为“[为什么需要]”，不要编写捏造的理由。{{code}}
删除“为什么”注释的空格：
在这段代码中，下一个开发人员可能会问“为什么会这样？” （神奇的数字、不寻常的决定、解决方法）。为每个问题给出一条评论“骨架”，但将基本原理留空；我会填写理由。{{code}}
变更日志/公关声明：
从下面的 diff 中编写一个 {{changelog 条目/PR 描述}}。格式：更改内容（以用户语言）、原因（问题：{{...}}）、重大更改（如果有）、是否经过测试。调整技术术语以适应目标受众。{{diff}}
弱提示/强提示
弱：“为这个项目写一个自述文件。”
Strong：“目标受众：第一次克隆此存储库的开发人员。根据附加的 package.json、docker-compose.yml 和 script/ 文件夹，编写一份 README 草稿，其中包含目的、要求、安装、操作、测试、贡献部分。从这些文件中提取命令，不要编造它们；用 [VERIFY] 标记任何您不确定的地方。”
强版本给出了受众、来源、结构以及“制作它、标记它”的规则；使文件以真实档案为依据，需要核实的地方清晰可见。
文件类型
人工智能做得很好
人工添加/验证
自述文件安装
步骤大纲
运行步骤并确认
文档字符串/API
结构、参数、类型
正确的类型和“为什么”
代码注释
“他在做什么”摘要
“这是为什么”的理由
变更日志/公关
初稿
影响力和准确性
架构决策 (ADR)
骨架
真正的决定和妥协
文档需要维护
文件最危险的方面是，即使它是假的，但它看起来却是真的。当代码发生变化而文档没有更新时，它会主动误导读者。人工智能使更新变得容易：发出差异并询问“此更改会影响文档的哪些部分？”你可能会问。但这是确保最新性的过程——使文档更新成为代码更改的一部分（PR 的接受标准）。人工智能加速发展；团队建立纪律。
注意：未经验证自述文件中的安装步骤，请勿发布。一份“可能有效”的文档可能会毁掉新开发人员的第一天并削弱信任。在干净的环境中自行运行这些步骤。
常见错误
- 找出适合人工智能的“原因”。错误的辩护比没有辩护更糟糕；代码所有者应该写下设计原因。
- 不验证安装步骤。不起作用的自述文件会破坏信任。
- 不必要的注释重复代码。它会产生噪音，模糊真正的“为什么”解释。
- 没有指定目标受众。一份不清楚是写给谁的文档对于新手或专家来说都是没有用的。
- 将更新与过程分开。如果文档没有使用代码进行更新，它很快就会产生误导。
综上所述
人工智能消除了文档中的大部分机械负担：快速草稿自述文件、文档字符串、API 参考、变更日志和 PR 描述。但它无法知道“为什么”，这是最有价值的一层，而弥补它是危险的。分工很明确：人工智能生产“什么/如何”，你添加“为什么”。指定受众、提供资源、强加结构、标记适合的位置，并通过亲自运行来验证每个安装步骤。使文档成为代码更改的一个组成部分。
应用任务
选择文档丢失或过时的模块或小项目。首先使用“结构化自述文件草案”（或文档字符串）模板从 AI 生成大纲；一定要给出来源和目标受众。然后检查人工智能标记为[验证]或[为什么需要]的每个点：实际运行设置步骤并用您自己的知识填写设计“原因”。请注意需要修复多少步骤以及您添加了多少“为什么”。
清单
- [ ] 在文档中，我区分了“什么/如何”和“为什么”层。
- [ ] 我不让AI编造“为什么”，我自己添加。
- [ ] 我给出目标受众和实际源文件的提示。
- [ ] 我通过亲自执行来验证AI标记的[VERIFY]点。
- [ ] 我删除了重复代码的不必要的注释。
- [ ] 我正在将文档更新作为代码更改的一部分。