Prompt工程架构实战：System四段式与五块积木提升AI应用可维护性

这次我们来看一个关于 Prompt 架构的实战项目。它不是一个具体的软件或模型，而是一套方法论和最佳实践，核心目标是解决一个痛点：如何像管理代码一样，系统化地管理、迭代和复用那些越来越复杂的 AI 提示词（Prompt）。随着大模型应用深入，动辄数百上千字的 System Prompt 和复杂的工具调用描述，如果还停留在记事本里复制粘贴，效率低下且难以维护。这套架构提供了“System 四段式”、“五块积木”和“工具描述五件套”等具体框架，旨在提升 Prompt 工程的可读性、可维护性和协作效率。

对于开发者、AI 应用构建者以及任何需要与大型语言模型（LLM）进行复杂、稳定交互的团队来说，这篇文章直接切入核心。我们将重点关注这套方法如何落地，包括：如何结构化编写 System Prompt，如何用“积木”思维组装复杂指令，以及如何规范化描述工具以提升 Agent 的调用准确性。更重要的是，我们会探讨如何将这些文本资产纳入版本管理（如 Git），实现真正的“提示即代码”。

本文将从实战出发，带你完成以下内容：首先快速了解这套架构的核心组件与价值；然后，我们会深入每一个模式，通过具体的示例和模板展示其用法；接着，探讨如何将这些模式化的 Prompt 用文件进行管理，并集成到常见的开发工作流中；最后，提供一套验证 Prompt 效果和进行迭代优化的实操方法。如果你正在为 Prompt 的混乱、难以调试和团队协作头疼，那么这篇文章提供的思路和工具链建议，或许能成为你的解决方案。

1. 核心能力速览

这套 Prompt 架构方法论不依赖特定硬件或显存，其“运行环境”是你的文本编辑器、版本控制系统和项目管理流程。它的核心价值在于通过规范化和模块化，提升 LLM 交互的工程化水平。

能力项	说明
核心方法	System 四段式、五块积木、工具描述五件套
主要功能	结构化编写 System Prompt、模块化组装复杂指令、标准化描述工具/函数供 LLM 调用
“运行”门槛	无硬件要求，需理解基础 Prompt 工程概念，并准备文本编辑与版本管理工具
“部署”方式	即采用即用，将模式应用于 Prompt 编写，并保存为.txt,.md,.yaml或.json文件
“接口”能力	产出的结构化 Prompt 可直接用于各类 LLM API（OpenAI, Claude, 国产大模型等）调用
“批量”任务	通过版本管理（Git）可高效管理大量 Prompt 变体，进行 A/B 测试和迭代
适合场景	复杂 AI Agent 开发、需要稳定输出的生产级应用、团队协作开发 Prompt、长期迭代优化提示词

2. 适用场景与使用边界

这套架构最适合那些已经超越简单问答，进入复杂交互和自动化流程的 LLM 应用开发者。

它非常适合以下场景：

1. AI Agent 开发：Agent 通常需要清晰的角色定义、复杂的工作流程和精准的工具调用。四段式和五件套能提供稳定的基础。
2. 生产级应用集成：当 Prompt 直接关系到产品功能的核心体验时（如客服机器人、内容生成流水线），其稳定性和可维护性至关重要，需要版本管理和结构化设计。
3. 团队协作与知识沉淀：避免“黑魔法” Prompt。通过模块化设计，团队可以共享、复用“积木”，新成员能快速理解系统设计意图。
4. 长期迭代与 A/B 测试：将 Prompt 作为代码管理，可以轻松创建分支、对比不同版本的效果，用数据驱动 Prompt 优化。

它的能力边界也很清晰：

1. 不替代创意和洞察：它提供的是“脚手架”和“规范”，而非灵感和对问题的深度理解。最核心的指令逻辑仍需人工设计。
2. 不保证模型绝对服从：再好的结构也无法 100% 杜绝模型的幻觉或偏离。它旨在提高稳定性和可预期性，而非绝对控制。
3. 可能增加初期复杂度：对于极其简单的“一次性” Prompt，使用完整架构可能显得繁琐。它更适用于有复用和迭代需求的复杂场景。
4. 需要团队共识：如果只有一人遵循规范而他人随意编写，其协作价值将大打折扣。需要作为团队规范推行。

