diagnosis_zh: >-

「刚才改了个Prompt，然后...出问题了。但我不记得之前那一版是什么了。」

这句话在过去两年里，我从最少20个Agent开发者嘴里听到过。每个人在踩了坑之后才意识到：Prompt管理不是文学创作，是软件工程。

2026年的AI Agent项目，Prompt文件动辄几十上百个。一个客服Agent可能包含： - 6个System Prompt（不同语言/场景） - 15个Few-shot示例 - 8个工具函数描述 - 3个输出格式约束 - 2个安全Guardrails配置

如果不把Prompt当代码管，后果就是——某次微调后Agent突然「疯了」，但你翻遍历史记录也不知道改了什么。

### 把Prompt塞进Git的核心原则

原则一：每个Prompt都是单独的文件

不要把所有Prompt写在一个大文件里。用目录组织：

my-agent/ ├── prompts/ │ ├── system/ │ │ ├── customer-support.zh.md # 客户服务（中文） │ │ ├── customer-support.en.md # Customer Service (English) │ │ └── order-query.md # 订单查询 │ ├── few-shot/ │ │ ├── refund-examples.json # 退款场景示例 │ │ └── exchange-examples.json # 换货场景示例 │ ├── tools/ │ │ ├── query_order.yaml # 查询订单工具描述 │ │ └── cancel_order.yaml # 取消订单工具 │ └── guardrails/ │ ├── sensitive-topics.yaml # 敏感话题过滤器 │ └── output-constraints.yaml # 输出格式约束 ├── prompt_manager.py # Prompt加载和渲染 └── agent.py # Agent主入口

原则二：用YAML/JSON做结构化Prompt，别写纯文本

纯文本Prompt最大的问题是——你不知道哪些是「指令」、哪些是「格式约束」、哪些是「可替换变量」。

```yaml # prompts/system/customer-support.zh.yaml name: "客户支持系统提示" version: "2.3.1"

role: "客服助手" tone: "礼貌、简洁" language: "中文"

constraints: - "只能回答与订单相关的问题" - "不要编造订单信息" - "如果不知道答案，说'我需要转接人工客服'"

variables: store_name: "{{ STORE_NAME }}" business_hours: "{{ BUSINESS_HOURS }}"

rules: - condition: "用户情绪激动" action: "先道歉，再解决问题" - condition: "涉及退款金额超过5000元" action: "转接人工客服" ```

原则三：Prompt要版本化，和代码一起发版

用git tag给Prompt版本打标签：

```bash # Prompt发布规范 git tag prompts/v2.3.1 git tag prompts/customer-support/stable

# 看谁改了什么 git log --oneline prompts/ # a1b2c3d fix: 修复退款场景的few-shot示例 # e4f5g6h feat: 新增英文客服Prompt # i7j8k9l fix: 限制订单查询只查最近3个月 ```

### 如何设计Prompt的Git Workflow

分支策略：

main → 只有经过测试通过的Prompt ├── develop → Prompt开发和迭代分支 │ ├── feature/ab-test-prompts → A/B测试新Prompt │ └── fix/prompt-injection-fix → 安全修复 └── release/v2.3.x → Prompt发布分支

开发流程：

1. 从develop分支创建feature分支
2. 修改Prompt文件，本地测试
3. 提交PR，带before/after对比和测试结果
4. Code Review（是的，Prompt也要Review）
5. 合并到develop，CI跑集成测试
6. 合并到main，打tag发布

### 实用工具：Prompt渲染器

有了结构化Prompt之后，需要一个渲染器把它加载进Agent：

```python import yaml from string import Template

class PromptManager: def init(self, prompts_dir: str = "prompts"): self.prompts_dir = prompts_dir

  def load(self, name: str, variables: dict = None) -> str:
      """加载并渲染一个Prompt"""
      path = f"{self.prompts_dir}/{name}.yaml"
      with open(path, 'r') as f:
          config = yaml.safe_load(f)

      # 组装成可读的System Prompt
      parts = [
          f"角色：{config['role']}",
          f"语气：{config['tone']}",
          f"语言：{config['language']}",
          "",
          "约束：",
      ]
      for c in config['constraints']:
          parts.append(f"- {c}")

      parts.append("")
      parts.append("行为规则：")
      for r in config['rules']:
          parts.append(f"- 如果{r['condition']}，{r['action']}")

      prompt = "\n".join(parts)

      # 变量替换
      if variables:
          prompt = Template(prompt).safe_substitute(variables)

      return prompt

```

