第 17 章：Prompt-First Development：把 Prompt 当作规格说明书

你是一名严谨的后端工程师。请根据下面的 JSON Schema 生成对应的 Pydantic 模型代码。
要求：
1. 所有字段必须添加 Field(description=...)。
2. 必填字段不加默认值，可选字段使用 Optional[...]。
3. 枚举类型使用 Python Literal。
4. 只输出代码，不要解释。

from jinja2 import Environment, BaseLoader

TEMPLATE = """
你是一名 API 文档生成助手。
请根据下面的函数签名，生成一段 OpenAPI 路径描述。

函数名：{{ function_name }}
参数：{% for p in params %}
- {{ p.name }} ({{ p.type }}): {{ p.description }}
{% endfor %}

输出要求：
1. 使用 YAML 格式。
2. 包含 summary、parameters、responses。
3. 不要添加 YAML 以外的文字。
"""

env = Environment(loader=BaseLoader())
template = env.from_string(TEMPLATE)

prompt = template.render(
    function_name="create_order",
    params=[
        {"name": "user_id", "type": "string", "description": "用户 ID"},
        {"name": "items", "type": "array", "description": "商品列表"},
    ]
)

import Handlebars from "handlebars";

const template = Handlebars.compile(`
你是一名 API 文档生成助手。
请根据下面的函数签名，生成一段 OpenAPI 路径描述。

函数名：{{functionName}}
参数：{{#each params}}
- {{name}} ({{type}}): {{description}}
{{/each}}

输出要求：
1. 使用 YAML 格式。
2. 包含 summary、parameters、responses。
3. 不要添加 YAML 以外的文字。
`);

const prompt = template({
  functionName: "createOrder",
  params: [
    { name: "userId", type: "string", description: "用户 ID" },
    { name: "items", type: "array", description: "商品列表" },
  ],
});

package main

import (
    "bytes"
    "text/template"
)

const tmpl = `
你是一名 API 文档生成助手。
请根据下面的函数签名，生成一段 OpenAPI 路径描述。

函数名：{{ .FunctionName }}
参数：{{ range .Params }}
- {{ .Name }} ({{ .Type }}): {{ .Description }}
{{ end }}

输出要求：
1. 使用 YAML 格式。
2. 包含 summary、parameters、responses。
3. 不要添加 YAML 以外的文字。
`

type Param struct {
    Name        string
    Type        string
    Description string
}

func renderPrompt(functionName string, params []Param) (string, error) {
    t := template.Must(template.New("prompt").Parse(tmpl))
    var buf bytes.Buffer
    err := t.Execute(&buf, map[string]any{
        "FunctionName": functionName,
        "Params":       params,
    })
    return buf.String(), err
}

import com.github.mustachejava.Mustache;
import com.github.mustachejava.MustacheFactory;
import com.github.mustachejava.DefaultMustacheFactory;

import java.io.StringWriter;
import java.util.List;
import java.util.Map;

public class PromptTemplate {
    public static void main(String[] args) {
        MustacheFactory mf = new DefaultMustacheFactory();
        Mustache mustache = mf.compile("prompt-template.mustache");

        StringWriter writer = new StringWriter();
        mustache.execute(writer, Map.of(
            "functionName", "createOrder",
            "params", List.of(
                Map.of("name", "userId", "type", "string", "description", "用户 ID"),
                Map.of("name", "items", "type", "array", "description", "商品列表")
            )
        ));

        String prompt = writer.toString();
    }
}

messages = [
    {
        "role": "system",
        "content": "你是一名后端代码审查助手。只输出安全风险，不输出风格建议。"
    },
    {
        "role": "user",
        "content": template.render(code_snippet=snippet)
    },
    {
        "role": "user",
        "content": "示例：\n输入：user_input = request.GET['name']\n输出：{\"risk\": \"SQL 注入\", \"line\": 1}"
    }
]

# prompt_registry.py
PROMPTS = {
    "generate_api": {
        "version": "1.2.0",
        "path": "prompts/generate_api/v1.2.0.md",
        "tests": [
            {"input": "create_order_schema.json", "expected_contains": "class CreateOrderRequest"},
        ],
    }
}

def load_prompt(name: str) -> str:
    meta = PROMPTS[name]
    with open(meta["path"], "r", encoding="utf-8") as f:
        return f.read()

import json
from pathlib import Path

def test_prompt_regression():
    cases = json.loads(Path("tests/prompt_cases.json").read_text())
    prompt = load_prompt("generate_api")
    for case in cases:
        output = llm.call(prompt, case["input"])
        for check in case["assertions"]:
            assert check in output, f"Missing {check} in {case['name']}"