3. 环境准备与前置条件

“环境准备”在这里指的是开始应用这套方法论所需的知识和工具准备，而非软件安装。

知识准备：

• 基础概念：理解什么是 System Prompt、User Prompt、Chat Completion API 的基本调用方式。
• 经验：有过编写复杂 Prompt（超过 5 轮交互或涉及多个步骤）并遇到维护困难的经验更佳。

工具准备：

1. 文本编辑器/IDE：VS Code、Sublime Text、Vim 等均可。推荐使用支持 Markdown、YAML 语法高亮和代码片段的编辑器。
2. 版本控制系统：Git是核心。你需要在本机安装 Git，并了解基本的git init,git add,git commit,git diff操作。拥有 GitHub、GitLab 或 Gitee 账号用于远程备份和协作更佳。
3. 文件组织：规划好项目目录。例如：

   your_agent_project/ ├── prompts/ # 存放所有提示词文件 │ ├── system/ # 系统提示词，按角色或功能分类 │ ├── blocks/ # 五块积木，可复用的指令模块 │ ├── tools/ # 工具描述五件套 │ └── templates/ # 完整的对话模板 ├── tests/ # 存放用于测试 Prompt 的输入输出案例 └── README.md # 项目说明，包含 Prompt 架构规范

4. LLM 访问环境：准备一个可用的 LLM API 密钥（如 OpenAI、Claude、DeepSeek、智谱等）及对应的 SDK 或能直接发送 HTTP 请求的环境（如curl、Postman）。

4. “System 四段式”详解与实战

System Prompt 是对话的基石，它定义了 AI 助手的角色、行为边界和思考框架。四段式将其结构化为四个逻辑部分，确保信息完整且有序。

4.1 四段式结构拆解

1. 角色与身份：清晰定义 AI 是谁。包括职称、领域专家身份、甚至性格特点。
   • 示例：“你是一位资深的全栈软件开发工程师，擅长 Python 和 JavaScript，代码风格严谨清晰，注重可读性和可维护性。”
2. 任务与目标：明确本次对话或任务的核心目标。要具体、可衡量。
   • 示例：“你的任务是分析用户提供的需求，生成一个技术方案概要，并给出核心模块的伪代码。方案需要包含技术选型理由和潜在风险点。”
3. 工作流程与约束：规定 AI 思考和行为的具体步骤、格式要求以及必须遵守的规则。
   • 示例：“请按以下步骤工作：1. 澄清模糊需求。2. 拆分系统模块。3. 为每个模块选择合适的技术栈并说明理由。4. 输出伪代码。输出必须使用 Markdown 格式，代码块需标注语言。”
4. 交互风格与边界：定义回复的语气、长度，以及明确什么不能做（安全、合规边界）。
   • 示例：“保持专业、友好的语气。如果需求涉及违法、侵权或你无法确认安全性的操作，你必须明确拒绝并说明原因。对于不确定的信息，应主动声明。”

4.2 实战：编写一个技术方案顾问的 System Prompt

我们将上述四段组合起来，形成一个完整的、可投入使用的 System Prompt 文件。建议保存为prompts/system/technical_advisor_v1.md。

# 系统提示词：技术方案顾问 (v1.0) ## 1. 角色与身份 你是 CodeCraft AI，一个拥有10年经验的全栈开发专家，主攻现代Web架构和云原生应用。你以逻辑严密、考虑周全著称，善于将复杂问题分解为可执行的步骤。 ## 2. 任务与目标 你的核心任务是协助用户将产品需求转化为可行的技术实施方案。每次交互，你应输出一个结构清晰、包含技术选型分析、架构草图（文字描述）和核心代码片段（伪代码或具体语言）的方案文档。 ## 3. 工作流程与约束 你必须严格遵循以下流程： 1. **需求确认**：首先复述用户需求，并提出最多3个关键问题以澄清任何模糊点，等待用户确认或补充。 2. **架构设计**：基于确认后的需求，提出1-2个备选的高层架构（如MVC、微服务、Serverless），并列出各自的优缺点。 3. **技术选型**：为选定的架构推荐具体的技术栈（如前端框架、后端语言、数据库、部署平台），并简要说明选型理由。 4. **输出交付**：将最终方案整理成Markdown文档，必须包含以下章节：概述、架构图描述、模块分解、技术栈清单、核心逻辑伪代码、潜在风险与缓解措施。 ## 4. 交互风格与边界 - 保持积极、建设性的沟通态度。 - 对于涉及用户隐私数据、系统安全攻击方法、破解版权保护等请求，应礼貌拒绝并提供合规建议。 - 如果遇到知识边界外的问题，如实告知并建议查询官方文档或相关专家。 - 所有代码示例需包含必要的注释。

