Back to Details

ai-prompt-engineering

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Prompt Engineering — Operational Skill

提示词工程 — 工程化实践技能

Modern Best Practices (January 2026): versioned prompts, explicit output contracts, regression tests, and safety threat modeling for tool/RAG prompts (OWASP LLM Top 10: https://owasp.org/www-project-top-10-for-large-language-model-applications/).
This skill provides operational guidance for building production-ready prompts across standard tasks, RAG workflows, agent orchestration, structured outputs, hidden reasoning, and multi-step planning.
All content is operational, not theoretical. Focus on patterns, checklists, and copy-paste templates.
2026年1月现代最佳实践：版本化提示词、明确的输出契约、回归测试，以及针对工具/RAG提示词的安全威胁建模（OWASP LLM十大风险：https://owasp.org/www-project-top-10-for-large-language-model-applications/）。
本技能为构建生产就绪型提示词提供工程化指导，覆盖标准任务、RAG工作流、Agent编排、结构化输出、隐藏推理以及多步骤规划等场景。
所有内容均为工程化实践，而非理论知识。重点关注模式、检查清单和可直接复制的模板。

Quick Start (60 seconds)

快速入门（60秒）

  1. Pick a pattern from the decision tree (structured output, extractor, RAG, tools/agent, rewrite, classification).
  2. Start from a template in 
    assets/
    and fill in 
    TASK
    , 
    INPUT
    , 
    RULES
    , and 
    OUTPUT FORMAT
    .
  3. Add guardrails: instruction/data separation, “no invented details”, missing → 
    null
    /explicit missing.
  4. Add validation: JSON parse check, schema check, citations check, post-tool checks.
  5. Add evals: 10–20 cases while iterating, 50–200 before release, plus adversarial injection cases.
  1. 从决策树中选择合适的模式（结构化输出、提取器、RAG、工具/Agent、重写、分类）。
  2. 从
    assets/
    目录下的模板开始，填充
    TASK
    、
    INPUT
    、
    RULES
    和
    OUTPUT FORMAT
    字段。
  3. 添加防护措施：指令与数据分离、“不得编造细节”、缺失信息返回
    null
    /明确标注缺失。
  4. 添加验证：JSON解析检查、Schema校验、引用检查、工具调用后检查。
  5. 添加评估：迭代过程中准备10-20个测试用例，发布前准备50-200个测试用例，同时包含对抗性注入测试用例。

Model Notes (2026)

模型注意事项（2026年）

This skill includes Claude Code + Codex CLI optimizations:
  • Action directives: Frame for implementation, not suggestions
  • Parallel tool execution: Independent tool calls can run simultaneously
  • Long-horizon task management: State tracking, incremental progress, context compaction resilience
  • Positive framing: Describe desired behavior rather than prohibitions
  • Style matching: Prompt formatting influences output style
  • Domain-specific patterns: Specialized guidance for frontend, research, and agentic coding
  • Style-adversarial resilience: Stress-test refusals with poetic/role-play rewrites; normalize or decline stylized harmful asks before tool use
Prefer “brief justification” over requesting chain-of-thought. When using private reasoning patterns, instruct: think internally; output only the final answer.
本技能包含针对Claude Code + Codex CLI的优化建议：
  • 行动指令：以实现为目标构建指令，而非仅给出建议
  • 并行工具执行：独立的工具调用可同时运行
  • 长周期任务管理：状态跟踪、增量进度、上下文压缩韧性
  • 正向表述：描述期望的行为而非禁止的行为
  • 风格匹配：提示词格式会影响输出风格
  • 领域特定模式：针对前端、研究和Agent化编码的专业指导
  • 风格对抗韧性：通过诗意/角色扮演式重写进行拒绝策略压力测试；在工具调用前规范化或拒绝风格化的有害请求
优先使用“简短理由说明”而非请求思维链。使用私有推理模式时，需指令：仅在内部思考；仅输出最终答案。

Quick Reference

快速参考

TaskPattern to UseKey ComponentsWhen to Use
Machine-parseable outputStructured OutputJSON schema, "JSON-only" directive, no proseAPI integrations, data extraction
Field extractionDeterministic ExtractorExact schema, missing->null, no transformationsForm data, invoice parsing
Use retrieved contextRAG WorkflowContext relevance check, chunk citations, explicit missing infoKnowledge bases, documentation search
Internal reasoningHidden Chain-of-ThoughtInternal reasoning, final answer onlyClassification, complex decisions
Tool-using agentTool/Agent PlannerPlan-then-act, one tool per turnMulti-step workflows, API calls
Text transformationRewrite + ConstrainStyle rules, meaning preservation, format specContent adaptation, summarization
ClassificationDecision TreeOrdered branches, mutually exclusive, JSON resultRouting, categorization, triage
任务适用模式核心组件使用场景
机器可解析输出结构化输出JSON Schema、“仅输出JSON”指令、无散文式内容API集成、数据提取
字段提取确定性提取器精确Schema、缺失值返回null、无转换操作表单数据、发票解析
使用检索到的上下文RAG工作流上下文相关性检查、块引用、明确标注缺失信息知识库、文档搜索
内部推理隐藏思维链内部推理、仅输出最终答案分类、复杂决策
使用工具的Agent工具/Agent规划器先规划后执行、每轮调用一个工具多步骤工作流、API调用
文本转换重写与约束风格规则、语义保留、格式规范内容适配、摘要生成
分类决策树有序分支、互斥规则、JSON结果路由、分类、分流

Decision Tree: Choosing the Right Pattern

决策树：选择合适的模式

text
User needs: [Prompt Type]
  |-- Output must be machine-readable?
  |     |-- Extract specific fields only? -> **Deterministic Extractor Pattern**
  |     `-- Generate structured data? -> **Structured Output Pattern (JSON)**
  |
  |-- Use external knowledge?
  |     `-- Retrieved context must be cited? -> **RAG Workflow Pattern**
  |
  |-- Requires reasoning but hide process?
  |     `-- Classification or decision task? -> **Hidden Chain-of-Thought Pattern**
  |
  |-- Needs to call external tools/APIs?
  |     `-- Multi-step workflow? -> **Tool/Agent Planner Pattern**
  |
  |-- Transform existing text?
  |     `-- Style/format constraints? -> **Rewrite + Constrain Pattern**
  |
  `-- Classify or route to categories?
        `-- Mutually exclusive rules? -> **Decision Tree Pattern**
text
用户需求: [提示词类型]
  |-- 输出必须是机器可读的？
  |     |-- 仅提取特定字段？ -> **确定性提取器模式**
  |     `-- 生成结构化数据？ -> **结构化输出模式（JSON）**
  |
  |-- 需要使用外部知识？
  |     `-- 检索到的上下文必须被引用？ -> **RAG工作流模式**
  |
  |-- 需要推理但隐藏过程？
  |     `-- 分类或决策任务？ -> **隐藏思维链模式**
  |
  |-- 需要调用外部工具/API？
  |     `-- 多步骤工作流？ -> **工具/Agent规划器模式**
  |
  |-- 转换现有文本？
  |     `-- 有风格/格式约束？ -> **重写与约束模式**
  |
  `-- 分类或路由到不同类别？
        `-- 规则互斥？ -> **决策树模式**

Copy/Paste: Minimal Prompt Skeletons

可直接复制的最简提示词骨架

1) Generic "output contract" skeleton

