有句话说得好好的工程师和差的工程师的区别不在于他们多聪明而在于他们有没有一份好的排障清单。这句话对 Prompt 工程也完全适用。最近三个月我在 Claude 社区的 Discord 里帮人调试 Prompt。最常见的情况是什么有人花了两个小时调 Prompt最后问题出在一个特别简单的地方——只需要改一句话。比如Claude 不用我上传的文件——问题是文件格式没指明同一个 Prompt 效果总是波动——问题是没有用示例Claude 给的答案不符合格式——问题是没有明确说明输出格式编码任务总是不完整——问题是没有设置合适的 effort 参数这些都是系统性的问题有规律可循。所以我花了一个周末整理了一份清单——10 种最常见的问题每个问题对应一个快速诊断和一句话修复方案。这份清单救了我好几次。现在我把它分享给你们。重要提示在用这份速查表之前强烈建议你先读前两期第一期讲的是基础框架清晰、背景、示例、输出控制第二期讲的是进阶技巧思考、Agent、4.7 新特性这份第三期是实战工具——它假设你已经理解了理论基础。如果你还没读过前两期这份清单可能会让你困惑。速查表10 种常见问题这个表格是这一期的核心。每个问题都对应一个症状、诊断和修复方案。问题 1输出太冗长有很多不必要的背景症状Claude 给的回答超过你需要的 2-3 倍长有大量解释、上下文、让我解释一下为什么只想要答案但得到了整个论文根本原因Claude 默认会解释得很详细。你没有明确说要简洁。一句话修复提供简洁、聚焦的回答。跳过非必要背景最小化示例。原理Claude 4.6/4.7 会识别这个指令自动调整语气。应用场景数据提取、快速查询、时间紧张的情况问题 2输出太短缺少关键细节症状Claude 的回答太简洁遗漏了重要信息代码示例不完整解释太简略你需要问追加问题根本原因effort参数太低或 Prompt 没有明确要求详细。一句话修复设置 effort: high 或 xhigh并在 Prompt 中加 提供完整、详细的回答包括所有必要的解释和代码示例。原理高 effort 让 Claude 花更多思想详细指导让 Claude 知道你想要什么。应用场景复杂问题、需要完整代码的编码任务、教学性内容问题 3输出不符合你要求的格式症状要求 JSON得到了 Markdown 表格要求结构化数据得到了段落格式完全不符合预期根本原因没有明确指定输出格式或格式说明不清晰。一句话修复用 XML 标签明确指定输出格式加上 2-3 个示例。详细修复output_format 你的回答必须是这个格式的 JSON { items: [ { name: string, value: number, status: active|inactive } ] } /output_format examples example output { items: [ {name: Item A, value: 100, status: active} ] } /example /examples原理XML 标签 具体示例 Claude 完全理解格式。应用场景数据提取、API 集成、需要结构化输出的任何任务问题 4Claude 不使用你上传的文件症状上传了文档Claude 说看不到上传了代码Claude 没有引用文件似乎没有被处理根本原因文件类型不支持或 Prompt 中没有明确说看我上传的文件。一句话修复在 Prompt 中明确说 请分析我上传的 [文件类型] 文件[文件名]。 在 Prompt 的结尾加 文件见下文或代码见下方或文档如下哪些文件格式支持✅ 代码.py, .js, .ts, .java, .go, .rs 等✅ 文本.md, .txt, .csv 等✅ 数据JSON, YAML, SQL 等✅ 图片.png, .jpg, .gif 等⚠️ PDF看得见但识别能力有限用 OCR 更好❌ 二进制.exe, .bin 等看不到应用场景代码审查、文档分析、数据提取问题 5同一个 Prompt 效果总是波动有时好有时坏症状上午用效果不错下午同样的 Prompt 效果变差有时 Claude 理解对了有时完全误解感觉像是运气不好根本原因Prompt 不够清晰或者没有用示例。Claude 没有足够的约束。一句话修复加 3-5 个 few-shot 示例展示你期望的输入/输出。详细修复原来的 Prompt从这段文本中提取关键词。改进后task 从文本中提取 3-5 个最相关的关键词。 /task examples example input Apple Inc. is a technology company founded in 1976 by Steve Jobs. /input output [Apple, technology, founded, Steve Jobs] /output /example example input Climate change is accelerating, causing extreme weather events. /input output [climate change, accelerating, extreme weather] /output /example /examples原理示例让 Claude 看到你真正想要什么消除歧义。应用场景任何需要稳定、一致输出的任务问题 6Claude 给建议而不是采取行动症状你想让 Claude 修改代码但它说你可以这样改你想让 Claude 创建文件但它只给了代码片段你想让 Claude 做事但它坚持给建议根本原因Prompt 用了能...吗或建议这样的措辞而不是祈使句。一句话修复改 Can you suggest... 为 Do... 改 How should I... 为 Heres how to... 在 Prompt 开头加default_to_action 块详细修复❌ 原来能帮我改进这个函数的性能吗✅ 改成改进这个函数的性能。列出你做出的改变及原因。或者加一个 System Promptdefault_to_action 默认情况下实施更改而不是仅建议。 如果用户的意图不清楚推断最可能的行动并进行。 /default_to_action原理Claude 理解做和建议是不同的意图。应用场景编码任务、内容生成、任何需要输出而不是建议的任务问题 7Claude 过度思考导致延迟太长Token 消耗太多症状简单问题也要等很久可能在做思考Token 消耗比预期多 2-3 倍速度特别慢根本原因effort参数太高或 Prompt 里有太多深入思考的激励。一句话修复降低 effort 参数 - 从 max 改成 xhigh - 从 xhigh 改成 high - 从 high 改成 medium如果任务不复杂或者在 Prompt 中加思考会增加延迟。仅在能显著改进答案时使用。有疑问时直接回答。原理Claude 会更谨慎地使用思考。应用场景成本敏感的应用、实时交互、简单查询问题 8Claude 生成的设计很 AI看起来通用、没有特色症状生成的网站设计看起来很模板化配色方案很常见紫色渐变、同色调字体选择很AI 标配Inter、Roboto根本原因Prompt 没有明确指定设计方向。Claude 4.7 有默认风格。一句话修复明确指定设计方向包括颜色、字体、风格的具体例子。 或者让 Claude 先提议 4 个方向你选一个再构建。详细修复❌ 原来设计一个现代的着陆页。✅ 改成设计着陆页。视觉方向冷单色调使用淡银灰色逐渐深化为蓝灰色。 字体方正、角度锐利的无衬线字体不是 Inter 或 Roboto。 布局清晰的水平分区居中留白充足。或者在构建前提议 4 个不同的视觉方向每个一行bg hex / accent hex / 字体名。 我会选一个然后你构建。原理具体指导 模糊指导。提议 直接做。应用场景设计生成、前端开发、任何需要有特色而不是模板化的视觉输出问题 9Claude 遗漏了重要的细节或要求症状生成的代码缺少错误处理写的文档缺少某些章节解决方案不完整根本原因Prompt 中的要求不够明确或被 Claude 忽视了。一句话修复把所有要求列成明确的检查清单用checklist标签。 在 Prompt 末尾加 完成前确保你已满足所有上述要求。详细修复requirements 你的代码必须 - [ ] 有完整的错误处理try/catch - [ ] 包括单元测试至少 3 个测试用例 - [ ] 支持 async/await 而不是 callback - [ ] 有 JSDoc 注释 - [ ] 处理边界情况空输入、null、极大值 /requirements 完成前确保所有检查清单项都已完成。原理显式的检查清单让 Claude 不容易遗漏。应用场景代码生成、完整项目、需要全面性的任何任务问题 10不知道该用哪个模型Opus vs Sonnet或哪个 effort 参数症状不确定现在的设置是否最优想降低成本但不知道能降多少想提升质量但不知道会增加多少开销根本原因没有一个清晰的选择矩阵。一句话修复用这个矩阵决策 任务类型 - 建议模型 Effort - 简单分类 - Haiku low - 标准查询 - Sonnet medium - 复杂推理 - Sonnet high - 编码任务 - Opus xhigh - 长 Agent - Opus high/xhigh 成本敏感- Sonnet medium (成本最优) 质量第一- Opus xhigh (质量最高)详细矩阵任务最佳模型推荐 Effort预期质量相对成本文本分类Haikulow85%1x问答Sonnetmedium90%1.5x摘要Sonnetmedium92%2x翻译Sonnethigh95%3x代码审查Opusxhigh98%8x代码生成Opusxhigh97%8x长 AgentOpushigh95%6x应用场景任何需要模型选择的应用实战案例库现在让我们看 4 个真实的案例展示如何用上面的原则。案例 1数据提取管道结构化输出背景从 100 份客户邮件中提取数据需要一致的 JSON 格式。挑战邮件格式多样信息完整度不一致需要 100% 准确性解决方案 Promptrole You are a data extraction specialist. Extract information accurately from emails. /role task Extract customer information from emails and output as JSON. /task schema { customer_name: string (required), company: string or null, email: string (email format), request_type: upgrade|cancel|support|other, deadline: string (YYYY-MM-DD or null), account_id: string or null, confidence: 0.0 to 1.0 } /schema instructions 1. If information is missing, use null (not empty string) 2. For dates, standardize to YYYY-MM-DD. If month/day unclear, use 01 3. For confidence: 1.0 explicitly stated, 0.75 reasoned inference, 0.5 uncertain, 0.25 guess 4. If you cannot extract a field with confidence 0.25, set to null 5. Do not make assumptions or invent information /instructions examples example input Hi, Im Jane Smith from Acme Corp. I want to upgrade my subscription by March 15, 2024. Account ID: ACC-12345. /input output { customer_name: Jane Smith, company: Acme Corp, email: null, request_type: upgrade, deadline: 2024-03-15, account_id: ACC-12345, confidence: 0.95 } /output /example example input Cancel Enterprise plan immediately. Account: ENC-99888. Going with another provider. — Bob /input output { customer_name: Bob, company: null, email: null, request_type: cancel, deadline: 2024-05-09, account_id: ENC-99888, confidence: 0.85 } /output /example /examples constraints - Process each email independently - Return valid JSON (no markdown) - Include confidence for each extraction - Report any ambiguities in your confidence score /constraints effort_level Use medium effort for this task. /effort_level Now process these emails: [用户粘贴的邮件列表]为什么这个 Prompt 强✅ Schema 完全明确 (null vs 空字符串)✅ 规则清晰日期格式、confidence 定义✅ 2 个示例覆盖不同场景✅ 输出格式用示例展示✅ 设置 effort: medium任务不复杂但需要一致预期结果准确率 95%格式 100% 一致案例 2代码审查 Agent找 Bug背景审查一个支付处理函数需要找出所有 Bug。挑战Bug 可能很隐蔽既要全面也要精准不能误报解决方案 Promptrole You are an expert code reviewer specializing in Python. Your job is to find bugs, not suggest improvements. /role context This code processes e-commerce payments. Correctness is critical — bugs directly impact revenue and compliance. The system handles prices, taxes, discounts, and refunds. /context task Find every bug, edge case, and security issue in the provided code. Report all findings, including ones youre uncertain about. Do not filter by severity — downstream review will prioritize. /task output_format Return a JSON array: [ { type: bug|edge_case|security, severity: critical|high|medium|low, location: line N, function name, description: Whats wrong, example: Example input that triggers the bug, impact: Business/user impact if unfixed, fix: How to fix it (pseudo-code okay) } ] /output_format instructions 1. Be thorough: Report edge cases like negative amounts, None values, type mismatches 2. Be precise: Include exact line numbers and function names 3. Dont filter: Its better to report something minor than miss a real bug 4. Explain clearly: A downstream team will review these findings 5. For each bug, provide a specific example input that triggers it /instructions effort_level Use xhigh effort for this review. Investigate thoroughly. /effort_level Code to review: [用户粘贴的代码]为什么这个 Prompt 强✅ 清晰的背景支付系统高风险✅ 明确说找 bug而不是改进✅ Effort: xhigh复杂任务需要深思✅ 输出格式明确JSON✅ 规则明确不过滤、要例子、要行号预期结果找到 85% 的真实 Bug假阳性很低案例 3长链条编码任务多步骤重构背景重构一个 5 文件的 Node.js 项目从 callback 转换到 async/await。挑战很长的任务容易中途迷失需要追踪哪些文件已完成需要验证没有破坏现有功能解决方案 Promptrole You are an expert Node.js developer tasked with refactoring legacy code. /role context This is a production Node.js application using callback-based async patterns. We need to convert it to async/await for better readability and maintainability. Preserving all existing functionality is critical. /context task Refactor this codebase from callbacks to async/await. Follow this process: 1. /plan mode: Analyze the codebase structure and create a refactoring plan 2. Execute: Refactor each file, testing after each change 3. Verify: Run all tests to ensure no behavior changed /task progress_tracking Save progress to PROGRESS.json after each file: { completed_files: [file1.js, file2.js], current_file: file3.js, current_step: analyzing, issues_found: [issue description], next_steps: [what comes next], test_status: all passed } /progress_tracking constraints 1. Use async/await, not promise chains 2. Preserve all existing behavior — tests must pass 3. Add proper error handling (try/catch) 4. Include JSDoc comments for all functions 5. Do NOT refactor parts you havent changed (avoid over-engineering) /constraints effort_level Use xhigh effort for this task. This is a complex refactor. /effort_level context_management Your context window will auto-compress when approaching limits. Do not stop early due to token budget. Save progress and continue when resuming. Always aim to complete the full refactor. /context_management [提供文件列表和要求]为什么这个 Prompt 强✅ 清晰的 3 步流程计划 → 执行 → 验证✅ 进度追踪JSON 格式便于恢复✅ 明确的约束不过度工程✅ Effort: xhigh复杂多步骤✅ 上下文管理说明告诉 Claude 可以跨越多个上下文窗口预期结果稳定完成长任务代码质量一致案例 4内容生成保持品牌声音背景为 SaaS 产品写 5 篇博客文章需要保持一致的品牌声音。挑战避免营销术语保持亲近感和专业性的平衡每篇文章需要一致的风格解决方案 Promptrole You write for [Brand Name], a developer-focused SaaS. Our voice is: expert but approachable, technical but clear, confident but not arrogant. /role brand_voice Guidelines: 1. Avoid marketing jargon: Never use revolutionary, game-changing, next-gen, cutting-edge 2. Show, dont tell: Use specific examples instead of claims 3. Be helpful: Explain the why not just the how 4. Stay genuine: Write like a senior engineer helping a colleague, not a sales pitch 5. Use data when possible: Back claims with numbers, not feelings Good opening: We tested 50 configurations and found... Bad opening: Were thrilled to announce a revolutionary solution... /brand_voice content_specifications Title: [topic] Audience: [backend engineers / devops / full-stack developers] Length: 1200-1500 words Tone: Professional but warm, educational, conversational Structure: - Hook (problem statement) - 3-4 key insights with examples - Practical implementation guide - Conclusion with next steps Include: - At least one code example - Links to relevant docs (but dont oversell) - 1-2 real-world numbers/metrics /content_specifications examples example article_opening When we switched to [solution], the most surprising discovery wasnt the performance gain— it was how much operational overhead disappeared. Heres what we learned testing this with 50 teams over 6 months. /article_opening analysisThis works because: 1) It hooks with curiosity (surprising discovery), 2) It implies authority (50 teams), 3) It promises practical value/analysis /example /examples effort_level Use high effort for this writing. Content quality matters. /effort_level Write an article about: [topic]为什么这个 Prompt 强✅ 清晰的品牌声音什么做、什么不做✅ 具体的反例不要说这个✅ 明确的结构和长度✅ 示例展示好的开场✅ Effort: high内容需要质量预期结果一致的品牌声音可直接发布的质量FAQ用户最常问的 5 个问题Q1我应该把 Prompt 放在 System 还是 User 消息中A一般规则System角色、通用指导方针、全局约束、品牌偏好、写作风格User这次特定任务、上下文、变量输入、实际数据对长、复杂的 Prompt分割通常更清晰。经验法则如果 Prompt 中有变化的部分用户上传的文件、不同的问题那部分放在 User。不变的框架性内容放在 System。Q2何时使用 few-shot 示例 vs 仅说明A如果以下任何一个是真的用示例输出格式很重要结构化数据、JSON、特定的文本格式任务涉及风格或风格品牌声音、写作风格、设计美学任务有正确和不太对的灰色区域分类、打分、评估你需要稳定、一致的输出如果任务很简单Python 怎样排序列表仅说明就够了。经验法则不确定时加 3 个示例。增加的 Token 很小但稳定性提升 30%。Q3Opus 4.7 vs Sonnet 4.6何时用哪一个A简单决策矩阵Opus 4.7编码、复杂推理、长 Agent、高风险任务、没有成本限制Sonnet 4.6快速响应必需、成本敏感、日常查询、分类、生成经验法则Sonnet 做 80%Opus 做 20%如果你每月 Claude 开销 用。如果500混合使用简单任务 Sonnet复杂任务 Opus。Q4如何知道现在的 Prompt 是否最优A用这个 3 步检查步骤 1测试基准用现在的 Prompt 运行 5 次记录成功率和平均 Token 消耗步骤 2逐个改进尝试一个改变加示例、改 effort、简化措辞再运行 5 次对比结果如果好转保留如果没改变回滚步骤 3持续监控每个月检查一次模型升级可能改变最优 Prompt记录什么有效什么无效最重要的指标成功率% 的运行产生有用输出一致性同一 Prompt 多次运行的结果差异Token 效率完成任务平均需要多少 TokenQ5升级 Claude 版本时我的 Prompt 会失效吗A大概率不会完全失效但可能变得不如以前优化。为什么因为新模型的行为改变了就像 4.6 → 4.7新模型可能更或更不激进地使用某些能力怎样应对升级后测试关键 Prompt用上面的 3 步检查按照新模型的推荐方式调整比如 4.7 推荐用 effort 参数而不是深入思考语言记录什么改变了这样你能更好地预测未来的升级经验数据按照官方最佳实践写的 Prompt升级时平均需要调整 10-20%。完全靠巧合写的 Prompt升级时需要调整 40%。进阶技巧Prompt 版本管理如果你有很多 Prompt建议做版本管理。这是一个简单的系统prompts/ ├── code-review-v1.md (Sonnet 4.5 时代的版本) ├── code-review-v2.md (4.6 优化的版本) ├── code-review-v3.md (4.7 优化的版本目前使用) ├── data-extraction-v1.md ├── data-extraction-v2.md └── ... changelog.md (记录每个版本的改变)Changelog 模板## code-review-v3 (2026-05-09) Changed for: Claude Opus 4.7 - Added effort: xhigh parameter - Removed think carefully language (now handled by effort) - Changed output to explicit JSON format - Added test example in instructions Performance: Bug detection rate improved from 82% to 94%这样做的好处你能看到什么改进最有效下次升级时可以参考历史改变可以快速回滚到旧版本如果新版本有问题最后的话从调试转向工程我注意到一个有趣的现象最开始用 Claude 的人都在调试Prompt——为什么这次不工作为什么这次和上次不一样但掌握了这套系统方法后他们转向了工程化Prompt——这个任务需要哪些约束用什么 effort 参数最优怎样做到 100% 可重复从调试到工程只需要三件事系统框架第一期讲的 6 层高级技巧第二期讲的 4.7 优化实战工具这一期的清单和案例现在你三样都有了。资源和下一步想深入学习官方文档https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/社区 Discordhttps://discord.com/invite/anthropic更多案例GitHub 上搜 claude-prompts想追踪 Claude 的更新官方新闻https://www.anthropic.com/newsTwitterclaudeai模型更新日志https://platform.claude.com/docs/changelog想分享你的经验在评论区告诉我你调试过的最有意思的 Prompt分享一个终于搞定了的时刻完成清单恭喜你看到这里。如果你想充分应用这三期的内容这是一个清单☐ 读过第一期基础框架☐ 读过第二期4.7 优化☐ 浏览过这一期的 10 个问题☐ 挑一个最接近你的症状用修复方案试过了☐ 用一个案例模板改进了你自己的 Prompt☐ 用 3 步检查方法测试了改进效果☐ 在 Discord 或评论区分享了你的发现都做完了恭喜——你现在已经掌握了专业级别的 Prompt 工程。回顾三期内容期数标题核心内容你学到了什么第一期你的 Prompt 调不好其实根本不是运气6 层框架的前 3 层清晰、背景、示例、格式、工具使用第二期升级到 Opus 4.7 的 5 个改法思考、Agent、4.7 新特性怎样用新模型旧 Prompt 需要怎样改第三期Prompt 调试速查表10 个问题 4 个案例 FAQ实战工具、快速诊断、版本管理感谢你追完了这三期。希望这套系统方法能帮助你从Prompt 工程师升级到Prompt 系统设计师。大功告成