软件工程

一、理解AI编程中的“幻觉”：定义、成因与典型表现 当Copilot为你补全一行 user.save() 后，你顺手提交了PR——但代码实际调用了 User.objects.create_user()，而 save() 方法在当前模型中已被重写为仅允许管理员调用。CI通过了，测试也绿了，直到上线后用户注册流程静默失败。这不是Bug，是AI幻觉（Hallucination）：模型生成了语法正确、上下文连贯、甚至能通过基础静态检查的代码，但其语义与真实系统契约严重偏离。 在AI编程语境下，幻觉 ≠ 随机错误，而是大语言模型基于概率分布进行自回归生成时，因训练数据偏差、注意力机制局限或上下文压缩失真所导致的结构性语义失准。它不满足“错误可归因于拼写/语法”，而是表现为： 非事实性输出：虚构不存在的API（如 pandas.DataFrame.dropna(threshold='all')，实际参数应为 thresh） 逻辑自洽但语义错误：生成看似合理的链式调用 df.groupby('x').apply(lambda x: x.sum()).reset_index()，却忽略 apply 返回结构与 reset_index() 的兼容性约束 上下文误推：根据注释 # Get active users from last 7 days 生成 User.objects.filter(last_login__gte=timezone.now() - timedelta(days=7))，却漏掉 is_active=True 关键条件 这与传统静态分析工具（如Bandit、Semgrep）有本质区别：LLM不验证契约，只拟合模式；而静态工具基于确定性规则遍历AST。前者是“以假乱真”的创作，后者是“按图索骥”的审查。 我们来看一个真实GitHub PR评论片段（脱敏）： “@ai-assistant generated this handler, but request.auth is None in our JWT setup — it should read from request.user. Also, serializer.is_valid(raise_exception=True) is missing before .save().” 对应 diff 对比如下： # AI生成版本 def create_order(request): serializer = OrderSerializer(data=request.data) order = serializer.save() # ❌ 缺少验证，且 request.auth 不存在 return Response({"id": order.id}) # 正确实现 def create_order(request): serializer = OrderSerializer(data=request.data) serializer.is_valid(raise_exception=True) # ✅ 强制验证 order = serializer.save(user=request.user) # ✅ 使用 request.user 而非 auth return Response({"id": order.id}) 关键洞察：幻觉常发生在抽象层跃迁点（如框架约定、权限模型、ORM行为），而非基础语法。检测它，不能靠“更聪明的模型”，而要靠多层确定性校验。 ...

引言：为什么精准提问对Claude Code至关重要 Claude 3.5 Sonnet（尤其是Opus）在代码理解任务中展现出显著超越通用大模型的能力：它在HumanEval-X、CodeContests和SWE-Bench等专业基准上达到SOTA级表现，关键在于其深度训练于真实GitHub仓库+编译器级AST解析数据，能准确识别控制流边界、变量生命周期、隐式类型传播与跨函数副作用。但这一优势有个前提——Claude不“猜”你的意图；它严格遵循Prompt中定义的语义契约。模糊提问不是“不够好”，而是直接触发模型的安全退避机制：当上下文不足时，它宁可输出谨慎的泛泛而谈，也不愿给出错误断言。 来看一个真实对比案例： 一段处理用户邮箱验证的Python函数（简化版）： def validate_email(s): if not s: return False parts = s.split("@") if len(parts) != 2: return False local, domain = parts return "." in domain and local.isalnum() ❌ 模糊Prompt：“修一下这个bug” → Claude响应：“可能存在空字符串或None输入导致split()报错……建议添加类型检查”（未定位行号，未指出local.isalnum()对含下划线邮箱（如[email protected]）返回False的真实缺陷） ✅ 结构化Prompt： 你是一位专注Django表单验证的Python SRE，熟悉PEP 484和mypy 1.10+。请分析以下函数：① 指出第7行local.isalnum()在何种合法邮箱输入下返回False（举例说明）；② 给出单行修复代码（保持函数签名不变）；③ 输出必须为：|问题行|输入示例|修复代码| → Claude精准响应： 问题行 输入示例 修复代码 7 "[email protected]" return "." in domain and re.match(r'^[a-zA-Z0-9._%+-]+$', local) is not None 这并非模板魔法，而是人机协同的语义契约：你定义“什么是正确答案”，Claude负责在约束内穷尽推理。Prompt Engineering的本质，是把开发者脑中的隐性知识，显性编码为Claude可执行的指令集。 第一步：解构你的代码理解需求——明确任务类型与边界 别再用“解释/优化/修bug”这类动词启动Prompt。Claude需要的是可判定的任务类型。我们将其归为4类原子任务，每类对应唯一输入输出契约： 任务类型 输入约束 输出约束 典型失效反例 代码解释 必须指定目标粒度（函数/AST节点/字节码） 禁止主观评价，只输出可观测事实（如“L5: ast.Call → requests.get”） 将“添加日志”混入解释Prompt → Claude开始写logging代码 缺陷诊断 必须提供失败现象（报错信息/异常堆栈/测试用例） 必须定位到具体行号+变量名+传播路径 只说“性能差” → Claude分析算法复杂度而非找热点行 重构建议 必须声明约束条件（时间/空间复杂度、兼容性、架构风格） 禁止引入新依赖/新范式（如async） 要求“优化JSON序列化”，未禁用ujson → Claude推荐非标准库 生成补全 必须提供完整上下文（前缀+后缀+接口契约） 输出必须是语法合法、可直接插入的代码块 给半截函数体，要求“补全逻辑” → Claude发明不存在的参数 ✅ 决策树检查表（快速归类）： ...

