1. 项目概述从“魔法咒语”到“工程蓝图”如果你用过Claude Code或者任何类似的AI编程助手肯定有过这样的体验有时候你问得含糊不清它给你一堆废话有时候你稍微调整一下问法它就像开了窍一样直接给你一段精准、可用的代码。这背后就是“提示词”在起作用。很多人把提示词比作“魔法咒语”觉得它神秘莫测全靠运气。但作为一个在AI辅助开发领域摸爬滚打多年的从业者我可以很负责任地告诉你提示词的构建绝非玄学而是一门有章可循的“工程学”。Claude Code的提示词装配本质上是一个将你的模糊意图转化为AI能精确理解的、结构化的“工程蓝图”的过程。它不是在聊天框里随便打几个字而是需要你像一位严谨的产品经理或架构师一样去定义需求、设定边界、提供上下文、并明确输出格式。这个过程直接决定了AI是给你一个玩具还是给你一把趁手的瑞士军刀。简单来说一个高质量的Claude Code提示词通常需要解决以下几个核心问题你是谁角色定义你要做什么任务目标在什么环境下做上下文与约束以及最终成果长什么样输出格式。接下来我们就抛开那些华而不实的理论直接深入到装配车间看看这份“蓝图”到底是怎么一砖一瓦搭建起来的。2. 核心思路拆解构建提示词的四大支柱为什么有的提示词效果好有的效果差关键在于结构。经过大量实践我总结出高效提示词离不开四大支柱角色设定、任务拆解、上下文注入和格式规范。这四者环环相扣缺一不可。2.1 角色设定给AI一个“专业人设”这是最容易被忽视但效果最立竿见影的一步。你不告诉AI它该以什么身份思考它就会默认使用一个“通用助手”的视角这往往意味着平庸和泛泛而谈。为什么有效AI模型在训练时接触了海量不同专业领域的文本。当你指定一个角色如“资深Python后端架构师”、“严谨的代码审查专家”或“富有创意的前端动画工程师”时你实际上是在激活模型内部与该角色相关的知识模式和表达风格。这就像给AI戴上了一副专业的“眼镜”让它能从一个特定的、高水平的视角来看待问题。如何设定角色设定需要具体、有相关性。不要只说“你是一个程序员”而要说“你是一个精通FastAPI、熟悉异步编程、并对数据库优化有丰富经验的Python后端工程师”。这样AI在生成代码或建议时会自然地倾向于使用相关技术栈和最佳实践。实操心得越具体越专业角色描述可以包括经验年限、技术偏好如“偏好使用TypeScript而非JavaScript”、甚至工作风格如“注重代码可读性和可维护性”。组合角色对于复杂任务可以要求AI同时扮演多个角色。例如“请你首先以安全审计员的身份检查这段代码的潜在漏洞然后以性能优化专家的身份提出改进建议。”2.2 任务拆解从模糊需求到清晰指令用户的需求往往是模糊的比如“帮我写个登录功能”。AI如果直接照此生成结果可能五花八门。任务拆解的目的就是把“做什么”细化成“一步步怎么做”。核心方法CRISP框架。这是我常用的一个心法Context背景、Request请求、Input输入、Steps步骤、Preference偏好。背景简要说明这个功能属于哪个项目、解决什么业务问题。例如“这是一个内部员工管理系统的登录模块需要对接公司已有的LDAP认证。”请求用明确的动词陈述核心任务。例如“编写一个安全的、基于JWT令牌的用户登录API端点。”输入明确给出AI需要处理的输入是什么。例如“输入是包含username和password字段的JSON请求体。”步骤将大任务分解为可执行的小步骤。例如“1. 验证请求体结构。2. 查询数据库核对用户凭证。3. 密码使用bcrypt比对。4. 生成JWT令牌。5. 返回令牌及基本用户信息。”偏好指定技术栈、代码风格、依赖库等。例如“使用Python FastAPI框架密码哈希用passlib[bcrypt]JWT使用python-jose[cryptography]。”避坑指南避免使用“优化一下”、“让它更好”这类模糊词汇。必须量化或具体化比如“将查询时间从200ms降低到50ms以内”、“将函数拆分为三个职责单一的小函数”。2.3 上下文注入提供“战场地图”AI没有记忆在单次对话中长上下文窗口也只是提供了更大的“草稿纸”你必须把必要的“战场地图”一次性给足。上下文包括代码上下文这是最重要的部分。通过粘贴相关代码文件、类定义、函数接口、数据结构如Pydantic模型、TypeScript接口让AI知道现有的代码环境。Claude Code这类插件的优势就在于能轻松读取整个项目文件但你在提示词中主动提供最核心的片段能极大提高准确率。项目上下文技术栈Python 3.11, React 18、框架版本、关键的配置文件如package.json,requirements.txt片段、数据库Schema描述。业务逻辑上下文一些特殊的业务规则。例如“用户状态为‘冻结’时即使密码正确也应拒绝登录并返回特定错误码。”注意事项一次性提供所有必要上下文。不要像挤牙膏一样AI根据不完整上下文生成的代码很可能在整合时出现接口不一致的问题。2.4 格式规范定义输出的“样子”你肯定不希望AI给你回复一大段散文里夹杂着代码。明确的格式要求能让你和AI的协作效率倍增。结构化输出直接要求AI以特定格式回复。例如请按以下格式回复1. 代码实现[完整的代码块]2. 关键逻辑解释[简要说明核心算法或流程]3. 注意事项[列出部署、运行时需要关注的点]代码标记明确要求使用Markdown代码块并指定语言。如“请将完整代码放在 python 代码块中。”非代码输出当需要设计思路、方案对比时可以要求使用表格。例如“请用表格对比方案A和方案B在性能、复杂度、可维护性三方面的优劣。”将这四大支柱组合起来一个强大的提示词骨架就诞生了。它不再是随意的聊天而是一份清晰的工作说明书。3. 进阶装配技巧从“能用”到“好用”掌握了四大支柱你写出的提示词已经能解决80%的问题。但要追求那20%的极致效率和质量还需要一些进阶技巧。3.1 思维链与分步指令引导AI“思考”对于复杂逻辑让AI直接给出最终答案容易出错。我们可以引导它展示思考过程这被称为“思维链”提示。基本用法在提示词中加入“让我们一步步思考”、“首先我们需要分析…”等引导语。例如对于一个复杂的数据处理任务你可以写“我们需要从原始数据中提取用户购买记录。请按以下步骤思考并给出答案1. 分析原始JSON数据的结构找出包含购买信息的字段。2. 设计一个数据清洗函数处理缺失值和异常格式。3. 编写转换函数将清洗后的数据映射到目标结构PurchaseRecord。请逐步完成。”优势这样做不仅能让最终结果更可靠而且当结果出现偏差时你可以从AI的“思考步骤”中快速定位问题出在哪个环节方便你调整提示词进行修正。3.2 示例驱动提供“参考答案”对于有明确格式要求或复杂模式的输出直接给AI一两个例子效果远超千言万语的描述。这就是“少样本学习”在提示词中的应用。如何操作在提示词中先明确任务然后写上“例如”接着给出一个完整的输入输出样例。任务请你根据以下用户故事生成对应的Gherkin语法测试场景。 用户故事作为一名用户我希望在登录失败时看到明确的错误提示以便我知道是用户名错误还是密码错误。 例如 输入用户故事“作为一名购物者我希望能将商品加入购物车以便后续统一结算。” 输出Gherkin场景Scenario: 添加商品到购物车 Given 用户浏览商品列表页 When 用户点击商品A的“加入购物车”按钮 Then 购物车图标数量应增加1 And 页面应显示“商品A已加入购物车”的提示消息现在请为上述登录失败的用户故事生成Gherkin场景。适用场景生成特定格式的代码如单元测试、配置模板、编写风格固定的文档如API文档、进行数据格式转换等。3.3 系统级约束与负面提示划定“禁区”除了告诉AI要做什么明确告诉它不要做什么同样重要这能有效避免生成无关、低质甚至有害的内容。系统级约束有些约束需要放在对话最开头或Claude Code的系统角色设置中贯穿整个会话。例如“在本对话中你生成的所有代码必须包含详细的注释解释关键算法和复杂逻辑。”、“请勿生成任何用于网络攻击、破解或侵犯隐私的代码。”负面提示针对当前任务的具体限制。例如“在实现这个排序算法时请不要使用内置的sort()函数请展示手动实现的逻辑。”、“解释概念时避免使用过于学术化的术语用比喻和生活中的例子来说明。”实操心得负面提示要具体。说“不要写低效代码”是无效的要说“避免使用时间复杂度高于O(n log n)的算法”或“禁止在循环内部执行数据库查询”。3.4 迭代与优化提示词也需要“调试”不要指望第一个提示词就完美无缺。将提示词工程视为一个迭代过程。初版生成基于四大支柱写出第一版提示词获取AI的回复。结果评估检查输出是否符合预期哪里不准确、不完整或多余归因分析是角色设定不准确任务步骤有歧义上下文不足还是格式混乱修改提示针对性地强化或修正提示词中的相应部分。例如如果AI忽略了错误处理就在“步骤”中明确加入“添加完整的异常处理逻辑”如果代码风格不符就在“偏好”中强调“遵循PEP 8规范”。重复直到获得满意结果。你可以保存这个优化后的提示词作为模板用于类似任务。4. 实战案例拆解装配一个完整的代码生成提示词让我们通过一个具体案例将上述所有技巧串联起来。假设我们需要Claude Code帮我们创建一个文件上传的API端点。初始模糊需求“帮我写个文件上传接口。”这个需求会带来各种不确定的结果。现在我们开始装配4.1 第一支柱角色设定你是一位资深Python后端工程师精通FastAPI框架对Web安全有深刻理解特别熟悉文件上传、验证和云存储集成。你的代码以健壮性、安全性和可维护性为首要目标。设计意图将AI定位在特定技术栈和安全敏感的领域引导其调用相关知识。4.2 第二支柱任务拆解使用CRISP框架背景这是“在线设计协作平台”的后端服务用户需要上传设计稿图片。请求创建一个支持图片文件上传的RESTful API端点。输入HTTP POST请求multipart/form-data格式包含一个名为file的文件字段以及可选的description文本字段。步骤验证上传文件是否为允许的图片类型仅限JPG, PNG, WebP。验证文件大小不超过10MB。为防止文件名冲突和路径遍历攻击在服务器端为文件生成一个唯一的随机文件名保留原始扩展名。将文件安全地保存到服务器的指定目录例如./uploads中。注意在生产环境中这一步通常改为上传至云存储如S3但本次实现本地存储逻辑。将文件信息生成后的文件名、原始文件名、MIME类型、大小、保存路径、上传时间记录到数据库这里简化先返回一个包含这些信息的JSON响应。实现完整的异常处理对文件类型错误、大小超限、保存失败等情况返回清晰、友好的HTTP错误响应。偏好使用FastAPI框架。使用Pydantic模型来定义响应结构。代码需包含详尽的文档字符串Docstring和关键逻辑的行内注释。遵循PEP 8风格。4.3 第三支柱上下文注入项目当前使用的主要依赖版本 - fastapi0.104.1 - python-multipart0.0.6 - pydantic2.5.0 当前项目结构中已有以下Pydantic模型可供你在响应模型中引用 python from pydantic import BaseModel from datetime import datetime class FileInfo(BaseModel): id: str # 生成的文件名不含路径 original_name: str mime_type: str size: int # 字节 saved_path: str uploaded_at: datetime### 4.4 第四支柱格式规范请按以下格式输出完整代码提供可直接放入main.py或类似路由文件的完整代码块。逻辑要点说明用几句话概括你实现中的安全措施和核心逻辑。运行与测试建议说明如何运行此端点并给出一个使用curl或httpie进行测试的命令示例。### 4.5 组合与发送 将以上所有部分按逻辑顺序组合就构成了我们最终发送给Claude Code的提示词。这个提示词清晰、具体、无歧义极大地提高了获得高质量、可直接使用代码的概率。 **最终组合提示词示例**你是一位资深Python后端工程师精通FastAPI框架对Web安全有深刻理解特别熟悉文件上传、验证和云存储集成。你的代码以健壮性、安全性和可维护性为首要目标。请为“在线设计协作平台”创建一个图片上传API端点。任务详情请求创建一个支持图片文件上传的RESTful API端点。输入HTTP POST请求multipart/form-data格式包含一个名为file的文件字段以及可选的description文本字段。实现步骤验证上传文件是否为允许的图片类型仅限JPG, PNG, WebP。验证文件大小不超过10MB。为防止文件名冲突和路径遍历攻击在服务器端为文件生成一个唯一的随机文件名如UUID保留原始扩展名。将文件安全地保存到服务器的./uploads目录中请确保在代码中处理目录不存在的情况。将文件信息生成后的文件名、原始文件名、MIME类型、大小、保存路径、上传时间封装返回。实现完整的异常处理对文件类型错误、大小超限、保存失败等情况返回清晰、友好的HTTP错误响应如400, 413, 500。技术偏好使用 FastAPI 框架。使用 Pydantic 模型定义响应结构。代码需包含详尽的文档字符串Docstring和关键逻辑的行内注释。遵循 PEP 8 风格。项目上下文依赖fastapi0.104.1, python-multipart0.0.6, pydantic2.5.0可复用的模型from pydantic import BaseModel from datetime import datetime class FileInfo(BaseModel): id: str # 生成的文件名不含路径 original_name: str mime_type: str size: int # 字节 saved_path: str uploaded_at: datetime输出格式要求请按以下格式回复完整代码提供可直接放入main.py的完整代码块。逻辑要点说明用几句话概括你实现中的安全措施和核心逻辑。运行与测试建议说明如何运行此端点并给出一个使用curl进行测试的命令示例。## 5. 避坑指南与常见问题排查 即使按照最佳实践装配提示词在实际操作中仍会遇到各种问题。以下是我总结的常见“坑点”及解决方案。 ### 5.1 问题AI生成的代码忽略了关键业务逻辑或边界条件 * **排查**检查你的“任务拆解-步骤”部分是否足够细致。AI只会执行你明确写出的或强烈暗示的指令。如果业务规则复杂必须逐条列出。 * **解决**将隐含条件显式化。不要写“检查用户权限”而要写“检查用户角色字段是否为‘admin’或‘editor’并且账户状态字段为‘active’”。 * **心得**把AI想象成一个极其严格但缺乏常识的新人程序员你需要编写一份毫无歧义的详细需求文档。 ### 5.2 问题AI陷入循环或不断追问细节 * **排查**通常是上下文不足或任务过于开放导致的。AI因为信息不够无法做出确定性的输出。 * **解决** 1. **补充上下文**提供更多的相关代码、数据结构定义、API文档链接。 2. **缩小范围**将一个大任务拆分成几个连续的小任务分多次对话完成。例如先让AI设计接口和数据模型你确认后再让它基于确认的模型编写具体实现。 3. **提供选择**对于有争议的设计点你可以给出2-3个选项让AI分析并推荐而不是让它凭空创造。例如“对于缓存策略你认为使用Redis缓存查询结果还是使用内存缓存如functools.lru_cache更合适请分别分析优缺点。” ### 5.3 问题代码风格或依赖与项目现有规范不符 * **排查**检查“偏好”和“上下文”部分是否明确指定了技术栈、版本和代码风格。 * **解决** * 在提示词开头就强调“请确保生成的代码与本项目现有代码风格保持一致。” * 直接粘贴一段项目中的典型代码作为“风格示例”。 * 明确拒绝某些做法“本项目禁止使用*进行通配符导入请使用显式导入。” * **心得**风格一致性是维护性的基础。在第一次为某个项目编写提示词时多花点时间定义好这些约束后续会省力很多。 ### 5.4 问题AI“捏造”了不存在的库或API * **现象**AI生成的代码使用了some_awesome_library但这个库根本不存在或者是AI根据训练数据“幻想”出来的。 * **解决** 1. **锁定依赖**在“偏好”或“上下文”中明确指定库的名称和**常用版本**。例如“使用pandas库处理数据版本号约为1.5.x。” 2. **要求验证**在提示词末尾加上“请只使用Python标准库和上述明确提到的第三方库。如果必须使用其他库请先询问。” 3. **事后审查**对于AI生成的代码尤其是涉及不熟悉依赖的部分务必进行快速的pip show 或查阅官方文档进行验证。 ### 5.5 问题提示词太长导致AI无法聚焦或丢失前文 * **背景**虽然Claude拥有长上下文窗口但过长的提示词仍可能让AI的注意力分散忘记最早的一些指令。 * **解决** * **结构化**使用清晰的标题如## 角色、## 任务和列表来组织提示词帮助AI解析。 * **优先级**将最核心的指令角色、核心任务、输出格式放在最前面和最末尾。 * **分而治之**对于极其复杂的任务不要试图在一个提示词中解决所有问题。建立“主提示词”定义整体架构然后通过后续对话使用“基于以上架构现在请实现XX模块…”的方式进行迭代开发。 装配一个高效的提示词就像是在编写一段能与AI精确协作的“元程序”。它需要的不是魔法而是严谨的工程思维、清晰的表达和对AI工作方式的理解。从明确角色开始一步步拆解任务注入充足的上下文并严格规范输出你就能将Claude Code从一个“有时灵有时不灵”的聊天伙伴转变为一个稳定、高效、可预测的编程协作者。这个过程本身也是对你自身逻辑思考和需求分析能力的一次绝佳锻炼。 Claude Code提示词工程：四大支柱与进阶技巧构建高效AI编程助手
1. 项目概述从“魔法咒语”到“工程蓝图”如果你用过Claude Code或者任何类似的AI编程助手肯定有过这样的体验有时候你问得含糊不清它给你一堆废话有时候你稍微调整一下问法它就像开了窍一样直接给你一段精准、可用的代码。这背后就是“提示词”在起作用。很多人把提示词比作“魔法咒语”觉得它神秘莫测全靠运气。但作为一个在AI辅助开发领域摸爬滚打多年的从业者我可以很负责任地告诉你提示词的构建绝非玄学而是一门有章可循的“工程学”。Claude Code的提示词装配本质上是一个将你的模糊意图转化为AI能精确理解的、结构化的“工程蓝图”的过程。它不是在聊天框里随便打几个字而是需要你像一位严谨的产品经理或架构师一样去定义需求、设定边界、提供上下文、并明确输出格式。这个过程直接决定了AI是给你一个玩具还是给你一把趁手的瑞士军刀。简单来说一个高质量的Claude Code提示词通常需要解决以下几个核心问题你是谁角色定义你要做什么任务目标在什么环境下做上下文与约束以及最终成果长什么样输出格式。接下来我们就抛开那些华而不实的理论直接深入到装配车间看看这份“蓝图”到底是怎么一砖一瓦搭建起来的。2. 核心思路拆解构建提示词的四大支柱为什么有的提示词效果好有的效果差关键在于结构。经过大量实践我总结出高效提示词离不开四大支柱角色设定、任务拆解、上下文注入和格式规范。这四者环环相扣缺一不可。2.1 角色设定给AI一个“专业人设”这是最容易被忽视但效果最立竿见影的一步。你不告诉AI它该以什么身份思考它就会默认使用一个“通用助手”的视角这往往意味着平庸和泛泛而谈。为什么有效AI模型在训练时接触了海量不同专业领域的文本。当你指定一个角色如“资深Python后端架构师”、“严谨的代码审查专家”或“富有创意的前端动画工程师”时你实际上是在激活模型内部与该角色相关的知识模式和表达风格。这就像给AI戴上了一副专业的“眼镜”让它能从一个特定的、高水平的视角来看待问题。如何设定角色设定需要具体、有相关性。不要只说“你是一个程序员”而要说“你是一个精通FastAPI、熟悉异步编程、并对数据库优化有丰富经验的Python后端工程师”。这样AI在生成代码或建议时会自然地倾向于使用相关技术栈和最佳实践。实操心得越具体越专业角色描述可以包括经验年限、技术偏好如“偏好使用TypeScript而非JavaScript”、甚至工作风格如“注重代码可读性和可维护性”。组合角色对于复杂任务可以要求AI同时扮演多个角色。例如“请你首先以安全审计员的身份检查这段代码的潜在漏洞然后以性能优化专家的身份提出改进建议。”2.2 任务拆解从模糊需求到清晰指令用户的需求往往是模糊的比如“帮我写个登录功能”。AI如果直接照此生成结果可能五花八门。任务拆解的目的就是把“做什么”细化成“一步步怎么做”。核心方法CRISP框架。这是我常用的一个心法Context背景、Request请求、Input输入、Steps步骤、Preference偏好。背景简要说明这个功能属于哪个项目、解决什么业务问题。例如“这是一个内部员工管理系统的登录模块需要对接公司已有的LDAP认证。”请求用明确的动词陈述核心任务。例如“编写一个安全的、基于JWT令牌的用户登录API端点。”输入明确给出AI需要处理的输入是什么。例如“输入是包含username和password字段的JSON请求体。”步骤将大任务分解为可执行的小步骤。例如“1. 验证请求体结构。2. 查询数据库核对用户凭证。3. 密码使用bcrypt比对。4. 生成JWT令牌。5. 返回令牌及基本用户信息。”偏好指定技术栈、代码风格、依赖库等。例如“使用Python FastAPI框架密码哈希用passlib[bcrypt]JWT使用python-jose[cryptography]。”避坑指南避免使用“优化一下”、“让它更好”这类模糊词汇。必须量化或具体化比如“将查询时间从200ms降低到50ms以内”、“将函数拆分为三个职责单一的小函数”。2.3 上下文注入提供“战场地图”AI没有记忆在单次对话中长上下文窗口也只是提供了更大的“草稿纸”你必须把必要的“战场地图”一次性给足。上下文包括代码上下文这是最重要的部分。通过粘贴相关代码文件、类定义、函数接口、数据结构如Pydantic模型、TypeScript接口让AI知道现有的代码环境。Claude Code这类插件的优势就在于能轻松读取整个项目文件但你在提示词中主动提供最核心的片段能极大提高准确率。项目上下文技术栈Python 3.11, React 18、框架版本、关键的配置文件如package.json,requirements.txt片段、数据库Schema描述。业务逻辑上下文一些特殊的业务规则。例如“用户状态为‘冻结’时即使密码正确也应拒绝登录并返回特定错误码。”注意事项一次性提供所有必要上下文。不要像挤牙膏一样AI根据不完整上下文生成的代码很可能在整合时出现接口不一致的问题。2.4 格式规范定义输出的“样子”你肯定不希望AI给你回复一大段散文里夹杂着代码。明确的格式要求能让你和AI的协作效率倍增。结构化输出直接要求AI以特定格式回复。例如请按以下格式回复1. 代码实现[完整的代码块]2. 关键逻辑解释[简要说明核心算法或流程]3. 注意事项[列出部署、运行时需要关注的点]代码标记明确要求使用Markdown代码块并指定语言。如“请将完整代码放在 python 代码块中。”非代码输出当需要设计思路、方案对比时可以要求使用表格。例如“请用表格对比方案A和方案B在性能、复杂度、可维护性三方面的优劣。”将这四大支柱组合起来一个强大的提示词骨架就诞生了。它不再是随意的聊天而是一份清晰的工作说明书。3. 进阶装配技巧从“能用”到“好用”掌握了四大支柱你写出的提示词已经能解决80%的问题。但要追求那20%的极致效率和质量还需要一些进阶技巧。3.1 思维链与分步指令引导AI“思考”对于复杂逻辑让AI直接给出最终答案容易出错。我们可以引导它展示思考过程这被称为“思维链”提示。基本用法在提示词中加入“让我们一步步思考”、“首先我们需要分析…”等引导语。例如对于一个复杂的数据处理任务你可以写“我们需要从原始数据中提取用户购买记录。请按以下步骤思考并给出答案1. 分析原始JSON数据的结构找出包含购买信息的字段。2. 设计一个数据清洗函数处理缺失值和异常格式。3. 编写转换函数将清洗后的数据映射到目标结构PurchaseRecord。请逐步完成。”优势这样做不仅能让最终结果更可靠而且当结果出现偏差时你可以从AI的“思考步骤”中快速定位问题出在哪个环节方便你调整提示词进行修正。3.2 示例驱动提供“参考答案”对于有明确格式要求或复杂模式的输出直接给AI一两个例子效果远超千言万语的描述。这就是“少样本学习”在提示词中的应用。如何操作在提示词中先明确任务然后写上“例如”接着给出一个完整的输入输出样例。任务请你根据以下用户故事生成对应的Gherkin语法测试场景。 用户故事作为一名用户我希望在登录失败时看到明确的错误提示以便我知道是用户名错误还是密码错误。 例如 输入用户故事“作为一名购物者我希望能将商品加入购物车以便后续统一结算。” 输出Gherkin场景Scenario: 添加商品到购物车 Given 用户浏览商品列表页 When 用户点击商品A的“加入购物车”按钮 Then 购物车图标数量应增加1 And 页面应显示“商品A已加入购物车”的提示消息现在请为上述登录失败的用户故事生成Gherkin场景。适用场景生成特定格式的代码如单元测试、配置模板、编写风格固定的文档如API文档、进行数据格式转换等。3.3 系统级约束与负面提示划定“禁区”除了告诉AI要做什么明确告诉它不要做什么同样重要这能有效避免生成无关、低质甚至有害的内容。系统级约束有些约束需要放在对话最开头或Claude Code的系统角色设置中贯穿整个会话。例如“在本对话中你生成的所有代码必须包含详细的注释解释关键算法和复杂逻辑。”、“请勿生成任何用于网络攻击、破解或侵犯隐私的代码。”负面提示针对当前任务的具体限制。例如“在实现这个排序算法时请不要使用内置的sort()函数请展示手动实现的逻辑。”、“解释概念时避免使用过于学术化的术语用比喻和生活中的例子来说明。”实操心得负面提示要具体。说“不要写低效代码”是无效的要说“避免使用时间复杂度高于O(n log n)的算法”或“禁止在循环内部执行数据库查询”。3.4 迭代与优化提示词也需要“调试”不要指望第一个提示词就完美无缺。将提示词工程视为一个迭代过程。初版生成基于四大支柱写出第一版提示词获取AI的回复。结果评估检查输出是否符合预期哪里不准确、不完整或多余归因分析是角色设定不准确任务步骤有歧义上下文不足还是格式混乱修改提示针对性地强化或修正提示词中的相应部分。例如如果AI忽略了错误处理就在“步骤”中明确加入“添加完整的异常处理逻辑”如果代码风格不符就在“偏好”中强调“遵循PEP 8规范”。重复直到获得满意结果。你可以保存这个优化后的提示词作为模板用于类似任务。4. 实战案例拆解装配一个完整的代码生成提示词让我们通过一个具体案例将上述所有技巧串联起来。假设我们需要Claude Code帮我们创建一个文件上传的API端点。初始模糊需求“帮我写个文件上传接口。”这个需求会带来各种不确定的结果。现在我们开始装配4.1 第一支柱角色设定你是一位资深Python后端工程师精通FastAPI框架对Web安全有深刻理解特别熟悉文件上传、验证和云存储集成。你的代码以健壮性、安全性和可维护性为首要目标。设计意图将AI定位在特定技术栈和安全敏感的领域引导其调用相关知识。4.2 第二支柱任务拆解使用CRISP框架背景这是“在线设计协作平台”的后端服务用户需要上传设计稿图片。请求创建一个支持图片文件上传的RESTful API端点。输入HTTP POST请求multipart/form-data格式包含一个名为file的文件字段以及可选的description文本字段。步骤验证上传文件是否为允许的图片类型仅限JPG, PNG, WebP。验证文件大小不超过10MB。为防止文件名冲突和路径遍历攻击在服务器端为文件生成一个唯一的随机文件名保留原始扩展名。将文件安全地保存到服务器的指定目录例如./uploads中。注意在生产环境中这一步通常改为上传至云存储如S3但本次实现本地存储逻辑。将文件信息生成后的文件名、原始文件名、MIME类型、大小、保存路径、上传时间记录到数据库这里简化先返回一个包含这些信息的JSON响应。实现完整的异常处理对文件类型错误、大小超限、保存失败等情况返回清晰、友好的HTTP错误响应。偏好使用FastAPI框架。使用Pydantic模型来定义响应结构。代码需包含详尽的文档字符串Docstring和关键逻辑的行内注释。遵循PEP 8风格。4.3 第三支柱上下文注入项目当前使用的主要依赖版本 - fastapi0.104.1 - python-multipart0.0.6 - pydantic2.5.0 当前项目结构中已有以下Pydantic模型可供你在响应模型中引用 python from pydantic import BaseModel from datetime import datetime class FileInfo(BaseModel): id: str # 生成的文件名不含路径 original_name: str mime_type: str size: int # 字节 saved_path: str uploaded_at: datetime### 4.4 第四支柱格式规范请按以下格式输出完整代码提供可直接放入main.py或类似路由文件的完整代码块。逻辑要点说明用几句话概括你实现中的安全措施和核心逻辑。运行与测试建议说明如何运行此端点并给出一个使用curl或httpie进行测试的命令示例。### 4.5 组合与发送 将以上所有部分按逻辑顺序组合就构成了我们最终发送给Claude Code的提示词。这个提示词清晰、具体、无歧义极大地提高了获得高质量、可直接使用代码的概率。 **最终组合提示词示例**你是一位资深Python后端工程师精通FastAPI框架对Web安全有深刻理解特别熟悉文件上传、验证和云存储集成。你的代码以健壮性、安全性和可维护性为首要目标。请为“在线设计协作平台”创建一个图片上传API端点。任务详情请求创建一个支持图片文件上传的RESTful API端点。输入HTTP POST请求multipart/form-data格式包含一个名为file的文件字段以及可选的description文本字段。实现步骤验证上传文件是否为允许的图片类型仅限JPG, PNG, WebP。验证文件大小不超过10MB。为防止文件名冲突和路径遍历攻击在服务器端为文件生成一个唯一的随机文件名如UUID保留原始扩展名。将文件安全地保存到服务器的./uploads目录中请确保在代码中处理目录不存在的情况。将文件信息生成后的文件名、原始文件名、MIME类型、大小、保存路径、上传时间封装返回。实现完整的异常处理对文件类型错误、大小超限、保存失败等情况返回清晰、友好的HTTP错误响应如400, 413, 500。技术偏好使用 FastAPI 框架。使用 Pydantic 模型定义响应结构。代码需包含详尽的文档字符串Docstring和关键逻辑的行内注释。遵循 PEP 8 风格。项目上下文依赖fastapi0.104.1, python-multipart0.0.6, pydantic2.5.0可复用的模型from pydantic import BaseModel from datetime import datetime class FileInfo(BaseModel): id: str # 生成的文件名不含路径 original_name: str mime_type: str size: int # 字节 saved_path: str uploaded_at: datetime输出格式要求请按以下格式回复完整代码提供可直接放入main.py的完整代码块。逻辑要点说明用几句话概括你实现中的安全措施和核心逻辑。运行与测试建议说明如何运行此端点并给出一个使用curl进行测试的命令示例。## 5. 避坑指南与常见问题排查 即使按照最佳实践装配提示词在实际操作中仍会遇到各种问题。以下是我总结的常见“坑点”及解决方案。 ### 5.1 问题AI生成的代码忽略了关键业务逻辑或边界条件 * **排查**检查你的“任务拆解-步骤”部分是否足够细致。AI只会执行你明确写出的或强烈暗示的指令。如果业务规则复杂必须逐条列出。 * **解决**将隐含条件显式化。不要写“检查用户权限”而要写“检查用户角色字段是否为‘admin’或‘editor’并且账户状态字段为‘active’”。 * **心得**把AI想象成一个极其严格但缺乏常识的新人程序员你需要编写一份毫无歧义的详细需求文档。 ### 5.2 问题AI陷入循环或不断追问细节 * **排查**通常是上下文不足或任务过于开放导致的。AI因为信息不够无法做出确定性的输出。 * **解决** 1. **补充上下文**提供更多的相关代码、数据结构定义、API文档链接。 2. **缩小范围**将一个大任务拆分成几个连续的小任务分多次对话完成。例如先让AI设计接口和数据模型你确认后再让它基于确认的模型编写具体实现。 3. **提供选择**对于有争议的设计点你可以给出2-3个选项让AI分析并推荐而不是让它凭空创造。例如“对于缓存策略你认为使用Redis缓存查询结果还是使用内存缓存如functools.lru_cache更合适请分别分析优缺点。” ### 5.3 问题代码风格或依赖与项目现有规范不符 * **排查**检查“偏好”和“上下文”部分是否明确指定了技术栈、版本和代码风格。 * **解决** * 在提示词开头就强调“请确保生成的代码与本项目现有代码风格保持一致。” * 直接粘贴一段项目中的典型代码作为“风格示例”。 * 明确拒绝某些做法“本项目禁止使用*进行通配符导入请使用显式导入。” * **心得**风格一致性是维护性的基础。在第一次为某个项目编写提示词时多花点时间定义好这些约束后续会省力很多。 ### 5.4 问题AI“捏造”了不存在的库或API * **现象**AI生成的代码使用了some_awesome_library但这个库根本不存在或者是AI根据训练数据“幻想”出来的。 * **解决** 1. **锁定依赖**在“偏好”或“上下文”中明确指定库的名称和**常用版本**。例如“使用pandas库处理数据版本号约为1.5.x。” 2. **要求验证**在提示词末尾加上“请只使用Python标准库和上述明确提到的第三方库。如果必须使用其他库请先询问。” 3. **事后审查**对于AI生成的代码尤其是涉及不熟悉依赖的部分务必进行快速的pip show 或查阅官方文档进行验证。 ### 5.5 问题提示词太长导致AI无法聚焦或丢失前文 * **背景**虽然Claude拥有长上下文窗口但过长的提示词仍可能让AI的注意力分散忘记最早的一些指令。 * **解决** * **结构化**使用清晰的标题如## 角色、## 任务和列表来组织提示词帮助AI解析。 * **优先级**将最核心的指令角色、核心任务、输出格式放在最前面和最末尾。 * **分而治之**对于极其复杂的任务不要试图在一个提示词中解决所有问题。建立“主提示词”定义整体架构然后通过后续对话使用“基于以上架构现在请实现XX模块…”的方式进行迭代开发。 装配一个高效的提示词就像是在编写一段能与AI精确协作的“元程序”。它需要的不是魔法而是严谨的工程思维、清晰的表达和对AI工作方式的理解。从明确角色开始一步步拆解任务注入充足的上下文并严格规范输出你就能将Claude Code从一个“有时灵有时不灵”的聊天伙伴转变为一个稳定、高效、可预测的编程协作者。这个过程本身也是对你自身逻辑思考和需求分析能力的一次绝佳锻炼。