1) 通用“输出契约”骨架

text
TASK:
{{one_sentence_task}}

INPUT:
{{input_data}}

RULES:
- Follow TASK exactly.
- Use only INPUT (and tool outputs if tools are allowed).
- No invented details. Missing required info -> say what is missing.
- Keep reasoning hidden.
- Follow OUTPUT FORMAT exactly.

OUTPUT FORMAT:
{{schema_or_format_spec}}
text
TASK:
{{one_sentence_task}}

INPUT:
{{input_data}}

RULES:
- 严格遵循TASK要求。
- 仅使用INPUT（若允许使用工具则包含工具输出）。
- 不得编造细节。缺失必要信息时，说明缺失内容。
- 隐藏推理过程。
- 严格遵循OUTPUT FORMAT要求。

OUTPUT FORMAT:
{{schema_or_format_spec}}

2) Tool/agent skeleton (deterministic)

2) 确定性工具/Agent骨架

text
AVAILABLE TOOLS:
{{tool_signatures_or_names}}

WORKFLOW:
- Make a short plan.
- Call tools only when required to complete the task.
- Validate tool outputs before using them.
- If the environment supports parallel tool calls, run independent calls in parallel.
text
可用工具:
{{tool_signatures_or_names}}

工作流:
- 制定简短计划。
- 仅在完成任务必需时调用工具。
- 使用工具输出前先进行验证。
- 若环境支持并行工具调用，可同时运行独立的调用请求。

