想让Gemini生成的脚本注释既清晰可读，又具备工程实用性，不能只停留在“简单解释代码”的层面。基于实战经验，我们必须从注释目的、读者角色、上下文粒度三个维度逐步优化提示词。下面直接提供干货，详细说明每个版本的具体写法。

基础版：让Gemini明确“这是注释任务”

第一步，在提示词开头清晰说明指令类型，避免模型默认输出完整脚本。【必须包含“只添加注释，不修改或重写代码”】。这不是可选项，而是区分“生成注释”与“生成脚本”的关键约束。

第二步，提供待注释的代码片段，用```python```等代码块包裹，确保语法结构完整。很多时候模型输出杂乱，正是因为输入的代码本身不规范。

第三步，加上一条约束：“每行代码上方或右侧添加中文注释，用#开头，不新增空行。”这条看似简单，却能直接解决注释排版混乱的常见问题。

实用进阶版：控制注释深度并明确读者视角

方法一：按读者经验层级设定提示
为新手编写的注释，核心是解释“为什么这样写”；为维护者编写的注释，则需强调“修改此处会影响哪些模块”。例如，你可以这样写：“假设阅读者是刚接手项目的Python中级开发者，请说明该函数为何使用try/except而非if判断，并解释except中logging.error()的level选择依据。”你会发现，一旦设定清晰的读者画像，注释的深度和针对性会立刻提升。

方法二：绑定上下文锚点
在提示词中直接引用代码中的变量名、函数名或错误码，强制注释具象化。比如：“请为check_user_status()函数内的status_code == 403这一判断添加注释，说明它对应OAuth2.0规范中的哪条授权拒绝场景。”这样生成的注释不再泛泛而谈，而是精准对应业务逻辑。

【关键约束】若代码包含硬编码值（如API超时设为3000），注释必须解释该数值的业务来源，不能只写“超时时间”。很多团队踩过的坑正是硬编码数字缺乏解释，导致后续维护时无人敢修改。

工程强化版：嵌入团队规范与可维护性要求

第一步，声明注释风格标准。
“遵循Google Python Style Guide第3.8节注释规范，函数级注释必须包含Args、Returns、Raises三段，且Args需注明参数是否可为None。”这不仅是风格统一的问题，还直接决定注释在代码评审中是否达标。

第二步，注入变更敏感点提示。
“识别出代码中调用外部API的行，在其注释中标明：①该API当前SLA承诺的P95延迟；②若超时触发降级逻辑，降级返回值在哪个模块定义。”这种级别的注释，能帮助团队在出现故障时快速定位影响范围。

第三步，设置注释自检条件。
“检查所有for循环，若循环体超过4行或包含嵌套if，必须在循环开始前用# TODO: 注释说明该循环的核心业务意图（不超过15字），例如：# TODO: 合并跨区域库存”。这个自检机制，正是防止注释流于形式的关键步骤。