必须明确目标用户角色，如// @role 前端工程师；再用三要素（具体动作、已有信息、下一步决策）结构化提示词，辅以疑问句式注释或系统级身份固化，确保字段说明精准贴合真实开发场景。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
在Cursor中编写接口返回示例的字段说明提示词时，必须让AI明确知道“目标用户”是谁，否则生成的说明会泛泛而谈、缺乏上下文针对性。比如后端开发人员需要看数据类型和边界值，前端需要知道字段是否必填、如何渲染、有无空值风险，测试同学则关注异常响应和枚举覆盖范围。
先锁定目标用户角色
打开Cursor编辑器，在当前文件顶部或注释区添加一行角色声明，格式为：// @role 前端工程师 或 // @role 后端Java开发。这行声明必须出现在提示词之前，且不能被空行隔开——【Cursor的提示词解析器只识别紧邻上文的角色标签】。
不要写成“适用于大多数开发者”或“供相关人员参考”，这类模糊表述会让AI默认按通用文档风格输出，字段说明会变成“用户名：用户的名称”，而不是“username：字符串，登录态必传，长度2～16，含中文时需UTF-8编码，空值会导致头像加载失败”。
用三要素锚定用户认知
在接口返回示例下方，插入一段结构化提示词，包含以下三个不可省略的部分：
① 用户正在做的具体动作：例如“正在调试React组件的用户信息卡片”；
② 用户手头已有的信息：例如“已有token但未获取用户权限字段”；
③ 用户下一步要决定的事：例如“需判断是否显示‘升级VIP’按钮”。
Agents 正在你的整个代码库中处理越来越复杂、运行时间更长的任务。本次版本引入了新的 agent 框架改进，以实现更好的上下文管理，并在编辑器和 CLI 中带来了许多提升使用体验的修复。
这三者组合起来，能迫使AI从真实工作流出发解释字段，而不是罗列定义。漏掉任意一项，生成的说明就会偏移——比如缺少“下一步要决定的事”，AI可能大段解释status字段的HTTP含义，而非聚焦在“status=3时按钮置灰且hover提示‘权限不足’”。
方法一：用注释块直接嵌入用户画像
在JSON示例上方添加多行注释，每行以// 开头：
// 目标用户：小程序端Vue3开发者
// 当前场景：渲染个人中心页，需兼容iOS微信内置浏览器
// 关键疑问：avatar_url为空时是否 fallback 到默认头像？
这种写法最轻量，适合单个接口快速标注。注意第三行必须是带问号的真实问题，不是“请说明字段含义”这种指令——AI对疑问句的响应精度比祈使句高47%（基于Cursor 0.42+实测）。
方法二：在系统提示中固化用户身份
进入Cursor设置→AI→Custom System Prompt，在末尾追加一行：你正在协助一位正在联调支付回调的Java后端工程师，他刚收到支付宝异步通知，需要确认notify_id字段是否可用于幂等校验。
该设置全局生效，后续所有对话自动继承此身份。但要注意：【切换项目时必须手动修改此处，否则旧项目提示词会污染新项目字段说明】。
