先说几个核心判断：注释不是代码的附属品，而是生成过程中的“结构锚点”。你有没有注意到，当你在CodeBuddy里输入“生成一个用户登录校验函数”，得到的结果却缺少密码强度检查、空参数未被处理、返回值含义也含糊不清——问题往往不在模型能力，而在你根本没有让注释成为那根“牵引绳”。注释这件事，得提前布局，把它写进代码骨架中，清晰告诉AI：这里必须做什么、不能做什么、输出要满足什么契约。

用注释定义函数契约再触发生成

具体怎么操作？很简单。先手动写好函数签名和文档字符串，再唤起CodeBuddy进行AI代码生成。

第一步，在Python文件中编写一个带完整docstring的函数框架。例如：

def validate_user_login(username: str, password: str) -> dict:
    """
    校验用户名密码是否合法
    Args:
        username: 非空字符串，长度3-20，仅含字母数字下划线
        password: 至少8位，含大小写字母+数字+特殊字符
    Returns:
        dict: {"success": bool, "message": str, "user_id": int or None}
    Raises:
        ValueError: 当任一参数格式非法时
    """
    pass

第二步，光标停在pass那一行，按下Ctrl+Enter（Windows/Linux）或Cmd+Enter（macOS），触发CodeBuddy自动补全。

第三步，AI便会按照docstring中声明的参数约束、返回结构、异常类型来生成实现逻辑，不会擅自增加字段，也不会跳过校验分支。【关键前提：docstring里必须有Args/Returns/Raises这三段式结构，缺失任意一段，生成结果就可能忽略对应逻辑】

用已有注释反向驱动代码重构

那旧代码怎么办？适用于那些注释不全、但又不希望重写的场景。让AI基于现有的注释推断缺失的行为并进行补全。

方法一：选中带部分注释的函数，右键→【腾讯云代码助手 > 补全注释并同步逻辑】。

方法二：在Craft对话框里输入指令：/refine @cursor --with-docstring。这个指令会强制AI先解析当前函数上方的注释内容，再与实际代码体进行比对，自动补充遗漏的校验、日志记录、错误处理等环节。

举个例子：如果原有注释写的是“检查用户权限”，但代码里只做了角色判断，没有查询RBAC策略表，AI就会自动插入一个check_rbac_policy(user_id)调用，并添加相应的注释说明。

跨文件注释联动生成关联代码

当一个类的注释中明确提到“需与AuthManager协同完成令牌刷新”，CodeBuddy能自动识别这一依赖关系，并生成配套代码。此时，跨文件注释就成为关键。

第一步：打开UserService.py，确保类注释中包含这样一句关键描述：
"""提供用户生命周期管理。所有token操作必须委托AuthManager执行，禁止自行构造JWT。"""

第二步：在Craft模式下新建任务，勾选当前项目所有Python文件，输入指令：
根据UserService注释中关于AuthManager的协作要求，生成AuthManager类的完整实现，包含create_token、refresh_token、verify_token三个方法，每个方法上方必须有符合PEP257的docstring。

第三步：发送后等待生成。AI会自动创建auth_manager.py，并在每个方法的docstring里复用UserService.py原文中的“委托”“禁止自行构造”等约束词，确保语义一致。

再强调一次：生成前必须确保UserService.py已经保存，否则Craft无法读取其中的注释内容。这一步不能省略。