Copilot旧代码整理文档:提示词减少来回改稿

先说几个核心判断。不少工程团队在用Microsoft Copilot把遗留代码生成技术文档时，反复调整提示词却效率低下的原因，不在工具本身，而在于初始提示词没有锁定关键信息结构和输出边界。

明确文档受众再拟提示词

动笔前先厘清：这份文档的读者是谁？是给新人快速理解业务逻辑，还是给QA核对分支覆盖率，或是给产品经理确认功能边界？不同受众决定了提示词里应突出哪些信息。比如，面向运维团队，需重点突出异常处理路径与外部服务依赖；如果是前端开发，则必须明确API入参格式与状态码含义。

没想清楚这个问题就写提示词，Copilot往往输出类似“该模块负责处理用户请求”这种空泛的废话。结果就是后续要靠人工逐句删除，反而更费时。

三段式模板固定提示词框架

方法一：角色+任务+约束

一种稳妥的写法是：明确告知Copilot其扮演的角色、需完成的任务、硬性约束条件。举例如下——

“请以资深后端开发工程师的身份，将以下Python函数转化为技术说明文档。要求：①开头用一句话概括函数核心职责；②参数列表必须标注类型、是否必填、示例值；③用「正常流程」「异常分支」两个小标题分述执行逻辑；④禁止出现‘可能’‘通常’等模糊表述；⑤输出纯Markdown，不加解释性内容。”

方法二：输入-输出对照表驱动

另一种方式直接定义输入与输出的解析格式，让Copilot像填空一样工作：

“请严格按以下格式解析代码：
【输入】列出所有入参名+类型+业务含义；
【处理】用带编号的步骤描述主干逻辑（每步不超过15字）；
【输出】说明返回值结构+各字段含义+典型错误码。不得补充任何代码外的信息。”

这里有一个现实问题——Copilot对模糊指令的容忍度极低。如果不在提示词里明确写上“禁止出现‘可能’”，它大概率会默认加入推测性描述，而这些推测常偏离代码实际行为。

喂代码前必须做两件事

第一步：删掉无关注释和调试用的print语句。Copilot缺乏判断力，会把“# TODO: 优化缓存”当作待办事项写进文档，也会把“print(‘debug’, x)”误判为关键日志行为。因此，给Copilot的代码越“干净”越好。

第二步：把函数签名单独提炼出来，放在代码块最上方。比如：def calculate_discount(user_id: str, order_amount: float, coupon_code: Optional[str] = None) -> Dict[str, Any]:。Copilot优先抓取第一行内容，若函数签名缺失，参数类型和返回结构几乎必定出错。

第三步：如果函数内部调用了某些工具函数，而这些函数的源码未提供，必须在提示词末尾追加一句：“若遇到未提供实现的函数调用，请标注‘[需查阅XXX模块]’并停止展开。”否则Copilot会自行脑补缺失逻辑，甚至凭空生成不存在的实现。

说到底，Copilot是个好工具，但需要严格“驯化”。提示词中的每一条约束，都是为它划出的安全边界。边界越清晰，产出的文档就越接近你真正想要的样子。