如何使用：在调用 LLM API 时，将上述文件的内容（或去除 Markdown 标题的纯文本）作为system参数传入。接下来，用户的请求将作为user参数。

5. “五块积木”组装复杂指令

对于复杂的单次查询或需要多步骤推理的 User Prompt，直接写一大段文字容易遗漏要点。“五块积木”模式将其分解为五个可插拔的模块，就像拼乐高一样组合你的指令。

5.1 五块积木定义

1. 指令：最核心的命令，告诉模型要做什么。必须清晰、无歧义。
   • 示例：“写一份关于‘如何管理Prompt版本’的技术博客大纲。”
2. 上下文：提供背景信息，帮助模型理解指令的所处环境。
   • 示例：“这篇文章面向的是有一定Prompt工程经验，但苦于团队协作和迭代效率的开发者。”
3. 输入数据：提供模型需要处理的具体材料。格式要规范。
   • 示例：“以下是当前混乱的Prompt管理方式描述：[此处粘贴描述文字]”。
4. 输出指示：明确规定输出的格式、结构、长度、风格等。
   • 示例：“输出要求：使用Markdown格式，包含至少二级标题，总字数在800字左右，风格偏实战指南而非理论阐述。”
5. 示例：提供一个或几个输入输出的例子，让模型更好地理解你的意图。这是 Few-Shot Learning 的运用。
   • 示例：“例如，如果输入是‘写一个Python函数计算斐波那契数列’，输出应该是包含函数定义、注释和简单调用示例的代码块。”

5.2 实战：组合积木完成内容改写任务

假设我们需要一个能将技术性文字改写得通俗易懂的指令。我们可以为每个“积木”创建独立的文本片段，存放在prompts/blocks/目录下，然后按需组装。

积木文件示例：

• instruction_rewrite.txt: “将以下技术性内容改写得通俗易懂，适合行业新手阅读。”
• context_tech_blog.txt: “这是为一篇面向入门开发者的技术博客准备的内容。”
• output_indicator_md_short.txt: “输出请直接给出改写后的段落，无需额外说明。语言口语化，避免长句和复杂术语。”
• example_pair_1.json: (一个包含“输入技术文本”和“输出通俗文本”的示例对)

组装实战： 当需要执行改写任务时，我们像拼接字符串一样组合这些积木。以下是一个 Python 伪代码示例，展示如何动态构建 User Prompt：

# 假设我们从文件中读取了各个积木的内容 with open(‘prompts/blocks/instruction_rewrite.txt‘, ‘r‘) as f: instruction = f.read() with open(‘prompts/blocks/context_tech_blog.txt‘, ‘r‘) as f: context = f.read() with open(‘prompts/blocks/output_indicator_md_short.txt‘, ‘r‘) as f: output_indicator = f.read() # 示例积木可能以结构化数据存储 example = load_example(‘prompts/blocks/example_pair_1.json‘) # 待处理的输入数据 input_data = “LLM的推理过程涉及自注意力机制，它通过计算查询、键和值向量之间的相关性，来动态地为序列中的每个token分配权重...” # 组装最终的用户提示词 user_prompt = f“““ {instruction} **上下文**：{context} **需要改写的内容**： {input_data} **输出要求**：{output_indicator} **参考示例**： 输入：{example[‘input‘]} 输出：{example[‘output‘]} “““ # 然后将 system_prompt 和 user_prompt 发送给 LLM API messages = [ {“role“: “system“, “content“: system_prompt}, {“role“: “user“, “content“: user_prompt} ] # ... 调用 API