### Diff你的Prompt——用代码审查的思维改Prompt

Git最强大的功能是diff。Prompt改了什么，清清楚楚：

diff - - "只能回答与订单相关的问题" + - "只能回答已登录用户的订单相关问题" + - "如果用户未登录，提示先登录" + + rules: + - condition: "用户查询别人订单" + action: "拒绝并提示隐私保护政策"

这一行改动堵住了一个潜在的数据泄露漏洞。在Git里，任何团队成员都能看到这次改动的上下文、时间和作者。

### Prompt的A/B测试版本管理

可以用Git Branch管理A/B测试：

```bash # 创建A/B测试分支 git checkout -b ab-test/prompt-v2-vs-v3

# A版本放在prompts/system/main.yaml # B版本放在prompts/system/main.v3.yaml

# 在两个分支间切换测试 git checkout ab-test/prompt-a -- prompts/ # 跑一遍测试 git checkout ab-test/prompt-b -- prompts/ # 再跑一遍 ```

### 中文开发者的特别建议

1. Prompt文件名用英文：中文文件名在终端和Git中可能编码不一致
2. Prompt内容里中文加BOM头：某些加载库默认用ASCII编码，中文会乱码
3. YAML文件统一用UTF-8 with BOM：避免跨平台的编码问题
4. 每次修改Prompt，在PR描述里写改动目的：不要只写「改了下Prompt」

### 总结

Prompt就是代码。应该享受和代码一样的版本控制、代码审查、测试流程和发布规范。

从今天开始： 1. 把现在的所有Prompt拆成独立文件 2. 用YAML结构化 3. 塞进Git，和你的Agent代码一个仓库 4. 以后改Prompt必须走PR

三个月后，你会感谢自己做了这个决定。

prescription_zh: >-

本周改造清单 1. 列出你当前Agent的所有Prompt——拆成独立文件 2. 用YAML重写第一个System Prompt 3. 创建一个prompts/目录，把所有Prompt放进去 4. 跑一遍 git diff —— 看今天的Prompt改了啥 5. 定一个团队规则：改Prompt必须走PR

diagnosis_en: >-

"I changed the prompt and now the agent is broken. But I don't remember what it said before."

I've heard this from at least 20 agent developers over the past two years. Everyone learns the hard way: prompt management isn't creative writing — it's software engineering.

A 2026 production agent can have 30+ prompt files: multiple system prompts, few-shot examples, tool descriptions, output constraints, and guardrails. Managing them without Git is asking for disaster.

Three core principles:

1. One file per prompt — organize by prompts/system/, prompts/few-shot/, prompts/tools/, prompts/guardrails/. No monolithic prompt files.

2. Structured YAML/JSON prompts — separate instructions from constraints from variables. Example YAML schema with role, tone, constraints, variables, and conditional rules.

3. Versioned with code releases — use git tag prompts/v2.3.1. Every prompt change goes through a PR with proper diff review.

Git workflow: main (tested only) → develop (iteration) → feature/ab-test-X (experiments) → fix/security. Prompt diffs show exactly what changed, making the invisible visible.

Implementation: A PromptManager class that loads YAML files, renders variables with string.Template, and outputs structured system prompts.

Bonus: Manage A/B tests with git branches. Compare prompts/v2 vs prompts/v3 by switching branches and running the same test suite.

Chinese-specific tip: Use English filenames (encoding-safe), UTF-8-BOM encoding for Chinese content in YAML, and always document WHY in PR descriptions — not just "fixed prompt".

The bottom line: prompts are code. Treat them that way.

prescription_en: >-

This week's migration checklist 1. Extract all your prompts into individual files 2. Rewrite your primary System Prompt as structured YAML 3. Create a prompts/ directory and migrate all prompts there 4. Run git diff — see what your prompts look like today 5. Establish a team rule: prompt changes require PR reviews

---

## Article 2: Git管理Prompt的进阶技巧：Diff、Review和Rollback实战

### 不只是存代码，要管变更

