注释是代码生成的结构锚点，需提前用三段式docstring定义契约；补全旧代码时可反向驱动重构；跨文件协作需求可通过类注释触发关联代码生成。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
当你在CodeBuddy中输入“生成一个用户登录校验函数”却得到一个缺少密码强度检查、未处理空参数、也未标注返回值含义的函数时，问题往往不在于模型能力，而在于你没让注释成为生成过程的“结构锚点”。注释不是事后补上的装饰，而是提前写进代码骨架里的意图说明书——它告诉AI：这里必须做什么、不能做什么、输出要满足什么契约。
用注释定义函数契约再触发生成
这一步操作起来很简单，直接把函数签名和文档字符串写好再唤起CodeBuddy。
1、在Python文件中手动写出带完整docstring的函数框架，例如：
def validate_user_login(username: str, password: str) -> dict:<br> """校验用户名密码是否合法<br> Args:<br> username: 非空字符串，长度3-20，仅含字母数字下划线<br> password: 至少8位，含大小写字母+数字+特殊字符<br> Returns:<br> dict: {"success": bool, "message": str, "user_id": int or None}<br> Raises:<br> ValueError: 当任一参数格式非法时<br> """<br> pass
2、将光标置于pass行，按下Ctrl+Enter（Windows/Linux）或Cmd+Enter（macOS）触发CodeBuddy补全。
3、AI会严格按docstring中声明的参数约束、返回结构、异常类型生成实现逻辑，不会擅自添加额外字段或忽略校验分支。【关键前提：docstring必须包含Args/Returns/Raises三段式结构，缺一则生成结果可能跳过对应逻辑】
用已有注释反向驱动代码重构
适用于已存在但注释不全的旧代码，让AI基于现有注释推断缺失行为并补全。
方法一：选中带部分注释的函数→右键→【腾讯云代码助手 > 补全注释并同步逻辑】
CodeBuddy Code CLI 的安装、配置与使用指南。CodeBuddy Code 是腾讯推出的 AI 驱动 CLI 编程助手，支持自然语言驱动开发。 - 必备触发词：CodeBuddy, codebuddy, AI CLI, Tencent AI coding, @tencent-ai/codebuddy-code, terminal AI assistant - 适用场景：安装 CodeBuddy CLI、配置 CodeBuddy、使用 CodeBuddy 命令、排查 CodeBuddy 问题
方法二：在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无法读取其注释内容。