这种方式使得维护和 A/B 测试变得非常容易。例如，想测试不同的“输出指示”对效果的影响，只需替换output_indicator_md_short.txt为另一个版本的文件即可。

6. “工具描述五件套”规范 Agent 能力

当构建能调用外部函数或工具的 AI Agent 时，清晰、无歧义的工具描述至关重要。“五件套”确保了 LLM 能准确理解何时以及如何调用工具。

6.1 五件套结构

这通常对应着 OpenAI Function Calling 或类似机制中的工具定义（JSON Schema）。一个完整的工具描述应包含：

1. 名称：工具的唯一标识符，用于在代码中映射到具体函数。
   • “name“: “get_current_weather“
2. 描述：用自然语言清晰说明这个工具是做什么的。这是 LLM 决定是否调用该工具的主要依据。
   • “description“: “获取指定城市的当前天气信息。“
3. 参数：定义工具所需的输入参数。每个参数都需要名称、类型、描述，以及是否必需。

   • “parameters“: { “type“: “object“, “properties“: { “location“: { “type“: “string“, “description“: “城市名称，例如‘北京‘，‘San Francisco, CA‘。“ }, “unit“: { “type“: “string“, “enum“: [“celsius“, “fahrenheit“], “description“: “温度单位，默认为‘celsius‘。“ } }, “required“: [“location“] }

4. 必需参数：在parameters中明确指出的required字段列表。
5. 返回描述（可选但建议）：说明工具成功调用后会返回什么类型的信息，帮助 LLM 理解如何利用返回结果继续对话。
   • 可以在外层补充：“returns“: “一个包含温度、天气状况和湿度的JSON对象。“

6.2 实战：定义“搜索网络资料”工具

我们将这个工具定义保存为一个独立的 JSON 文件，例如prompts/tools/web_search.json。这有利于在多个 Agent 间复用和统一更新。

{ “name“: “search_web“, “description“: “根据查询关键词，在互联网上搜索最新的相关信息、文章或资料。当你需要获取实时、未知或特定领域的事实时，应优先使用此工具。“, “parameters“: { “type“: “object“, “properties“: { “query“: { “type“: “string“, “description“: “搜索查询字符串，应具体、明确，包含关键实体和限定词。例如：‘2024年Python异步编程asyncio的最佳实践‘ 而非 ‘Python怎么异步‘。“ }, “max_results“: { “type“: “integer“, “description“: “希望返回的最大结果数量，默认为5。“, “default“: 5 } }, “required“: [“query“] } }

在 Agent 中使用：当初始化你的 AI Agent（例如使用 LangChain、Semantic Kernel 或直接调用支持 Function Calling 的 API）时，你可以直接读取这个 JSON 文件，将其作为工具列表的一部分加载进去。这样，工具的描述就与代码逻辑分离，易于管理。

7. 将 Prompt 纳入版本管理

这是“把提示当代码管”的精髓。通过 Git 管理 Prompt 文件，你可以获得所有代码管理的好处：历史追溯、差异对比、分支实验和团队协作。

7.1 项目目录结构重构

基于前面的建议，一个规范的 Prompt 工程项目目录可能如下所示：

my_ai_agent/ ├── .gitignore ├── README.md ├── agent_core.py # Agent 核心逻辑代码 ├── requirements.txt # Python 依赖 └── prompts/ # 所有 Prompt 资产 ├── README.md # Prompt 目录说明，描述架构规范 ├── system/ │ ├── technical_advisor_v1.md │ ├── creative_writer_v2.md │ └── customer_support_v1.md ├── blocks/ │ ├── instruction_*.txt │ ├── context_*.txt │ ├── output_*.txt │ └── examples/ │ └── *.json ├── tools/ │ ├── web_search.json │ ├── calculator.json │ └── send_email.json ├── templates/ # 预组装好的完整对话模板 │ └── blog_outline_from_topic.json └── tests/ # Prompt 测试用例 ├── test_cases.json └── evaluation_logs/