3) RAG skeleton (grounded)

3) 基于RAG的骨架（落地版）

text
RETRIEVED CONTEXT:
{{chunks_with_ids}}

RULES:
- Use only retrieved context for factual claims.
- Cite chunk ids for each claim.
- If evidence is missing, say what is missing.
text
检索到的上下文:
{{chunks_with_ids}}

规则:
- 事实性声明仅使用检索到的上下文。
- 每个声明需引用块ID。
- 若缺少证据，说明缺失内容。

Operational Checklists

工程化检查清单

Use these references when validating or debugging prompts:
  • frameworks/shared-skills/skills/ai-prompt-engineering/references/quality-checklists.md
  • frameworks/shared-skills/skills/ai-prompt-engineering/references/production-guidelines.md
验证或调试提示词时可参考以下文档：
  • frameworks/shared-skills/skills/ai-prompt-engineering/references/quality-checklists.md
  • frameworks/shared-skills/skills/ai-prompt-engineering/references/production-guidelines.md

Context Engineering (2026)

上下文工程（2026年）

True expertise in prompting extends beyond writing instructions to shaping the entire context in which the model operates. Context engineering encompasses:
  • Conversation history: What prior turns inform the current response
  • Retrieved context (RAG): External knowledge injected into the prompt
  • Structured inputs: JSON schemas, system/user message separation
  • Tool outputs: Results from previous tool calls that shape next steps
真正的提示词专业能力不仅限于编写指令，还包括塑造模型运行的整个上下文环境。上下文工程涵盖：
  • 对话历史：哪些之前的对话回合会影响当前响应
  • 检索到的上下文（RAG）：注入到提示词中的外部知识
  • 结构化输入：JSON Schema、系统/用户消息分离
  • 工具输出：之前工具调用的结果会影响后续步骤

Context Engineering vs Prompt Engineering

上下文工程 vs 提示词工程

AspectPrompt EngineeringContext Engineering
FocusInstruction textFull input pipeline
ScopeSingle promptRAG + history + tools
OptimizationWord choice, structureInformation architecture
GoalClear instructionsOptimal context window
维度提示词工程上下文工程
关注点指令文本完整输入管道
范围单个提示词RAG + 历史 + 工具
优化方向措辞、结构信息架构
目标清晰的指令最优上下文窗口

Key Context Engineering Patterns

核心上下文工程模式

1. Context Prioritization: Place most relevant information first; models attend more strongly to early context.
2. Context Compression: Summarize history, truncate tool outputs, select most relevant RAG chunks.
3. Context Separation: Use clear delimiters (
<system>
, 
<user>
, 
<context>
) to separate instruction types.
4. Dynamic Context: Adjust context based on task complexity - simple tasks need less context, complex tasks need more.
1. 上下文优先级：将最相关的信息放在最前面；模型对早期上下文的关注度更高。
2. 上下文压缩：总结历史对话、截断工具输出、选择最相关的RAG块。
3. 上下文分离：使用明确的分隔符（
<system>
、
<user>
、
<context>
）区分不同类型的指令。
4. 动态上下文：根据任务复杂度调整上下文——简单任务需要更少上下文，复杂任务需要更多。

Core Concepts vs Implementation Practices

核心概念 vs 实现实践

Core Concepts (Vendor-Agnostic)

