代码块输出控制让AI生成可复制的代码你有没有过这种抓狂的体验让AI写一段代码它确实写出来了逻辑也对但你复制粘贴到编辑器后——缩进全乱了、注释全是废话、变量名毫无意义、缺少必要的import语句、还混着大段的解释文字。你花了10分钟让它生成代码又花了20分钟手动修代码才能跑起来。这不是AI的问题是你的提示词没有做代码块输出控制。今天我教你一套方法论让AI输出的代码真正做到复制粘贴就能跑。一、为什么代码块输出控制是一个独立话题1.1 代码与自然语言的本质差异 自然语言可以容忍模糊、容忍冗余、容忍不精确。但代码不行。代码是给机器执行的——少一个分号就报错多一个空格就逻辑偏移缩进层级差一个字符Python就直接罢工。这个本质差异带来了一个关键挑战AI擅长生成看起来对的代码但不容易生成直接能跑的代码。这中间差的就是你对代码块输出结构的精确控制。看起来对的代码 vs 直接能跑的代码 看起来对的代码 // 连接数据库 connect(db) // 查询用户 getUsers() // 返回结果 直接能跑的代码 import mysql.connector from config import DB_HOST, DB_USER, DB_PASS, DB_NAME def get_active_users(): 返回最近30天内有活动的用户列表 try: conn mysql.connector.connect( hostDB_HOST, userDB_USER, passwordDB_PASS, databaseDB_NAME ) cursor conn.cursor(dictionaryTrue) cursor.execute( SELECT id, username, email, last_login FROM users WHERE last_login DATE_SUB(NOW(), INTERVAL 30 DAY) AND status active ORDER BY last_login DESC ) return cursor.fetchall() except mysql.connector.Error as e: print(f数据库查询失败: {e}) return [] finally: if conn and conn.is_connected(): cursor.close() conn.close() 两组代码的差距一目了然。第一组是思路演示第二组是生产可用。而要让AI输出第二组而非第一组关键在于你的提示词设计。1.2 代码块输出的五个控制维度我把代码块输出控制分为五个核心维度维度控制内容典型问题结构完整性import、依赖、入口函数、异常处理AI遗漏必要的import导致代码无法运行格式正确性缩进、空白、换行、编码复制粘贴后缩进全乱可读性命名规范、注释质量、代码组织变量名是a/b/c/x1/x2可运行性依赖版本、环境要求、配置代码语法对但缺少环境说明安全性输入验证、注入防护、密钥管理AI生成含硬编码密码的代码二、代码块格式的基础控制2.1 指定语言标记⌨️ 最基础但最容易被忽视的一步——告诉AI用正确的Markdown代码块语言标记请用Python语言实现以下功能[功能描述] 输出格式要求 - 代码放在 python 代码块中 - 不要将多个小的代码片段分散在解释文字中集中放在一个代 码块中除非确实需要解释穿插⚠️ 为什么要明确指定python而不仅仅是代码块因为正确的语言标记能让Markdown渲染器正确高亮语法。没有语言标记的代码块大部分平台会显示为纯文本阅读体验和复制体验都会大打折扣。2.2 分离代码与解释这是一个高频问题AI在代码块中混入自然语言解释导致代码无法直接复制使用。问题示例python # 这里我们引入需要的库 import pandas as pd # 然后读取CSV文件 df pd.read_csv(data.csv) # 接下来过滤掉空值——这是数据清洗的第一步 df df.dropna() # 最后输出清洗后的行数 print(f清洗后剩余{len(df)}行)这个代码块中有大量的教程式注释。如果你的目的是教学这没问题但如果你的目的是直接用这些注释就是噪声。 **解决方案——分离指令**请将代码和注释分开输出【代码块】干净可执行的代码注释只保留必要的docstring和技术注释在这里放代码【代码说明】代码块之后单独列出不作为代码的一部分第X行的作用[解释]为什么选择这个实现方式[理由] 这个代码说明的双区结构是我最推荐的模式。代码区是干净的、可直接运行的说明区承载教学和解释功能。两个区域互不污染。 ### 2.3 多文件/多代码块的组织 当任务涉及多个文件时如何组织输出就变得很重要请为这个Flask应用生成完整的后端代码包含以下文件app.py主应用models.py数据库模型routes.py路由处理config.py配置文件requirements.txt依赖列表输出时每个文件一个独立的代码块格式如下文件app.py代码内容文件models.py代码内容…请按被依赖的文件先输出的顺序排列——即config.py最先因为它被其他所有文件依赖。⌨️ 这里的细节是按被依赖顺序排列——这让读者可以从头到尾顺序阅读不需要来回跳转去找某个变量或函数是在哪个文件中定义的。 --- ## 三、代码内容的精确控制 ### 3.1 命名规范控制 变量命名直接影响代码的可读性和可维护性。AI默认的命名质量参差不齐——有时用x、temp、data这种无意义的名字有时用theListOfUsersThatAreActive这种过度冗长的名字。 **命名规范控制指令**请遵守以下命名规范生成代码变量名小写下划线如 user_list、total_count函数名小写下划线动词名词如 get_user_by_id()类名大驼峰如 UserRepository、OrderService常量全大写下划线如 MAX_RETRY_COUNT、DB_TIMEOUT不要使用单字母变量除了循环中的i,j,k和lambda中的x不要使用缩写除非该缩写是行业通用缩写如id、url、http布尔变量以is_/has_/can_/should_开头### 3.2 注释质量控制 哪些该注释、哪些不该注释——这个是需要明确告诉AI的注释规范✅ 必须注释的位置每个公开函数/类必须有docstring复杂的业务逻辑超过5行的算法必须有逐段注释非直观的魔法数字必须有注释解释原因临时解决方案workaround必须注释原因和计划❌ 不要注释的位置不要写显而易见的注释如# 导入os模块 import os不要用注释配音代码如# 循环遍历每个元素 for item in items不要用注释代替好的命名如果你觉得需要加注释解释变量说明变量名起得不够好应该改名而非加注释 注释原则总结注释应该解释为什么而不是是什么。是什么应该由代码本身通过好的命名和清晰的结构来表达。### 3.3 错误处理控制 ⚠️ AI生成的代码最容易出问题的地方不是核心逻辑而是异常处理。AI常常生成快乐路径的代码——只考虑正常情况不考虑异常情况。生成的代码必须包含以下异常处理所有I/O操作文件读写、网络请求、数据库操作必须用try-except包裹异常类型要具体不要用裸露的except:至少except Exception as e:每种异常要有对应的处理策略可恢复的重试或降级处理不可恢复的记录日志向上抛出或返回错误状态必须包含finally块来释放资源文件句柄、数据库连接、网络socket自定义异常类要用清晰的类名继承自合适的内置异常类型### 3.4 类型注解控制 对于Python、TypeScript等支持类型注解的语言明确要求类型注解能大幅提升代码质量所有的函数/方法必须包含完整的类型注解参数类型返回值类型如果使用泛型List[User]、Optional[str]等确保类型参数完整示例格式fromtypingimportList,Optional,Dictdefsearch_users(keyword:str,department:Optional[str]None,limit:int20)-List[Dict[str,any]]:搜索用户...--- ## 四、确保代码可运行的进阶技巧 ### 4.1 要求AI输出可运行性检查清单 在AI生成代码之后让它自己输出一份检查清单在代码块输出完毕后请附加以下检查清单【可运行性检查清单】所有import语句完整且正确可以直接复制粘贴运行所有函数/变量被使用前已定义没有TODO、FIXME、…等占位符外部依赖已在requirements.txt/pom.xml/package.json中列出配置文件模板已提供如有需要Python版本兼容性已说明已测试的逻辑边界空输入、极大值、null/None处理✅ 这个检查清单有两个作用一是让你快速验证代码的完整性二是反向约束AI——当AI知道需要输出这份清单时它在生成代码时就会更加严谨。 ### 4.2 环境与依赖的显式声明生成的代码必须包含以下环境元信息放在第一个代码块之前【运行环境】语言版本Python 3.10请确认兼容你当前的版本操作系统跨平台如需特定系统请注明核心依赖及版本requests 2.28.0pandas 1.5.0…【安装命令】pipinstallrequests2.28.0 pandas1.5.0【快速启动】# 1. 安装依赖pipinstall-rrequirements.txt# 2. 配置环境变量复制.env.example为.env并填写配置# 3. 运行python main.py### 4.3 让AI测试自己生成的代码 这是一个高级技巧——你可以让AI模拟执行自己生成的代码在输出代码后请进行逻辑走查——用注释的形式在关键位置标注每一步执行后的预期状态defcalculate_discount(order_total:float,user_level:str)-float:ifuser_levelvip:discount0.2elifuser_levelregular:discount0.05else:discount0.0returnorder_total*(1-discount)逻辑走查输入order_total100, user_level“vip”步骤1user_level “vip” → True → discount 0.2步骤2100 * (1 - 0.2) 100 * 0.8 80输出80.0 ✅输入order_total0, user_level“vip”步骤1user_level “vip” → True → discount 0.2步骤20 * 0.8 0输出0.0 ✅边界值处理正确如果发现输入参数可能导致错误或异常结果请在走查中标注出来。 这个技巧的价值在于它让AI不只是生成代码而是审视自己生成的代码。往往在逻辑走查阶段AI能发现自己生成代码中的逻辑漏洞。 --- ## 五、不同场景的代码块控制策略 ### 5.1 教学场景注释丰富的代码 教学场景的目标是让读者理解而非让机器执行请为Python初学者写一段文件批处理的代码。这是教学用途。教学要求代码整体结构简单不超过30行每个关键步骤前用一行注释解释在这一步我们做什么不要使用高级特性如装饰器、生成器、上下文管理器除外使用有教育意义的变量名如file_list比fl好在代码块后用3-5点总结本节的关键知识点### 5.2 生产场景精简高效的代码 生产场景的目标是可维护、可扩展、可运行请为生产环境编写一段文件批处理的代码。生产要求完整的异常处理区分可恢复错误和致命错误使用logging而非print进行日志输出配置外部化不要硬编码路径、密钥等支持dry-run模式先检查不执行函数单一职责每个函数不超过20行关键操作有性能注释如此操作在大文件场景下可能耗时较长代码注释只写为什么不写是什么### 5.3 原型场景快速验证的代码 原型场景的目标是快速验证想法请写一段快速原型代码来验证[想法]。这是原型验证用途。快速原型要求优先速度而非完美可以简化异常处理在关键判断点使用assert或简单验证——快速失败使用print输出关键的中间状态代码顶部用注释标明“PROTOTYPE - 仅用于验证生产使用需重构”将可以后续优化的地方用 # OPTIMIZE: 标注### 5.4 代码审查场景标注式的代码输出 当你需要AI帮你审查代码时请对以下代码进行审查输出格式要求【问题清单】行号严重程度问题类型问题描述修复建议12 高安全SQL注入风险使用参数化查询25 中性能N1查询使用批量查询【修复后代码】在这里放修复后的完整代码【修改说明】修改1第12行[原代码] → [新代码] —— [为什么改]修改2第25行[原代码] → [新代码] —— [为什么改]--- ## 六、多语言代码块的特殊控制 ### 6.1 Python代码块的特殊控制 Python对缩进极其敏感所以需要特别的缩进控制Python代码特殊要求缩进使用4个空格绝对不要混用Tab和空格长的函数调用或定义使用以下两种换行方式之一方式A悬挂缩进result some_function(argument1, argument2,argument3, argument4)方式B对齐缩进result some_function(argument1, argument2,argument3, argument4)请选择一种并在全文中保持一致使用ifname “main”:作为入口所有字符串使用双引号除非字符串内包含双引号### 6.2 JavaScript/TypeScript代码块控制JavaScript/TypeScript代码特殊要求使用const/let禁止使用var使用箭头函数处理回调使用模板字符串反引号拼接字符串使用而非进行比较async/await优于.then()链式调用TypeScript项目必须定义所有接口和类型### 6.3 SQL代码块控制SQL代码特殊要求关键字全部大写SELECT、FROM、WHERE、JOIN等表名和列名用小写下划线复杂查询用CTEWITH子句分步组织每个子查询要有注释说明用途所有WHERE条件如果是用户输入的必须注明参数化要求对于MySQL注明存储引擎建议对于PostgreSQL注明是否需要创建索引--- ## 七、代码块输出的常见问题与解决方案 ### 7.1 问题一AI生成了伪代码而非真实代码 **现象**AI输出类似// 这里调用API获取数据、// TODO: 实现具体逻辑的占位符。 **解决方案**在提示词中明确声明“禁止在代码中使用TODO、FIXME、…等占位符。禁止使用伪代码或占位注释代替实际实现。如果你不确定某个功能的实现方式请使用一个合理的默认实现并在注释中标注假设条件。”### 7.2 问题二生成代码使用了不存在的API **现象**AI幻觉出了一个不存在的库函数或API方法。 **解决方案**“请只使用标准库和主流第三方库中的公开API。如果你需要使用一个较少见的函数请注明该函数所属的库和版本。如果不确定某个API是否存在请使用你能确认存在的替代方案。”在代码块后附加【依赖验证提示】请运行以下命令验证所有依赖是否可用python-cimport [库1]; import [库2] 如果任何导入失败请检查对应库的安装状态。7.3 问题三代码与当前环境不兼容现象AI生成了Python 3.12的新语法但你在用Python 3.8。解决方案请生成兼容Python 3.8的代码。 不要使用以下Python 3.8之后引入的特性 - match-case语句3.10 - 联合类型使用|符号3.10中可用但3.8需要用Optional/Union 如果你的建议中包含了需要更高版本Python的特性请明确标注并给出降级替代方案。7.4 问题四代码块中包含不可见字符现象从AI复制代码到编辑器后出现奇怪的不可见字符导致编译/解析失败。⚠️ 这个问题通常来自AI输出中混入了Unicode特殊字符如全角空格、零宽空格、特殊引号。解决方案代码中请只使用ASCII字符集英文字母、数字、标准标点。 字符串字面量中如果需要中文请使用Unicode转义或确保使用UTF-8编码。 不要在代码中使用全角字符、弯引号、、破折号——等非代码字符。八、完整提示词模板库8.1 通用代码生成模板【角色】你是一位经验丰富的[编程语言]开发者代码风格遵循 [语言社区]的最佳实践。 【任务】请实现以下功能[功能描述] 【代码要求】 - 语言版本[Python 3.10] - 代码风格遵循[PEP 8 / Airbnb Style Guide / Google Style Guide] - 命名规范[具体规则] - 注释规范[具体规则] - 异常处理[具体规则] - 测试[是否包含使用示例或测试用例] 【输出格式】 ### 文件[文件名] [语言] 代码内容【环境要求】放在第一个代码块之前语言版本[X.X]依赖[列出]安装命令[命令]【使用示例】放在所有代码块之后# 基本用法示例### 8.2 代码重构提示词模板请对以下代码进行重构。重构目标[提升性能/增强可读性/降低耦合度/…]原始代码原始代码重构要求保持原有功能完全不变不改变公共接口函数签名、类名[具体重构目标的要求]在重构后的代码中用注释标注关键改动点输出格式【重构后代码】新代码【改动对照】位置改动前改动后改动理由### 8.3 Bug修复提示词模板以下代码存在一个Bug。请帮我定位并修复。有Bug的代码现象描述[Bug表现]预期行为[期望的正确行为]环境信息[语言版本、系统、相关依赖版本]输出格式【Bug诊断】问题根因[解释为什么会出现这个Bug]影响范围[这个Bug可能影响哪些场景]【修复后代码】修复后的完整代码【修复验证】测试用例1输入[X] → 预期输出[Y]测试用例2边界值[Z] → 预期输出[…]--- ## 九、实战案例用代码块控制提示词完成一个完整的API开发 ### 9.1 场景描述 假设你需要开发一个简单的用户管理REST API。你希望AI一次性输出一个完整的、可直接运行的Flask应用。 ### 9.2 完整提示词你是一位Python后端开发专家。请帮我实现一个简单的用户管理REST API。【技术栈】框架Flask 2.x数据库SQLite开发环境PostgreSQL生产环境已注释认证JWT使用PyJWT库序列化Marshmallow【功能需求】用户注册POST /api/register用户登录POST /api/login—— 返回JWT token获取用户列表GET /api/users—— 需要认证获取单个用户GET /api/users/—— 需要认证更新用户信息PUT /api/users/—— 需要认证且只能修改自己的信息删除用户DELETE /api/users/—— 需要管理员权限【代码要求】项目结构清晰使用Blueprint组织路由所有密码使用bcrypt哈希输入验证邮箱格式、密码强度等完整的异常处理和错误响应使用环境变量管理敏感配置PEP 8规范类型注解完整每个函数有docstring【输出格式】请按以下文件顺序输出每个文件一个独立代码块文件requirements.txt依赖列表标注版本文件config.py配置类使用环境变量文件models.pySQLAlchemy模型定义文件schemas.pyMarshmallow序列化/反序列化schema文件auth.pyJWT认证相关工具函数和装饰器文件routes.py所有API路由文件app.py应用入口工厂函数快速启动说明如何在本地运行这个项目### 9.3 为什么这个提示词有效 第一**技术栈预定义**。明确框架、数据库、认证方式AI不会在选型上浪费时间。 第二**功能需求用API规范格式描述**。HTTP方法路径简要说明这既是需求描述也是隐式的代码结构约束。 第三**代码要求具体到实现细节**。bcrypt哈希、环境变量管理配置、Blueprint组织路由——这些不是可选的建议而是强制性的实现约束。 第四**文件顺序按依赖关系排列**。requirements.txt最先config.py其次——因为后面的文件依赖它们。 ✅ 这种级别的提示词AI输出的代码基本上只需要改一下环境变量配置就能直接跑起来。 --- ## 十、核心要点总结 ✅ **代码块输出的核心目标是可运行性而非看起来对**。你需要通过约束让AI从生成演示代码模式切换到生成生产代码模式。 ✅ **五个控制维度缺一不可**结构完整性import/依赖、格式正确性缩进/空白、可读性命名/注释、可运行性环境/配置、安全性输入验证/密钥管理。 ✅ **代码说明双区结构是最佳输出模式**——代码块保持干净可执行说明文字独立于代码块之外两者互不污染。 ✅ **用可运行性检查清单反向约束AI**。当AI知道自己需要输出验证清单时它在生成代码阶段就会更加严谨。 ✅ **针对不同场景使用不同的控制策略**教学场景重注释重解释生产场景重健壮性重规范原型场景重速度重快速验证。 ✅ **多语言项目要指定每个语言的特殊规范**。Python的缩进、JS的const/let、SQL的大写关键字——每个语言有不同的关注点。 ✅ **显式禁止TODO、伪代码和幻觉API**。不给AI留以后再补的后门强制它在生成时就给出完整实现。 最后一句话**让AI生成代码不难难的是让它生成复制粘贴就能跑的代码。这中间差的不只是技术差的是你对输出结构的设计意识。好的代码块提示词本质上是一份写给AI的编码规范——你规定得越细AI交付得越好。**
代码块输出控制：让AI生成可复制的代码
代码块输出控制让AI生成可复制的代码你有没有过这种抓狂的体验让AI写一段代码它确实写出来了逻辑也对但你复制粘贴到编辑器后——缩进全乱了、注释全是废话、变量名毫无意义、缺少必要的import语句、还混着大段的解释文字。你花了10分钟让它生成代码又花了20分钟手动修代码才能跑起来。这不是AI的问题是你的提示词没有做代码块输出控制。今天我教你一套方法论让AI输出的代码真正做到复制粘贴就能跑。一、为什么代码块输出控制是一个独立话题1.1 代码与自然语言的本质差异 自然语言可以容忍模糊、容忍冗余、容忍不精确。但代码不行。代码是给机器执行的——少一个分号就报错多一个空格就逻辑偏移缩进层级差一个字符Python就直接罢工。这个本质差异带来了一个关键挑战AI擅长生成看起来对的代码但不容易生成直接能跑的代码。这中间差的就是你对代码块输出结构的精确控制。看起来对的代码 vs 直接能跑的代码 看起来对的代码 // 连接数据库 connect(db) // 查询用户 getUsers() // 返回结果 直接能跑的代码 import mysql.connector from config import DB_HOST, DB_USER, DB_PASS, DB_NAME def get_active_users(): 返回最近30天内有活动的用户列表 try: conn mysql.connector.connect( hostDB_HOST, userDB_USER, passwordDB_PASS, databaseDB_NAME ) cursor conn.cursor(dictionaryTrue) cursor.execute( SELECT id, username, email, last_login FROM users WHERE last_login DATE_SUB(NOW(), INTERVAL 30 DAY) AND status active ORDER BY last_login DESC ) return cursor.fetchall() except mysql.connector.Error as e: print(f数据库查询失败: {e}) return [] finally: if conn and conn.is_connected(): cursor.close() conn.close() 两组代码的差距一目了然。第一组是思路演示第二组是生产可用。而要让AI输出第二组而非第一组关键在于你的提示词设计。1.2 代码块输出的五个控制维度我把代码块输出控制分为五个核心维度维度控制内容典型问题结构完整性import、依赖、入口函数、异常处理AI遗漏必要的import导致代码无法运行格式正确性缩进、空白、换行、编码复制粘贴后缩进全乱可读性命名规范、注释质量、代码组织变量名是a/b/c/x1/x2可运行性依赖版本、环境要求、配置代码语法对但缺少环境说明安全性输入验证、注入防护、密钥管理AI生成含硬编码密码的代码二、代码块格式的基础控制2.1 指定语言标记⌨️ 最基础但最容易被忽视的一步——告诉AI用正确的Markdown代码块语言标记请用Python语言实现以下功能[功能描述] 输出格式要求 - 代码放在 python 代码块中 - 不要将多个小的代码片段分散在解释文字中集中放在一个代 码块中除非确实需要解释穿插⚠️ 为什么要明确指定python而不仅仅是代码块因为正确的语言标记能让Markdown渲染器正确高亮语法。没有语言标记的代码块大部分平台会显示为纯文本阅读体验和复制体验都会大打折扣。2.2 分离代码与解释这是一个高频问题AI在代码块中混入自然语言解释导致代码无法直接复制使用。问题示例python # 这里我们引入需要的库 import pandas as pd # 然后读取CSV文件 df pd.read_csv(data.csv) # 接下来过滤掉空值——这是数据清洗的第一步 df df.dropna() # 最后输出清洗后的行数 print(f清洗后剩余{len(df)}行)这个代码块中有大量的教程式注释。如果你的目的是教学这没问题但如果你的目的是直接用这些注释就是噪声。 **解决方案——分离指令**请将代码和注释分开输出【代码块】干净可执行的代码注释只保留必要的docstring和技术注释在这里放代码【代码说明】代码块之后单独列出不作为代码的一部分第X行的作用[解释]为什么选择这个实现方式[理由] 这个代码说明的双区结构是我最推荐的模式。代码区是干净的、可直接运行的说明区承载教学和解释功能。两个区域互不污染。 ### 2.3 多文件/多代码块的组织 当任务涉及多个文件时如何组织输出就变得很重要请为这个Flask应用生成完整的后端代码包含以下文件app.py主应用models.py数据库模型routes.py路由处理config.py配置文件requirements.txt依赖列表输出时每个文件一个独立的代码块格式如下文件app.py代码内容文件models.py代码内容…请按被依赖的文件先输出的顺序排列——即config.py最先因为它被其他所有文件依赖。⌨️ 这里的细节是按被依赖顺序排列——这让读者可以从头到尾顺序阅读不需要来回跳转去找某个变量或函数是在哪个文件中定义的。 --- ## 三、代码内容的精确控制 ### 3.1 命名规范控制 变量命名直接影响代码的可读性和可维护性。AI默认的命名质量参差不齐——有时用x、temp、data这种无意义的名字有时用theListOfUsersThatAreActive这种过度冗长的名字。 **命名规范控制指令**请遵守以下命名规范生成代码变量名小写下划线如 user_list、total_count函数名小写下划线动词名词如 get_user_by_id()类名大驼峰如 UserRepository、OrderService常量全大写下划线如 MAX_RETRY_COUNT、DB_TIMEOUT不要使用单字母变量除了循环中的i,j,k和lambda中的x不要使用缩写除非该缩写是行业通用缩写如id、url、http布尔变量以is_/has_/can_/should_开头### 3.2 注释质量控制 哪些该注释、哪些不该注释——这个是需要明确告诉AI的注释规范✅ 必须注释的位置每个公开函数/类必须有docstring复杂的业务逻辑超过5行的算法必须有逐段注释非直观的魔法数字必须有注释解释原因临时解决方案workaround必须注释原因和计划❌ 不要注释的位置不要写显而易见的注释如# 导入os模块 import os不要用注释配音代码如# 循环遍历每个元素 for item in items不要用注释代替好的命名如果你觉得需要加注释解释变量说明变量名起得不够好应该改名而非加注释 注释原则总结注释应该解释为什么而不是是什么。是什么应该由代码本身通过好的命名和清晰的结构来表达。### 3.3 错误处理控制 ⚠️ AI生成的代码最容易出问题的地方不是核心逻辑而是异常处理。AI常常生成快乐路径的代码——只考虑正常情况不考虑异常情况。生成的代码必须包含以下异常处理所有I/O操作文件读写、网络请求、数据库操作必须用try-except包裹异常类型要具体不要用裸露的except:至少except Exception as e:每种异常要有对应的处理策略可恢复的重试或降级处理不可恢复的记录日志向上抛出或返回错误状态必须包含finally块来释放资源文件句柄、数据库连接、网络socket自定义异常类要用清晰的类名继承自合适的内置异常类型### 3.4 类型注解控制 对于Python、TypeScript等支持类型注解的语言明确要求类型注解能大幅提升代码质量所有的函数/方法必须包含完整的类型注解参数类型返回值类型如果使用泛型List[User]、Optional[str]等确保类型参数完整示例格式fromtypingimportList,Optional,Dictdefsearch_users(keyword:str,department:Optional[str]None,limit:int20)-List[Dict[str,any]]:搜索用户...--- ## 四、确保代码可运行的进阶技巧 ### 4.1 要求AI输出可运行性检查清单 在AI生成代码之后让它自己输出一份检查清单在代码块输出完毕后请附加以下检查清单【可运行性检查清单】所有import语句完整且正确可以直接复制粘贴运行所有函数/变量被使用前已定义没有TODO、FIXME、…等占位符外部依赖已在requirements.txt/pom.xml/package.json中列出配置文件模板已提供如有需要Python版本兼容性已说明已测试的逻辑边界空输入、极大值、null/None处理✅ 这个检查清单有两个作用一是让你快速验证代码的完整性二是反向约束AI——当AI知道需要输出这份清单时它在生成代码时就会更加严谨。 ### 4.2 环境与依赖的显式声明生成的代码必须包含以下环境元信息放在第一个代码块之前【运行环境】语言版本Python 3.10请确认兼容你当前的版本操作系统跨平台如需特定系统请注明核心依赖及版本requests 2.28.0pandas 1.5.0…【安装命令】pipinstallrequests2.28.0 pandas1.5.0【快速启动】# 1. 安装依赖pipinstall-rrequirements.txt# 2. 配置环境变量复制.env.example为.env并填写配置# 3. 运行python main.py### 4.3 让AI测试自己生成的代码 这是一个高级技巧——你可以让AI模拟执行自己生成的代码在输出代码后请进行逻辑走查——用注释的形式在关键位置标注每一步执行后的预期状态defcalculate_discount(order_total:float,user_level:str)-float:ifuser_levelvip:discount0.2elifuser_levelregular:discount0.05else:discount0.0returnorder_total*(1-discount)逻辑走查输入order_total100, user_level“vip”步骤1user_level “vip” → True → discount 0.2步骤2100 * (1 - 0.2) 100 * 0.8 80输出80.0 ✅输入order_total0, user_level“vip”步骤1user_level “vip” → True → discount 0.2步骤20 * 0.8 0输出0.0 ✅边界值处理正确如果发现输入参数可能导致错误或异常结果请在走查中标注出来。 这个技巧的价值在于它让AI不只是生成代码而是审视自己生成的代码。往往在逻辑走查阶段AI能发现自己生成代码中的逻辑漏洞。 --- ## 五、不同场景的代码块控制策略 ### 5.1 教学场景注释丰富的代码 教学场景的目标是让读者理解而非让机器执行请为Python初学者写一段文件批处理的代码。这是教学用途。教学要求代码整体结构简单不超过30行每个关键步骤前用一行注释解释在这一步我们做什么不要使用高级特性如装饰器、生成器、上下文管理器除外使用有教育意义的变量名如file_list比fl好在代码块后用3-5点总结本节的关键知识点### 5.2 生产场景精简高效的代码 生产场景的目标是可维护、可扩展、可运行请为生产环境编写一段文件批处理的代码。生产要求完整的异常处理区分可恢复错误和致命错误使用logging而非print进行日志输出配置外部化不要硬编码路径、密钥等支持dry-run模式先检查不执行函数单一职责每个函数不超过20行关键操作有性能注释如此操作在大文件场景下可能耗时较长代码注释只写为什么不写是什么### 5.3 原型场景快速验证的代码 原型场景的目标是快速验证想法请写一段快速原型代码来验证[想法]。这是原型验证用途。快速原型要求优先速度而非完美可以简化异常处理在关键判断点使用assert或简单验证——快速失败使用print输出关键的中间状态代码顶部用注释标明“PROTOTYPE - 仅用于验证生产使用需重构”将可以后续优化的地方用 # OPTIMIZE: 标注### 5.4 代码审查场景标注式的代码输出 当你需要AI帮你审查代码时请对以下代码进行审查输出格式要求【问题清单】行号严重程度问题类型问题描述修复建议12 高安全SQL注入风险使用参数化查询25 中性能N1查询使用批量查询【修复后代码】在这里放修复后的完整代码【修改说明】修改1第12行[原代码] → [新代码] —— [为什么改]修改2第25行[原代码] → [新代码] —— [为什么改]--- ## 六、多语言代码块的特殊控制 ### 6.1 Python代码块的特殊控制 Python对缩进极其敏感所以需要特别的缩进控制Python代码特殊要求缩进使用4个空格绝对不要混用Tab和空格长的函数调用或定义使用以下两种换行方式之一方式A悬挂缩进result some_function(argument1, argument2,argument3, argument4)方式B对齐缩进result some_function(argument1, argument2,argument3, argument4)请选择一种并在全文中保持一致使用ifname “main”:作为入口所有字符串使用双引号除非字符串内包含双引号### 6.2 JavaScript/TypeScript代码块控制JavaScript/TypeScript代码特殊要求使用const/let禁止使用var使用箭头函数处理回调使用模板字符串反引号拼接字符串使用而非进行比较async/await优于.then()链式调用TypeScript项目必须定义所有接口和类型### 6.3 SQL代码块控制SQL代码特殊要求关键字全部大写SELECT、FROM、WHERE、JOIN等表名和列名用小写下划线复杂查询用CTEWITH子句分步组织每个子查询要有注释说明用途所有WHERE条件如果是用户输入的必须注明参数化要求对于MySQL注明存储引擎建议对于PostgreSQL注明是否需要创建索引--- ## 七、代码块输出的常见问题与解决方案 ### 7.1 问题一AI生成了伪代码而非真实代码 **现象**AI输出类似// 这里调用API获取数据、// TODO: 实现具体逻辑的占位符。 **解决方案**在提示词中明确声明“禁止在代码中使用TODO、FIXME、…等占位符。禁止使用伪代码或占位注释代替实际实现。如果你不确定某个功能的实现方式请使用一个合理的默认实现并在注释中标注假设条件。”### 7.2 问题二生成代码使用了不存在的API **现象**AI幻觉出了一个不存在的库函数或API方法。 **解决方案**“请只使用标准库和主流第三方库中的公开API。如果你需要使用一个较少见的函数请注明该函数所属的库和版本。如果不确定某个API是否存在请使用你能确认存在的替代方案。”在代码块后附加【依赖验证提示】请运行以下命令验证所有依赖是否可用python-cimport [库1]; import [库2] 如果任何导入失败请检查对应库的安装状态。7.3 问题三代码与当前环境不兼容现象AI生成了Python 3.12的新语法但你在用Python 3.8。解决方案请生成兼容Python 3.8的代码。 不要使用以下Python 3.8之后引入的特性 - match-case语句3.10 - 联合类型使用|符号3.10中可用但3.8需要用Optional/Union 如果你的建议中包含了需要更高版本Python的特性请明确标注并给出降级替代方案。7.4 问题四代码块中包含不可见字符现象从AI复制代码到编辑器后出现奇怪的不可见字符导致编译/解析失败。⚠️ 这个问题通常来自AI输出中混入了Unicode特殊字符如全角空格、零宽空格、特殊引号。解决方案代码中请只使用ASCII字符集英文字母、数字、标准标点。 字符串字面量中如果需要中文请使用Unicode转义或确保使用UTF-8编码。 不要在代码中使用全角字符、弯引号、、破折号——等非代码字符。八、完整提示词模板库8.1 通用代码生成模板【角色】你是一位经验丰富的[编程语言]开发者代码风格遵循 [语言社区]的最佳实践。 【任务】请实现以下功能[功能描述] 【代码要求】 - 语言版本[Python 3.10] - 代码风格遵循[PEP 8 / Airbnb Style Guide / Google Style Guide] - 命名规范[具体规则] - 注释规范[具体规则] - 异常处理[具体规则] - 测试[是否包含使用示例或测试用例] 【输出格式】 ### 文件[文件名] [语言] 代码内容【环境要求】放在第一个代码块之前语言版本[X.X]依赖[列出]安装命令[命令]【使用示例】放在所有代码块之后# 基本用法示例### 8.2 代码重构提示词模板请对以下代码进行重构。重构目标[提升性能/增强可读性/降低耦合度/…]原始代码原始代码重构要求保持原有功能完全不变不改变公共接口函数签名、类名[具体重构目标的要求]在重构后的代码中用注释标注关键改动点输出格式【重构后代码】新代码【改动对照】位置改动前改动后改动理由### 8.3 Bug修复提示词模板以下代码存在一个Bug。请帮我定位并修复。有Bug的代码现象描述[Bug表现]预期行为[期望的正确行为]环境信息[语言版本、系统、相关依赖版本]输出格式【Bug诊断】问题根因[解释为什么会出现这个Bug]影响范围[这个Bug可能影响哪些场景]【修复后代码】修复后的完整代码【修复验证】测试用例1输入[X] → 预期输出[Y]测试用例2边界值[Z] → 预期输出[…]--- ## 九、实战案例用代码块控制提示词完成一个完整的API开发 ### 9.1 场景描述 假设你需要开发一个简单的用户管理REST API。你希望AI一次性输出一个完整的、可直接运行的Flask应用。 ### 9.2 完整提示词你是一位Python后端开发专家。请帮我实现一个简单的用户管理REST API。【技术栈】框架Flask 2.x数据库SQLite开发环境PostgreSQL生产环境已注释认证JWT使用PyJWT库序列化Marshmallow【功能需求】用户注册POST /api/register用户登录POST /api/login—— 返回JWT token获取用户列表GET /api/users—— 需要认证获取单个用户GET /api/users/—— 需要认证更新用户信息PUT /api/users/—— 需要认证且只能修改自己的信息删除用户DELETE /api/users/—— 需要管理员权限【代码要求】项目结构清晰使用Blueprint组织路由所有密码使用bcrypt哈希输入验证邮箱格式、密码强度等完整的异常处理和错误响应使用环境变量管理敏感配置PEP 8规范类型注解完整每个函数有docstring【输出格式】请按以下文件顺序输出每个文件一个独立代码块文件requirements.txt依赖列表标注版本文件config.py配置类使用环境变量文件models.pySQLAlchemy模型定义文件schemas.pyMarshmallow序列化/反序列化schema文件auth.pyJWT认证相关工具函数和装饰器文件routes.py所有API路由文件app.py应用入口工厂函数快速启动说明如何在本地运行这个项目### 9.3 为什么这个提示词有效 第一**技术栈预定义**。明确框架、数据库、认证方式AI不会在选型上浪费时间。 第二**功能需求用API规范格式描述**。HTTP方法路径简要说明这既是需求描述也是隐式的代码结构约束。 第三**代码要求具体到实现细节**。bcrypt哈希、环境变量管理配置、Blueprint组织路由——这些不是可选的建议而是强制性的实现约束。 第四**文件顺序按依赖关系排列**。requirements.txt最先config.py其次——因为后面的文件依赖它们。 ✅ 这种级别的提示词AI输出的代码基本上只需要改一下环境变量配置就能直接跑起来。 --- ## 十、核心要点总结 ✅ **代码块输出的核心目标是可运行性而非看起来对**。你需要通过约束让AI从生成演示代码模式切换到生成生产代码模式。 ✅ **五个控制维度缺一不可**结构完整性import/依赖、格式正确性缩进/空白、可读性命名/注释、可运行性环境/配置、安全性输入验证/密钥管理。 ✅ **代码说明双区结构是最佳输出模式**——代码块保持干净可执行说明文字独立于代码块之外两者互不污染。 ✅ **用可运行性检查清单反向约束AI**。当AI知道自己需要输出验证清单时它在生成代码阶段就会更加严谨。 ✅ **针对不同场景使用不同的控制策略**教学场景重注释重解释生产场景重健壮性重规范原型场景重速度重快速验证。 ✅ **多语言项目要指定每个语言的特殊规范**。Python的缩进、JS的const/let、SQL的大写关键字——每个语言有不同的关注点。 ✅ **显式禁止TODO、伪代码和幻觉API**。不给AI留以后再补的后门强制它在生成时就给出完整实现。 最后一句话**让AI生成代码不难难的是让它生成复制粘贴就能跑的代码。这中间差的不只是技术差的是你对输出结构的设计意识。好的代码块提示词本质上是一份写给AI的编码规范——你规定得越细AI交付得越好。**