上一篇文章讲了「为什么要把Prompt当代码管」，这篇讲「具体怎么管」。

我们用真实的Git命令和场景，从三个核心操作讲起：对比、审查、回滚。

### 场景一：Agent上周还好好的，这周疯了

症状：Agent突然开始拒绝回答正常问题，或者在应该查订单的时候跑去干别的事情。

第一步：查最近改了哪些Prompt

bash # 看看这周所有的Prompt修改记录 git log --oneline --since="7 days ago" -- prompts/ # d8f3e10 fix: 新增隐私保护规则 # a2b1c70 feat: 客服System Prompt新增场景 # e5f6g70 fix: 删除了"转接人工"权限

第二步：用diff看具体改了什么

bash git diff a2b1c70^..a2b1c70 -- prompts/system/customer-support.yaml

diff输出会精确显示每一行的变化。你可能发现上周的那次修改无意中删掉了某些关键指令。

第三步：回滚到正常版本

```bash # 回滚单个文件到昨天的版本 git checkout HEAD@{1.day.ago} -- prompts/system/customer-support.yaml

# 或者用git revert创建一个回滚提交 git revert a2b1c70 ```

整个过程不超过5分钟。如果没有Git，你可能需要翻聊天记录、查备份文件、甚至重写一遍。

### 场景二：两个Prompt版本测试对比

当你对Prompt做A/B测试时，Git是最自然的版本管理工具：

```bash # 保存当前版本作为A git tag prompts/ab-a/v1

# 修改Prompt vim prompts/system/main.yaml

# 保存新版本作为B git add prompts/ git commit -m "ab-test: 新版System Prompt (v2)" git tag prompts/ab-b/v1

# 在两个版本之间切换测试 git checkout prompts/ab-a/v1 -- prompts/ # 跑测试...

git checkout prompts/ab-b/v1 -- prompts/ # 跑测试... ```

### 场景三：多人协作时的Prompt Review

PR描述范例：

``` ## Prompt变更：客服System Prompt v2.3.1 → v2.4.0

### 原因 上周用户反馈Agent「态度太冷」，主要集中在退款场景。

### 改动 1. 加入了「共情」指令：对情绪激动的用户先表达理解 2. 新增退款进度查询的few-shot示例 3. 移除了「回复控制在50字以内」的约束（用户反馈回复太短）

### 测试结果 - Before：满意度评分 4.2/5 - After：满意度评分 4.7/5（50条测试样本） - 未见负面效果（安全测试全部通过）

### Reviewer需要关注 - 确认移除50字约束不会导致回复过长 - 检查新增的few-shot示例不包含敏感信息 ```

Review Checklist（贴在PR模板里）：

□ Prompt约束是否被意外删除？ □ 新增的规则有没有副作用？ □ 变量替换是否正确（{{VAR_NAME}}没有拼错）？ □ 中英文Prompt保持同步更新？ □ Safety guardrails有没有被弱化？ □ 对应的测试用例是否需要更新？

### 场景四：Prompt版本与代码版本不一致

有时候代码改了但Prompt没更新，或者Prompt改了但代码不兼容新的变量格式。

用Git来解决这个问题：

bash # 把Prompt版本号写在Agent的日志里 def log_version_info(): import subprocess prompt_version = subprocess.check_output( ['git', 'describe', '--tags', '--match', 'prompts/*'] ).decode().strip() print(f"Agent started with prompt: {prompt_version}")

每次Agent启动，日志里都会记录当前Prompt的Git版本。如果出了问题，你第一时间知道用的是哪个版本的Prompt。

### 五条铁律

1. 一个Prompt一个文件：不要把所有Prompt塞到一个文件里
2. 每一次修改都有commit message：「改了下」这种commit不算
3. 不同场景的Prompt用不同文件夹：别混在一起
4. 改Prompt必须有Review：和改代码一样需要Code Review
5. Agent日志记录Prompt版本号：生产环境出了问题能快速定位

### 总结

Git不是存代码的工具——它是管理变更的工具。Prompt作为Agent的「灵魂代码」，配得上最好的变更管理。

用Git管理Prompt不是增加工作量，是把「拍脑袋修改」变成「可追溯的工程流程」。今天花半天时间整理好，以后省下的是无尽的调试时间。