核心概念（与厂商无关）

  • Prompt contract: inputs, allowed tools, output schema, max tokens, and refusal rules.
  • Context engineering: conversation history, RAG context, tool outputs, and structured inputs shape model behavior.
  • Determinism controls: temperature/top_p, constrained decoding/structured outputs, and strict formatting.
  • Cost & latency budgets: prompt length and max output drive tokens and tail latency; enforce hard limits and measure p95/p99.
  • Evaluation: golden sets + regression gates + A/B + post-deploy monitoring.
  • Security: prompt injection, data exfiltration, and tool misuse are primary threats (OWASP LLM Top 10: https://owasp.org/www-project-top-10-for-large-language-model-applications/).
  • 提示词契约：输入、允许使用的工具、输出Schema、最大Token数和拒绝规则。
  • 上下文工程：对话历史、RAG上下文、工具输出和结构化输入共同塑造模型行为。
  • 确定性控制：temperature/top_p、约束解码/结构化输出、严格格式要求。
  • 成本与延迟预算：提示词长度和最大输出长度决定Token消耗和尾部延迟；需强制执行硬限制并测量p95/p99指标。
  • 评估：黄金测试集 + 回归门控 + A/B测试 + 部署后监控。
  • 安全：提示词注入、数据泄露和工具滥用是主要威胁（OWASP LLM十大风险：https://owasp.org/www-project-top-10-for-large-language-model-applications/）。

Implementation Practices (Model/Platform-Specific)

实现实践（与模型/平台相关）

Do / Avoid

建议/禁忌

Do
  • Do keep prompts small and modular; centralize shared fragments (policies, schemas, style).
  • Do add a prompt eval harness and block merges on regressions.
  • Do prefer "brief justification" over requesting chain-of-thought; treat hidden reasoning as model-internal.
Avoid
  • Avoid prompt sprawl (many near-duplicates with no owner or tests).
  • Avoid brittle multi-step chains without intermediate validation.
  • Avoid mixing policy and product copy in the same prompt (harder to audit and update).
建议
  • 保持提示词精简且模块化；集中管理共享片段（策略、Schema、风格）。
  • 添加提示词评估框架，出现回归时阻止合并。
  • 优先使用“简短理由说明”而非请求思维链；将隐藏推理视为模型内部行为。
禁忌
  • 避免提示词泛滥（大量近乎重复的提示词，无所有者或测试）。
  • 避免脆弱的多步骤链，无中间验证环节。
  • 避免在同一个提示词中混合策略和产品文案（难以审计和更新）。

Navigation: Core Patterns

导航：核心模式

  • Core Patterns - 7 production-grade prompt patterns
    • Structured Output (JSON), Deterministic Extractor, RAG Workflow
    • Hidden Chain-of-Thought, Tool/Agent Planner, Rewrite + Constrain, Decision Tree
    • Each pattern includes structure template and validation checklist
  • 核心模式 - 7种生产级提示词模式
    • 结构化输出（JSON）、确定性提取器、RAG工作流
    • 隐藏思维链、工具/Agent规划器、重写与约束、决策树
    • 每种模式均包含结构模板和验证检查清单

Navigation: Best Practices

导航：最佳实践

  • Best Practices (Core) - Foundation rules for production-grade prompts
    • System instruction design, output contract specification, action directives
    • Context handling, error recovery, positive framing, style matching, style-adversarial red teaming
    • Anti-patterns, Claude 4+ specific optimizations
  • Production Guidelines - Deployment and operational guidance
    • Evaluation & testing (Prompt CI/CD), model parameters, few-shot selection
    • Safety & guardrails, conversation memory, context compaction resilience
    • Answer engineering, decomposition, multilingual/multimodal, benchmarking
    • CI/CD Tools (2026): Promptfoo, DeepEval integration patterns
    • Security (2026): PromptGuard 4-layer defense, Microsoft Prompt Shields, taint tracking
  • Quality Checklists - Validation checklists before deployment
    • Prompt QA, JSON validation, agent workflow checks
    • RAG workflow, safety & security, performance optimization
    • Testing coverage, anti-patterns, quality score rubric
  • Domain-Specific Patterns - Claude 4+ optimized patterns for specialized domains
    • Frontend/visual code: Creativity encouragement, design variations, micro-interactions
    • Research tasks: Success criteria, verification, hypothesis tracking
    • Agentic coding: No speculation rule, principled implementation, investigation patterns
    • Cross-domain best practices and quality modifiers
  • 核心最佳实践 - 生产级提示词的基础规则
    • 系统指令设计、输出契约规范、行动指令
    • 上下文处理、错误恢复、正向表述、风格匹配、风格对抗红队测试
    • 反模式、Claude 4+特定优化
  • 生产指南 - 部署与工程化指导
    • 评估与测试（提示词CI/CD）、模型参数、少样本选择
    • 安全与防护、对话记忆、上下文压缩韧性
    • 答案工程、分解、多语言/多模态、基准测试
    • CI/CD工具（2026年）：Promptfoo、DeepEval集成模式
    • 安全（2026年）：PromptGuard 4层防御、Microsoft Prompt Shields、污点跟踪
  • 质量检查清单 - 部署前的验证检查清单
    • 提示词QA、JSON验证、Agent工作流检查
    • RAG工作流、安全与合规、性能优化
    • 测试覆盖、反模式、质量评分标准
  • 领域特定模式 - 针对Claude 4+优化的特定领域模式
    • 前端/可视化代码：创意鼓励、设计变体、微交互
    • 研究任务：成功标准、验证、假设跟踪
    • Agent化编码：无猜测规则、原则性实现、调查模式
    • 跨领域最佳实践和质量调整

Navigation: Specialized Patterns

导航：专业模式

  • RAG Patterns - Retrieval-augmented generation workflows
    • Context grounding, chunk citation, missing information handling
  • Agent and Tool Patterns - Tool use and agent orchestration
    • Plan-then-act workflows, tool calling, multi-step reasoning, generate-verify-revise chains
    • Multi-Agent Orchestration (2026): centralized, handoff, federated patterns; plan-and-execute (90% cost reduction)
  • Extraction Patterns - Deterministic field extraction
    • Schema-based extraction, null handling, no hallucinations
  • Reasoning Patterns (Hidden CoT) - Internal reasoning without visible output
    • Hidden reasoning, final answer only, classification workflows
    • Extended Thinking API (Claude 4+): budget management, think tool, multishot patterns
  • Additional Patterns - Extended prompt engineering techniques
    • Advanced patterns, edge cases, optimization strategies
  • RAG模式 - 检索增强生成工作流
    • 上下文落地、块引用、缺失信息处理
  • Agent与工具模式 - 工具使用与Agent编排
    • 先规划后执行工作流、工具调用、多步骤推理、生成-验证-修订链
    • 多Agent编排（2026年）：集中式、交接式、联邦式模式；规划执行模式（成本降低90%）
  • 提取模式 - 确定性字段提取
    • 基于Schema的提取、空值处理、无幻觉
  • 推理模式（隐藏思维链） - 内部推理，无可见输出
    • 隐藏推理、仅输出最终答案、分类工作流
    • 扩展思考API（Claude 4+）：预算管理、思考工具、少样本模式
  • 其他模式 - 进阶提示词工程技术
    • 高级模式、边缘案例、优化策略

Navigation: Templates

导航：模板

Templates are copy-paste ready and organized by complexity:
模板可直接复制使用，按复杂度分类：

Quick Templates

快速模板

  • Quick Template - Fast, minimal prompt structure
  • 快速模板 - 快速、极简的提示词结构

Standard Templates

标准模板

  • Standard Template - Production-grade operational prompt
  • Agent Template - Tool-using agent with planning
  • RAG Template - Retrieval-augmented generation
  • Chain-of-Thought Template - Hidden reasoning pattern
  • JSON Extractor Template - Deterministic field extraction
  • Prompt Evaluation Template - Regression tests, A/B testing, rollout gates
  • 标准模板 - 生产级工程化提示词
  • Agent模板 - 带规划功能的工具型Agent
  • RAG模板 - 检索增强生成
  • 思维链模板 - 隐藏推理模式
  • JSON提取器模板 - 确定性字段提取
  • 提示词评估模板 - 回归测试、A/B测试、发布门控

External Resources

外部资源

External references are listed in data/sources.json:
  • Official documentation (OpenAI, Anthropic, Google)
  • LLM frameworks (LangChain, LlamaIndex)
  • Vector databases (Pinecone, Weaviate, FAISS)
  • Evaluation tools (OpenAI Evals, HELM)
  • Safety guides and standards
  • RAG and retrieval resources
外部参考列于data/sources.json：
  • 官方文档（OpenAI、Anthropic、Google）
  • LLM框架（LangChain、LlamaIndex）
  • 向量数据库（Pinecone、Weaviate、FAISS）
  • 评估工具（OpenAI Evals、HELM）
  • 安全指南与标准
  • RAG与检索资源

Freshness Rule (2026)

时效性规则（2026年）

When asked for “latest” prompting recommendations, prefer provider docs and standards from 
data/sources.json
. If web search is unavailable, state the constraint and avoid overconfident “current best” claims.
当被问及“最新”提示词建议时，优先参考
data/sources.json
中的厂商文档和标准。若无法进行网页搜索，需说明限制条件，避免过度自信地声称“当前最佳实践”。

Related Skills

相关技能

This skill provides foundational prompt engineering patterns. For specialized implementations:
AI/LLM Skills:
  • AI Agents Development - Production agent patterns, MCP integration, orchestration
  • AI LLM Engineering - LLM application architecture and deployment
  • AI LLM RAG Engineering - Advanced RAG pipelines and chunking strategies
  • AI LLM Search & Retrieval - Search optimization, hybrid retrieval, reranking
  • AI LLM Development - Fine-tuning, evaluation, dataset creation
Software Development Skills:
  • Software Architecture Design - System design patterns
  • Software Backend - Backend implementation
  • Foundation API Design - API design and contracts
本技能提供基础提示词工程模式。如需专业实现，可参考：
AI/LLM技能:
  • AI Agent开发 - 生产级Agent模式、MCP集成、编排
  • AI LLM工程 - LLM应用架构与部署
  • AI LLM RAG工程 - 进阶RAG管道与分块策略
  • AI LLM搜索与检索 - 搜索优化、混合检索、重排序
  • AI LLM开发 - 微调、评估、数据集创建
软件开发技能:
  • 软件架构设计 - 系统设计模式
  • 软件后端 - 后端实现
  • 基础API设计 - API设计与契约

Usage Notes

使用说明

For Claude Code:
  • Reference this skill when building prompts for agents, commands, or integrations
  • Use Quick Reference table for fast pattern lookup
  • Follow Decision Tree to select appropriate pattern
  • Validate outputs with Quality Checklists before deployment
  • Use templates as starting points, customize for specific use cases
For Codex CLI:
  • Use the same patterns and templates; adapt tool-use wording to the local tool interface
  • For long-horizon tasks, track progress explicitly (a step list/plan) and update it as work completes
  • Run independent reads/searches in parallel when the environment supports it; keep writes/edits serialized
  • AGENTS.md Integration: Place project-specific prompt guidance in AGENTS.md files at global (~/.codex/AGENTS.md), project-level (./AGENTS.md), or subdirectory scope for layered instructions
  • Reasoning Effort: Use 
    medium
    for interactive coding (default), 
    high
    /
    xhigh
    for complex autonomous multi-hour tasks
针对Claude Code:
  • 构建Agent、命令或集成的提示词时可参考本技能
  • 使用快速参考表快速查找模式
  • 遵循决策树选择合适的模式
  • 部署前使用质量检查清单验证输出
  • 以模板为起点，根据具体用例进行定制
针对Codex CLI:
  • 使用相同的模式和模板；调整工具使用措辞以适配本地工具接口
  • 对于长周期任务，需显式跟踪进度（步骤列表/计划），并在工作完成时更新
  • 若环境支持，并行运行独立的读取/搜索操作；保持写入/编辑操作序列化
  • AGENTS.md集成：将项目特定的提示词指导放置在全局（~/.codex/AGENTS.md）、项目级（./AGENTS.md）或子目录级的AGENTS.md文件中，实现分层指令
  • 推理力度：交互式编码使用
    medium
    （默认），复杂的自主多小时任务使用
    high
    /
    xhigh