7.2 Git 工作流示例

1. 初始化与提交：

   cd my_ai_agent git init git add prompts/ git commit -m “feat(prompts): 初始化Prompt目录结构，添加技术顾问系统提示词v1“

2. 迭代与更新：当你优化了technical_advisor_v1.md，可以创建新版本文件technical_advisor_v2.md，或直接修改后提交。

   # 修改 prompts/system/technical_advisor_v1.md 后 git diff prompts/system/technical_advisor_v1.md # 查看具体改了哪里 git add prompts/system/technical_advisor_v1.md git commit -m “fix(prompts): 优化技术顾问的工作流程约束，增加风险分析步骤“

3. 分支实验：想尝试一个全新的、可能破坏现有功能的 Prompt 设计？创建一个特性分支。

   git checkout -b experiment/new_creative_prompt # 在 prompts/system/ 下创建新的 experimental_writer.md 并修改 # 进行测试... git add . git commit -m “experiment: 测试新的创意写作系统提示词结构“ # 如果效果不好，可以轻松切回主分支 git checkout main # 如果效果好，可以合并到主分支 git merge experiment/new_creative_prompt

4. 团队协作：团队成员可以克隆仓库，在各自分支上修改不同的 Prompt 模块，通过 Pull Request 提交修改，并进行 Code Review（此时是 Prompt Review），确保变更符合团队规范。

8. 功能测试与效果验证

如何验证我们结构化后的 Prompt 是否真的更好？需要建立测试流程。

8.1 创建测试用例集

在prompts/tests/test_cases.json中，定义一组标准的输入和期望的输出特征。

[ { “id“: “test_tech_1“, “system_prompt_file“: “system/technical_advisor_v1.md“, “user_input“: “我想开发一个个人记账微信小程序，记录日常开支并能生成月度报表。“, “evaluation_criteria“: [ “回复是否首先进行了需求澄清提问？“, “输出的方案是否包含至少两个架构选项（如原生小程序 vs UniApp）？“, “是否列出了具体的技术栈（如前端框架、数据库）？“, “伪代码是否涵盖了核心的数据添加和查询逻辑？“, “是否提及了潜在风险（如数据安全、云成本）？“ ] }, { “id“: “test_rewrite_1“, “system_prompt_file“: “system/creative_writer_v2.md“, “user_input“: “（这里粘贴一段复杂的区块链技术说明文字）“, “evaluation_criteria“: [ “改写后的文本长度是否控制在原长度的80%-120%？“, “专业术语是否被恰当解释或替换？“, “整体可读性（句子平均长度、段落结构）是否提升？“, “是否保留了原意的所有关键信息？“ ] } ]

8.2 自动化测试脚本

编写一个简单的 Python 脚本，读取测试用例，调用 LLM API，并记录结果。关键不是完全自动化判断对错，而是自动化执行并保存记录，供人工评审。

import json import openai import datetime # 加载测试用例 with open(‘prompts/tests/test_cases.json‘, ‘r‘, encoding=‘utf-8‘) as f: test_cases = json.load(f) client = openai.OpenAI(api_key=‘your-api-key‘) results = [] for case in test_cases: # 1. 加载对应的 System Prompt with open(f‘prompts/{case[“system_prompt_file“]}‘, ‘r‘, encoding=‘utf-8‘) as f: system_content = f.read() # 2. 调用 API try: response = client.chat.completions.create( model=“gpt-4-turbo“, # 或你使用的模型 messages=[ {“role“: “system“, “content“: system_content}, {“role“: “user“, “content“: case[“user_input“]} ], temperature=0.7, ) answer = response.choices[0].message.content except Exception as e: answer = f“API调用失败: {e}“ # 3. 保存结果 result = { “test_id“: case[“id“], “timestamp“: datetime.datetime.now().isoformat(), “user_input“: case[“user_input“], “model_response“: answer, “evaluation_criteria“: case[“evaluation_criteria“] } results.append(result) # 4. 将结果保存到日志文件，文件名包含时间戳以便追溯 log_file = f“prompts/tests/evaluation_logs/test_run_{datetime.datetime.now().strftime(‘%Y%m%d_%H%M%S‘)}.json“ with open(log_file, ‘w‘, encoding=‘utf-8‘) as f: json.dump(results, f, ensure_ascii=False, indent=2) print(f“测试完成，结果已保存至: {log_file}“)

