提示词模板：工程化复用体系

为什么需要提示词工程化？

从"随手写 Prompt"到"工程化资产"

大多数开发者使用 AI 工具的方式是：每次需要时临时构造一个 Prompt，用完即丢。这种方式有几个明显问题：

• 同样的任务每次结果质量不稳定（Prompt 写得好不好差异很大）
• 好的 Prompt 技巧没有沉淀，团队成员各自摸索
• 无法对 Prompt 进行版本管理和效果追踪
• 新人入职时没有 AI 工具使用规范可以参考

提示词工程化的核心思想是：把优质的 Prompt 当作代码一样管理——存储、版本控制、测试、复用。

提示词模板设计

变量占位符系统

一个好的 Prompt 模板应该包含可替换的变量，使其能够适用于不同场景：

# 模板格式约定
# 使用 {变量名} 作为占位符
# 使用 {变量名:默认值} 表示有默认值的变量
# 使用 [[可选块]] 表示可选内容

# CRUD API 生成模板
生成一个 {language} {framework} 的 {resource_name} CRUD API。

技术规范：
- 语言版本：{language_version:最新稳定版}
- 数据库：{database:PostgreSQL}
- 认证方式：{auth_method:JWT}

API 端点：
- GET /{resource_plural} - 列表（支持分页和筛选）
- GET /{resource_plural}/{id} - 获取单个
- POST /{resource_plural} - 创建
- PUT /{resource_plural}/{id} - 更新（完整替换）
- PATCH /{resource_plural}/{id} - 部分更新
- DELETE /{resource_plural}/{id} - 删除

数据模型字段：
{fields}

[[包含软删除（deleted_at 字段）]]
[[包含审计字段（created_by, updated_by）]]

请生成：
1. 数据模型定义
2. 请求/响应 Schema（包含验证）
3. 路由处理器（包含错误处理）
4. 服务层逻辑
5. 基础单元测试

Python 模板引擎管理

# prompts/template_engine.py
from pathlib import Path
import re
from dataclasses import dataclass
from typing import Optional


@dataclass
class PromptTemplate:
    name: str
    template: str
    version: str
    category: str
    description: str

    def render(self, **kwargs) -> str:
        """渲染模板，替换变量并处理可选块"""
        result = self.template

        # 处理默认值变量 {var:default}
        for match in re.finditer(r'\{(\w+):([^}]+)\}', result):
            var_name, default = match.group(1), match.group(2)
            value = kwargs.get(var_name, default)
            result = result.replace(match.group(0), str(value))

        # 处理可选块 [[content]]
        optional_blocks = re.findall(r'\[\[(.+?)\]\]', result)
        for block in optional_blocks:
            block_key = block.strip().lower().replace(' ', '_')
            if kwargs.get(block_key, False):
                result = result.replace(f'[[{block}]]', block)
            else:
                result = result.replace(f'[[{block}]]', '')

        # 替换普通变量
        for key, value in kwargs.items():
            result = result.replace(f'{{{key}}}', str(value))

        return result.strip()


class PromptLibrary:
    def __init__(self, prompts_dir: str = "prompts"):
        self.prompts_dir = Path(prompts_dir)
        self._cache: dict[str, PromptTemplate] = {}

    def get(self, name: str) -> PromptTemplate:
        if name not in self._cache:
            self._cache[name] = self._load(name)
        return self._cache[name]

    def render(self, name: str, **kwargs) -> str:
        return self.get(name).render(**kwargs)


# 使用示例
library = PromptLibrary()
prompt = library.render(
    "crud_api",
    language="Python",
    framework="FastAPI",
    resource_name="Product",
    resource_plural="products",
    fields="name: str, price: Decimal, category_id: int",
    包含软删除=True
)

常用模板集合

单元测试生成模板

# 模板：generate_unit_tests.txt

你是一位测试专家，请为以下 {language} 函数生成全面的单元测试。

测试框架：{test_framework:pytest}
Mock 框架：{mock_framework:pytest-mock}

函数代码：
```{language}
{function_code}
```

要求：
1. 覆盖所有正常路径（Happy Path）
2. 覆盖所有边界条件（空值、极值、边界值）
3. 覆盖所有异常路径（各种错误情况）
4. 每个测试有清晰的描述性名称和注释
5. 使用 Arrange/Act/Assert 三段式结构
6. Mock 所有外部依赖（数据库、HTTP 请求等）

额外要求：{additional_requirements:无}

目标代码覆盖率：{coverage_target:90%}

API 文档生成模板

# 模板：generate_api_doc.txt

请为以下 API 端点生成 OpenAPI/Swagger 格式的文档。

API 框架：{framework}
代码：
```{language}
{api_code}
```

生成内容：
1. 端点摘要和详细描述
2. 所有请求参数（path/query/body）的类型、必填性、描述
3. 所有可能的响应码及响应体结构
4. 请求和响应示例（JSON 格式）
5. 安全认证要求（如果有）

输出格式：OpenAPI 3.0 YAML

数据库迁移生成模板

# 模板：generate_db_migration.txt

