写文档和补注释是维护成本最高的工作之一，却直接影响代码的可交接性。Cursor 可以将代码逻辑反向输出为自然语言，帮助你在编码流中快速补齐注释，也能基于项目结构生成对外文档的初稿。
1. 函数与代码块注释
选中需要补充注释的函数或类，按 Ctrl/Cmd + K（行内编辑），直接输入：
- "添加 JSDoc 注释"
- "生成 Python Docstring"
- "给这个接口加上中文注释，说明每个参数的业务含义"
Cursor 会自动识别参数类型、返回值和异常抛出情况，在代码上方插入符合语言规范的注释模板。如果该函数已有部分注释，AI 会保持原有风格进行补全或修正，而不是完全覆盖。
2. 批量规范注释
对于整个文件甚至多文件的注释缺失，可以在侧边栏（Ctrl/Cmd + L）中使用 @文件 引用目标文件，然后指示：
"为文件中所有公开方法补充标准注释，遵循 Google JavaScript Style Guide。"
Cursor 会逐条生成改动并展示 diff，你可以逐段审阅和采纳。这种方式比手动复制粘贴更安全，也便于在 Code Review 时统一确认。
3. 模块与项目级文档
- 文件头说明：在文件开头按
Ctrl/Cmd + K，输入"添加模块说明：该文件负责用户鉴权中间件"，AI 会生成简洁的文件头注释。 - README 初稿：在侧边栏中 @代码库 或 @package.json，指令如："根据项目结构和入口逻辑，生成一份 README 初稿，包含安装步骤和主要脚本说明。" Cursor 会梳理目录层级，提取依赖信息和入口文件，输出可直接预览的 Markdown。
- API 文档：选中路由定义或 Controller 层，要求"生成接口文档，包含请求方法、路径、参数和响应示例"，可直接得到接近 Swagger 描述的格式，稍加调整即可同步到团队协作平台。
4. 实用技巧
- 统一风格：在提示词中指定注释规范（如 JSDoc、TSDoc、reStructuredText），Cursor 会尽量保持整份文件风格一致。如果团队已有
.cursorrules或外部文档定义了注释模板，可通过 @文档 引入，让 AI 自动遵循。 - 中英文选择：面向国际开源的代码可明确指令"用英文编写注释"；内部项目则直接要求中文，减少后续翻译成本。
- 从注释反向校验代码：如果 AI 生成的注释读起来与代码逻辑矛盾，往往是代码本身存在隐患或变量命名不清，可借机审查并优化代码质量。
5. 局限与建议
AI 生成的注释通常能准确描述"这段代码做了什么"，但容易遗漏"为什么要这么做"的业务背景。建议在 AI 生成的基础上，手动补充设计意图、边界条件和待办事项（TODO）。
此外，生成项目级文档（如 README、API 文档）时，务必核对其中提到的文件路径、命令和版本号是否与当前仓库一致——AI 偶尔会基于训练数据中的常见模式进行推测，可能与你的实际项目结构不符，需要人工二次校准。