运行此脚本后，你可以查看生成的日志文件，人工根据evaluation_criteria评估每次回复的质量。多次运行、修改 Prompt 后再运行，就能形成迭代优化的数据依据。

9. 常见问题与排查方法

在实践这套架构时，你可能会遇到一些典型问题。

问题现象	可能原因	排查方式	解决方案
LLM 输出完全偏离角色或任务	System Prompt 角色/任务段定义模糊或矛盾。	检查“角色与身份”是否足够具体？“任务与目标”是否清晰无歧义？	重写角色和任务描述，使其更精确。可以加入“你绝对不是...”这样的负面约束。
模型忽略了输出格式要求	输出指示不够强硬或放在了不显眼的位置。	检查“工作流程与约束”或“输出指示”积木是否明确列出了格式要求。	将格式要求放在更靠前的位置，使用“必须”、“严格遵循”等词，并给出具体示例。
Agent 该调用工具时不调用	工具描述不够清晰，或 System Prompt 未鼓励工具使用。	1. 检查工具描述是否准确说明了使用场景。 2. 检查 System Prompt 中是否明确要求“在需要时使用可用工具”。	1. 优化工具描述，特别是“描述”字段。 2. 在 System Prompt 的“工作流程”中加入工具调用步骤。
不同 Prompt 版本间效果对比困难	缺乏系统化的测试和记录。	回顾是否建立了固定的测试用例集和评估标准。	建立本章第8节所述的测试用例库和自动化测试日志流程。
团队成员的 Prompt 风格迥异	没有统一的架构规范和文件模板。	检查prompts/README.md中是否明确了书写规范。	制定团队规范文档，并提供system/,blocks/下的模板文件，进行 Code Review。
Prompt 文件过多，难以查找	目录结构不合理或命名不规范。	查看prompts/目录是否混乱。	采用功能/角色分类的子目录，文件命名包含版本号（如_v1,_v2）和简要描述。

10. 最佳实践与使用建议

1. 始于简单，渐进复杂：不要一开始就追求完美的四段式或五件套。从一个清晰的核心指令开始，随着问题复杂化再引入更多模块。
2. 版本化一切：任何对生产环境有影响的 Prompt 修改，都必须通过 Git 提交。使用有意义的提交信息，如fix(prompt): 澄清需求澄清步骤或feat(tool): 新增数据库查询工具描述。
3. 分离关注点：将系统指令、用户指令、工具定义、示例数据分开存放。这符合软件工程的“单一职责原则”，使得修改和复用更容易。
4. 编写“活”文档：在prompts/README.md或每个 Prompt 文件的头部，写明其设计意图、适用场景、版本变更历史以及已知的局限性。
5. 建立评估基线：在开始大规模优化前，用一组标准问题测试当前 Prompt 的效果，并保存结果。后续所有优化都应与这个基线进行比较，避免盲目修改。
6. 合规与安全前置：在 System Prompt 的“边界”部分和工具描述中，明确加入对内容安全、用户隐私、版权合规的约束。这不仅是伦理要求，也能减少生产环境中的意外风险。
7. 拥抱迭代：Prompt 工程本质上是实验性的。利用好版本管理，大胆创建分支进行 A/B 测试，用测试结果和数据驱动决策，而不是直觉。

将 Prompt 视为代码，不仅仅是换一种文件存储方式，更是一种思维模式的转变。它要求我们像对待软件组件一样，对待这些与模型交互的指令：设计、实现、测试、版本控制、协作和迭代。通过采用 System 四段式、五块积木和工具描述五件套这样的架构，我们能够有效管理复杂度，提升团队效率，并构建出更稳定、可靠的 AI 应用。下次当你面对一个需要反复调试的复杂 Prompt 时，不妨先停下来，思考一下如何用这些“积木”将它重新搭建。