请根据以下变更需求，生成 {orm_framework} 数据库迁移脚本。

当前数据模型：
```python
{current_model}
```

需要的变更：
{changes_description}

要求：
1. 生成 up 迁移（应用变更）
2. 生成 down 迁移（回滚变更）
3. 考虑已有数据的兼容性（不要破坏现有数据）
4. 为新字段提供合理的默认值（如果是 NOT NULL 字段）
5. 在注释中说明每个步骤的目的

版本化 Prompt 管理（Git 管理）

目录结构

prompts/
├── README.md              # 模板库说明
├── CHANGELOG.md           # 模板更新历史
├── categories/
│   ├── code_review/       # 代码审查类
│   │   ├── security.md
│   │   ├── performance.md
│   │   └── maintainability.md
│   ├── code_generation/   # 代码生成类
│   │   ├── crud_api.md
│   │   ├── unit_tests.md
│   │   └── migration.md
│   ├── documentation/     # 文档类
│   │   ├── api_doc.md
│   │   ├── readme.md
│   │   └── changelog.md
│   └── debugging/         # 调试类
│       ├── error_analysis.md
│       └── performance_profiling.md
└── evaluations/           # A/B 测试结果
    └── 2025-Q1/

模板元数据格式

---
name: crud_api_generator
version: 2.1.0
category: code_generation
author: team@example.com
created: 2024-06-01
updated: 2025-01-15
tested_with: [claude-3-5-sonnet, gpt-4o]
success_rate: 87%  # 根据评估结果更新
tags: [api, crud, rest, backend]
---

# CRUD API 生成器

## 描述
生成完整的 RESTful CRUD API，包括模型、路由、服务层和测试。

## 变量
- `language`: 编程语言（Python/TypeScript/Go）
- `framework`: Web 框架（FastAPI/Express/Gin）
- `resource_name`: 资源名称（如 User/Product/Order）
...

## 模板内容
生成一个 {language} {framework} 的 {resource_name} CRUD API...

## 使用示例
...

## 已知限制
- 暂不支持多对多关系
- ...

A/B 测试提示词效果

评估框架

Prompt 的效果评估需要系统化的方法，而不是"感觉哪个更好"：

# 简单的 Prompt A/B 测试框架
import anthropic
import json
from dataclasses import dataclass


@dataclass
class EvaluationResult:
    prompt_version: str
    task_id: str
    output: str
    scores: dict[str, float]  # 各维度评分
    manual_edits_required: int  # 需要人工修改的行数


async def evaluate_prompt(
    prompt_v1: str,
    prompt_v2: str,
    test_cases: list[dict]
) -> dict:
    client = anthropic.AsyncAnthropic()
    results = {"v1": [], "v2": []}

    for case in test_cases:
        for version, prompt in [("v1", prompt_v1), ("v2", prompt_v2)]:
            response = await client.messages.create(
                model="claude-3-5-sonnet-20241022",
                max_tokens=4096,
                messages=[{
                    "role": "user",
                    "content": prompt.format(**case)
                }]
            )
            results[version].append(response.content[0].text)

    return results

提示词工程的底层原理

为什么 Prompt 的措辞差异会导致截然不同的结果？

这个问题的答案在于 LLM 的生成机制：模型基于输入词元的概率分布生成输出，轻微的措辞差异会改变初始概率分布，而这种差异在多步生成中会被放大（蝴蝶效应）。

Prompt 版本管理的最佳实践

将 Prompt 纳入版本管理的工程价值：可以追溯每次效果变化的原因、方便团队协作共建 Prompt 库、出问题时快速回滚到上一个有效版本。

# prompts/code_review.py - 代码审查 Prompt 版本管理示例
from dataclasses import dataclass
from datetime import date
from typing import Callable


@dataclass
class PromptVersion:
    version: str          # 语义化版本号，如 "1.2.0"
    template: str         # Prompt 模板内容
    author: str           # 修改人
    change_date: date     # 修改日期
    change_reason: str   # 修改原因（为什么要改）
    score: float = 0.0   # 评测得分（0-1），供对比用


# 版本历史
CODE_REVIEW_VERSIONS: list[PromptVersion] = [
    PromptVersion(
        version="1.0.0",
        template="请审查以下代码：\n{code}",
        author="alice",
        change_date=date(2025, 1, 10),
        change_reason="初始版本",
        score=0.62  # 评测：发现问题率 62%
    ),
    PromptVersion(
        version="1.1.0",
        template="""你是高级工程师，请从以下维度审查代码：
安全性、性能、可读性、测试覆盖。

代码：
{code}

对每个维度给出具体建议（如果没有问题请说"无问题"）。""",
        author="bob",
        change_date=date(2025, 1, 25),
        change_reason="添加角色和维度约束，提升结构化输出",
        score=0.81  # 评测：发现问题率提升到 81%
    ),
]

# 获取当前最新版本（score 最高）
CURRENT_CODE_REVIEW_PROMPT = max(CODE_REVIEW_VERSIONS, key=lambda v: v.score)

常见误区：Prompt 工程中的陷阱