这次我们来看一个关于 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 APIOpenAI, Claude, 国产大模型等调用“批量”任务通过版本管理Git可高效管理大量 Prompt 变体进行 A/B 测试和迭代适合场景复杂 AI Agent 开发、需要稳定输出的生产级应用、团队协作开发 Prompt、长期迭代优化提示词2. 适用场景与使用边界这套架构最适合那些已经超越简单问答进入复杂交互和自动化流程的 LLM 应用开发者。它非常适合以下场景AI Agent 开发Agent 通常需要清晰的角色定义、复杂的工作流程和精准的工具调用。四段式和五件套能提供稳定的基础。生产级应用集成当 Prompt 直接关系到产品功能的核心体验时如客服机器人、内容生成流水线其稳定性和可维护性至关重要需要版本管理和结构化设计。团队协作与知识沉淀避免“黑魔法” Prompt。通过模块化设计团队可以共享、复用“积木”新成员能快速理解系统设计意图。长期迭代与 A/B 测试将 Prompt 作为代码管理可以轻松创建分支、对比不同版本的效果用数据驱动 Prompt 优化。它的能力边界也很清晰不替代创意和洞察它提供的是“脚手架”和“规范”而非灵感和对问题的深度理解。最核心的指令逻辑仍需人工设计。不保证模型绝对服从再好的结构也无法 100% 杜绝模型的幻觉或偏离。它旨在提高稳定性和可预期性而非绝对控制。可能增加初期复杂度对于极其简单的“一次性” Prompt使用完整架构可能显得繁琐。它更适用于有复用和迭代需求的复杂场景。需要团队共识如果只有一人遵循规范而他人随意编写其协作价值将大打折扣。需要作为团队规范推行。3. 环境准备与前置条件“环境准备”在这里指的是开始应用这套方法论所需的知识和工具准备而非软件安装。知识准备基础概念理解什么是 System Prompt、User Prompt、Chat Completion API 的基本调用方式。经验有过编写复杂 Prompt超过 5 轮交互或涉及多个步骤并遇到维护困难的经验更佳。工具准备文本编辑器/IDEVS Code、Sublime Text、Vim 等均可。推荐使用支持 Markdown、YAML 语法高亮和代码片段的编辑器。版本控制系统Git是核心。你需要在本机安装 Git并了解基本的git init,git add,git commit,git diff操作。拥有 GitHub、GitLab 或 Gitee 账号用于远程备份和协作更佳。文件组织规划好项目目录。例如your_agent_project/ ├── prompts/ # 存放所有提示词文件 │ ├── system/ # 系统提示词按角色或功能分类 │ ├── blocks/ # 五块积木可复用的指令模块 │ ├── tools/ # 工具描述五件套 │ └── templates/ # 完整的对话模板 ├── tests/ # 存放用于测试 Prompt 的输入输出案例 └── README.md # 项目说明包含 Prompt 架构规范LLM 访问环境准备一个可用的 LLM API 密钥如 OpenAI、Claude、DeepSeek、智谱等及对应的 SDK 或能直接发送 HTTP 请求的环境如curl、Postman。4. “System 四段式”详解与实战System Prompt 是对话的基石它定义了 AI 助手的角色、行为边界和思考框架。四段式将其结构化为四个逻辑部分确保信息完整且有序。4.1 四段式结构拆解角色与身份清晰定义 AI 是谁。包括职称、领域专家身份、甚至性格特点。示例“你是一位资深的全栈软件开发工程师擅长 Python 和 JavaScript代码风格严谨清晰注重可读性和可维护性。”任务与目标明确本次对话或任务的核心目标。要具体、可衡量。示例“你的任务是分析用户提供的需求生成一个技术方案概要并给出核心模块的伪代码。方案需要包含技术选型理由和潜在风险点。”工作流程与约束规定 AI 思考和行为的具体步骤、格式要求以及必须遵守的规则。示例“请按以下步骤工作1. 澄清模糊需求。2. 拆分系统模块。3. 为每个模块选择合适的技术栈并说明理由。4. 输出伪代码。输出必须使用 Markdown 格式代码块需标注语言。”交互风格与边界定义回复的语气、长度以及明确什么不能做安全、合规边界。示例“保持专业、友好的语气。如果需求涉及违法、侵权或你无法确认安全性的操作你必须明确拒绝并说明原因。对于不确定的信息应主动声明。”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 五块积木定义指令最核心的命令告诉模型要做什么。必须清晰、无歧义。示例“写一份关于‘如何管理Prompt版本’的技术博客大纲。”上下文提供背景信息帮助模型理解指令的所处环境。示例“这篇文章面向的是有一定Prompt工程经验但苦于团队协作和迭代效率的开发者。”输入数据提供模型需要处理的具体材料。格式要规范。示例“以下是当前混乱的Prompt管理方式描述[此处粘贴描述文字]”。输出指示明确规定输出的格式、结构、长度、风格等。示例“输出要求使用Markdown格式包含至少二级标题总字数在800字左右风格偏实战指南而非理论阐述。”示例提供一个或几个输入输出的例子让模型更好地理解你的意图。这是 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。一个完整的工具描述应包含名称工具的唯一标识符用于在代码中映射到具体函数。“name“: “get_current_weather“描述用自然语言清晰说明这个工具是做什么的。这是 LLM 决定是否调用该工具的主要依据。“description“: “获取指定城市的当前天气信息。“参数定义工具所需的输入参数。每个参数都需要名称、类型、描述以及是否必需。“parameters“: { “type“: “object“, “properties“: { “location“: { “type“: “string“, “description“: “城市名称例如‘北京‘‘San Francisco, CA‘。“ }, “unit“: { “type“: “string“, “enum“: [“celsius“, “fahrenheit“], “description“: “温度单位默认为‘celsius‘。“ } }, “required“: [“location“] }必需参数在parameters中明确指出的required字段列表。返回描述可选但建议说明工具成功调用后会返回什么类型的信息帮助 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 工作流示例初始化与提交cd my_ai_agent git init git add prompts/ git commit -m “feat(prompts): 初始化Prompt目录结构添加技术顾问系统提示词v1“迭代与更新当你优化了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): 优化技术顾问的工作流程约束增加风险分析步骤“分支实验想尝试一个全新的、可能破坏现有功能的 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团队协作团队成员可以克隆仓库在各自分支上修改不同的 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“]} ], temperature0.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_asciiFalse, indent2) 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. 最佳实践与使用建议始于简单渐进复杂不要一开始就追求完美的四段式或五件套。从一个清晰的核心指令开始随着问题复杂化再引入更多模块。版本化一切任何对生产环境有影响的 Prompt 修改都必须通过 Git 提交。使用有意义的提交信息如fix(prompt): 澄清需求澄清步骤或feat(tool): 新增数据库查询工具描述。分离关注点将系统指令、用户指令、工具定义、示例数据分开存放。这符合软件工程的“单一职责原则”使得修改和复用更容易。编写“活”文档在prompts/README.md或每个 Prompt 文件的头部写明其设计意图、适用场景、版本变更历史以及已知的局限性。建立评估基线在开始大规模优化前用一组标准问题测试当前 Prompt 的效果并保存结果。后续所有优化都应与这个基线进行比较避免盲目修改。合规与安全前置在 System Prompt 的“边界”部分和工具描述中明确加入对内容安全、用户隐私、版权合规的约束。这不仅是伦理要求也能减少生产环境中的意外风险。拥抱迭代Prompt 工程本质上是实验性的。利用好版本管理大胆创建分支进行 A/B 测试用测试结果和数据驱动决策而不是直觉。将 Prompt 视为代码不仅仅是换一种文件存储方式更是一种思维模式的转变。它要求我们像对待软件组件一样对待这些与模型交互的指令设计、实现、测试、版本控制、协作和迭代。通过采用 System 四段式、五块积木和工具描述五件套这样的架构我们能够有效管理复杂度提升团队效率并构建出更稳定、可靠的 AI 应用。下次当你面对一个需要反复调试的复杂 Prompt 时不妨先停下来思考一下如何用这些“积木”将它重新搭建。