引子：PRD失效的三个真实现场 上周五的某电商中台需求评审会上，一位资深后端工程师第三次打断产品经理：“这个‘智能退款建议按钮’点击后，到底触发哪5个系统？库存扣减在风控校验前还是后？支付网关回调失败时，重试逻辑写在哪一版PRD里？”会议室陷入沉默——那份87页的PRD文档，通篇用“用户可获得更优退款方案”“系统自动决策”等模糊表述，却未定义任何一个状态跃迁条件。 测试同学的反馈更直白：“第3.2.4节说‘支持异常场景处理’，但没写具体有哪些异常、各走哪条路径、预期返回码是多少。我按什么写用例？按你口头说的，还是按上次上线崩掉的版本？” 最棘手的是AI Agent项目。当客服Agent上线首周，用户一句“我刚在APP投诉完，现在想加急处理，但又不想重复描述”，系统竟启动了全新对话分支——而原PRD里连“跨会话状态继承”四个字都没出现。传统PRD的线性功能罗列范式，在面对多智能体协同、状态驱动、实时反馈闭环的AI原生产品时，已不是“不够好”，而是结构性失能。 我们亟需一种新抽象：它不描述“系统应该做什么”，而是定义“系统如何协作着把事情做成”。这个新载体，就是编排图（Orchestration Graph）——一张可执行、可追踪、可验证的状态流转拓扑图。 为什么是“编排图”？从Prompt工程视角解构需求本质 PRD本质是面向人类读者的指令集：模块化、静态、依赖上下文理解。而编排图是面向LLM+Agent系统的领域特定语言（DSL）：角色化、状态化、路由驱动。 维度 传统PRD 智能体编排图 核心单元 功能模块（如“投诉提交页”） 角色节点（CustomerServiceAgent） 行为定义 输入→处理→输出（文字描述） 能力接口（.invoke()方法 + tool schema） 流程逻辑 “若A则B，否则C”（自然语言条件句） 带guard函数的有向边（lambda s: "vip" in s.tags） 状态管理 隐含在字段说明中（如“status字段取值为pending/processing”） 显式State Schema（Pydantic模型定义全生命周期字段） 以“用户投诉处理流程”为例： PRD写法（4行文字）： 用户提交投诉，系统校验基础信息； 若为VIP客户，优先分配高级坐席； 若含“欺诈”关键词，同步触发合规审查； 审查通过后进入赔付流程。 编排图表达（3节点+2条件边）： graph LR A[CustomerServiceAgent] -->|guard: “vip” in state.tags| B[SeniorAgent] A -->|guard: “fraud” in state.keywords| C[ComplianceChecker] 关键洞察：PRD是“告诉人怎么做”，编排图是“告诉机器何时调谁、传什么、判什么”。 每个节点的system prompt必须显式约束其职责边界（如Router节点的prompt强制声明：“仅当state.urgency==‘critical’且无可用坐席时，才调用EscalateToManager工具”），这正是Prompt工程对需求颗粒度的倒逼。 实战：用LangGraph构建可执行的编排图（含完整代码） 以下为可直接运行的最小可行示例（Python 3.10+, langgraph==0.1.44）： from typing import TypedDict, Annotated, List, Optional from langgraph.graph import StateGraph, START, END from langgraph.checkpoint.memory import MemorySaver from pydantic import BaseModel # 1. 定义状态Schema（显式契约） class ComplaintState(TypedDict): text: str tags: List[str] # e.g., ["vip", "urgent"] keywords: List[str] assigned_to: Optional[str] escalation_needed: bool # 2. 定义智能体（每个即一个可调用节点） class CustomerServiceAgent: def __call__(self, state: ComplaintState) -> ComplaintState: # 简化版：提取关键词和标签（真实场景调用LLM） state["keywords"] = ["fraud"] if "欺诈" in state["text"] else [] state["tags"] = ["vip"] if "VIP" in state["text"] else [] return state class ComplianceChecker: def __call__(self, state: ComplaintState) -> ComplaintState: # 合规检查逻辑（此处模拟通过） print("✅ 合规检查通过") return state class EscalationRouter: def __call__(self, state: ComplaintState) -> ComplaintState: # Router节点不修改状态，只做路由决策（实际中可调用LLM判断） if "urgent" in state["tags"] and "vip" in state["tags"]: state["escalation_needed"] = True return state # 3. 构建编排图 builder = StateGraph(ComplaintState) builder.add_node("service", CustomerServiceAgent()) builder.add_node("compliance", ComplianceChecker()) builder.add_node("router", EscalationRouter()) # 4. 添加带条件的边（核心！业务规则即代码） builder.add_edge(START, "service") builder.add_conditional_edges( "service", lambda s: "fraud" in s["keywords"], {True: "compliance", False: "router"} ) builder.add_conditional_edges( "router", lambda s: s.get("escalation_needed", False), {True: END, False: "service"} # 非紧急则循环服务 ) # 5. 编译并运行 graph = builder.compile(checkpointer=MemorySaver()) result = graph.invoke({ "text": "VIP用户投诉支付欺诈，要求15分钟内处理！", "tags": [], "keywords": [], "assigned_to": None, "escalation_needed": False }, config={"configurable": {"thread_id": "1"}}) print("最终状态:", result) # 输出: {'text': '...', 'tags': ['vip'], 'keywords': ['fraud'], ...} ✅ Prompt设计意图注释：EscalationRouter节点的system prompt应包含明确约束： “你是一个路由决策器。仅当state.tags包含’urgent’且’vip’时，设置escalation_needed=True；其他情况一律返回原state。禁止生成解释性文本。” 这确保LLM不会“自由发挥”，而是严格服从图结构。 ...