第5章 智能体开发Step3：用Claude Code生成你的第一个“评论甄别智能体”

本章你将学到：

• 用自然语言指令让Claude Code为你生成业务智能体的Prompt和运行脚本
• 理解生成的代码中每一段的作用，而不是盲目使用
• 首次运行智能体，观察它的表现，并做必要的手动微调

本章你将产出：一个完全由AI辅助生成、但经过你审查和微调的“评论甄别智能体”核心脚本 comment_agent.py 及其Prompt模板
全部章节：收录在专栏《AI应用工程化实战教程》

---

在第4章，我们用Claude Code生成了规范文档和测试数据集。当时你做的，是给出一条清晰的指令，然后AI把活儿干了，你来审核。

本章我们要做同样的事情——但这次，AI要帮你写的是一个能真正运行起来、能调用大模型、能处理各种异常情况的Python程序。

如果你是从第1章一路读过来的，可能会心里犯嘀咕：“我不会写这么复杂的代码啊。”

没关系。本书的核心原则就是：你不会写的代码，让AI帮你写。但你必须看得懂AI写了什么，能判断它写得对不对，能在必要时指挥它改。

这就是“驾驭AI”的真正含义——不是自己当苦力，也不是完全撒手不管，而是像一个项目负责人一样，提需求、审产出、做决策。
本章以Claude Code作为开发环境，但同样的方法也适用于其它AI辅助编程工具，比如Trae也可以，还免费，详见第3章。

---

5.1 用Claude Code生成智能体的Prompt和运行脚本

5.1.1 我们需要生成什么？

在动手之前，先理清目标。我们需要两个文件：

1. prompt_template.txt：业务智能体的系统提示词（System Prompt），定义了它的角色、判断标准、输出格式和边界规则。
2. comment_agent.py：一个Python脚本，封装了调用大模型API、输入校验、输出解析、错误处理等全部逻辑，对外提供一个干净的函数 analyze_comment(comment_text)。

这两个文件互相关联：脚本会读取Prompt文件，把它作为系统提示词发给大模型。修改Prompt就能改变智能体的行为，不需要改代码。

5.1.2 设计给Claude Code的指令

要让AI一次生成这两个文件，并且生成的结果质量可控，关键在于指令必须足够清晰、具体，包含我们对代码质量的全部要求。

打开终端，进入项目文件夹，启动Claude Code：

cd comment-analyzer
claude

然后输入以下指令（你可以直接复制，但建议先读一遍，理解每一条要求的用意）：

---

你是AI工程化开发专家。我正在构建一个“评论有效性甄别智能体”。项目已有一份评测规范文档 spec_review_validity.md，它定义了判断评论有效性的四个维度（具体性、可验证性、相关性、信息密度）以及边界规则和输出格式。

请根据这份规范文档，为我生成两个文件：

### 文件1：prompt_template.txt
这是业务智能体的系统提示词。要求：
- 角色设定：你是一个专业的用户评论质量审核员，擅长从海量评论中甄别出真正有参考价值的评论。
- 任务说明：根据评测标准判断评论是否有效。
- 判断标准：严格依据 spec_review_validity.md 中定义的四个维度进行综合判断。
- 输出格式：必须严格输出以下JSON，不包含任何其他文字：
  {
    "valid": true/false,
    "reason": "判定理由，中文，不超过80字",
    "details": {
      "specificity": true/false,
      "verifiability": true/false,
      "relevance": true/false,
      "information_density": true/false
    }
  }
- 边界规则：空输入、纯表情/符号/数字、非中文内容等，按照规范文档处理。
- 语言为中文，专业、清晰、无歧义。

### 文件2：comment_agent.py
这是一个Python脚本，封装业务智能体的调用逻辑。要求：
- 使用 anthropic 库调用Claude API，使用 python-dotenv 从 .env 文件读取API密钥。
- 包含完整的类型注解和中文docstring。
- 核心函数签名为 analyze_comment(comment_text: str, model: str = "claude-sonnet-4-20250514") -> dict。
- 函数必须包含以下健壮性设计：
  a. 输入校验：检查None、非字符串类型、空字符串或纯空格。这些情况直接返回预定义的错误JSON，不调用API。
  b. 超长输入处理：超过2000字符自动截断，并附加提示。
  c. 输出解析容错：如果AI返回的不是合法JSON，尝试用正则提取花括号内的内容。仍然失败则返回错误JSON。
  d. 异常处理：API调用异常时返回错误JSON，不抛出异常。
- 所有错误JSON与正常输出保持相同的结构，valid为false，reason说明原因，details中所有维度为false。
- 在脚本底部包含一个 if __name__ == "__main__": 测试入口，用五条不同类型的评论（含空输入、纯空格、无信息短评、高质量长评、情绪发泄）进行快速测试。
- 代码风格清晰，关键步骤有注释。

请先读取 spec_review_validity.md 的内容，理解规范细节后再生成这两个文件。生成后，分别保存到对应路径。

---

5.1.3 观察Claude Code的执行过程

输入指令后，Claude Code会依次完成以下动作：

1. 读取规范文档：它会先打开 spec_review_validity.md，理解评测维度、边界规则和输出格式要求。
2. 生成Prompt模板：基于规范文档，生成一段结构化的系统提示词，保存为 prompt_template.txt。
3. 生成Python脚本：按照你给出的健壮性要求，生成完整的 comment_agent.py。
4. （可能）自动安装依赖：如果项目环境里还没装 anthropic 和 python-dotenv，Claude Code可能会提示你安装，或者直接帮你执行 pip install。

这个过程通常不超过两分钟。你会在终端里看到它生成的内容概览。

---

5.2 审查AI生成的代码

生成完毕后，不要立即运行。你需要先阅读一遍生成的代码，确认它符合你的预期。这是整个工程化流程中最关键的一步——AI是执行者，你是决策者。

5.2.1 检查Prompt模板

打开 prompt_template.txt，逐条对照以下检查清单：

• 角色设定是否清晰？
• 四个评测维度是否完整，且与规范文档一致？
• 输出格式是否为严格的JSON，没有多余的“好的，这是结果：”之类的引导语？
• 边界规则是否覆盖了空输入、纯表情、非中文内容？
• 有没有AI“自由发挥”添加了规范里没有的规则？（如果有，删除它）

如果发现任何问题，直接在文本编辑器里修改。或者，用Claude Code帮你改——在对话中继续输入：

prompt_template.txt 中有一个问题：它在输出格式里加了“以下是判定结果”这样的引导语。请去掉，只保留纯JSON。

5.2.2 检查Python脚本

打开 comment_agent.py，对照以下检查清单：

• 文件顶部有 import 语句，引入了 os、json、dotenv、anthropic。
• load_dotenv() 和 Anthropic(api_key=...) 的初始化逻辑正确。
• analyze_comment 函数的类型注解和docstring完整。
• 输入校验：if comment_text is None、if not isinstance(comment_text, str)、if not comment_text.strip() 三个检查都有。
• 超长截断：超过2000字符的截断逻辑存在。
• 输出解析：有 json.loads 和正则回退的逻辑。
• 异常处理：try...except 包裹了API调用。
• 所有错误返回的结构与正常输出结构一致，valid 为 False，reason 有说明。
• if __name__ == "__main__": 测试入口有五条测试评论。

一个常见的AI生成问题：有时候Claude Code生成的 except 块会直接 return None 或者只打印错误信息。这不符合我们的健壮性要求——必须返回统一结构的字典。如果你看到这种情况，在对话中要求它修正：

comment_agent.py 的异常处理中，except块应该返回与其他情况结构一致的字典，而不是None。请修正。

---

5.3 首次运行与初步观察

确认代码没有问题后，在终端中运行：

python comment_agent.py

你会看到类似以下的输出（具体结果取决于模型和Prompt）：

--- 测试 1 ---
输入: ''
结果: {"valid": false, "reason": "输入为空", "details": {...}}

--- 测试 2 ---
输入: '   '
结果: {"valid": false, "reason": "输入为空", "details": {...}}

--- 测试 3 ---
输入: '还行吧'
结果: {"valid": false, "reason": "缺少具体描述，信息密度不足", ...}

--- 测试 4 ---
输入: '红烧肉软烂入味...'
结果: {"valid": true, "reason": "包含具体菜品描述和口感细节", ...}

--- 测试 5 ---
输入: '太难吃了！垃圾！'
结果: {"valid": false, "reason": "仅有情绪表达，无具体事实", ...}

现在，花五分钟仔细观察这些输出：

• 空输入和纯空格是否被正确拦截了？（应该看到 "输入为空" 而不需要调用API——你可以在代码里加打印语句验证）
• “还行吧”被判为无效了吗？理由是“缺少具体信息”还是别的？
• 详细好评被判为有效了吗？details 里的四个维度分别是 true 还是 false？
• 情绪发泄被判为无效了吗？理由是否合理？

一个重要提醒：如果你发现某条判断明显不符合你的预期，先记下来，不要立刻改Prompt。我们在第1章已经尝过“凭感觉改Prompt”的苦果。等到第6章，我们会用完整的50条测试集做系统评测，到那时再根据数据精准修改。

当前的目标很简单：智能体跑起来了，格式正确，逻辑基本通顺，没有报错崩溃。 能做到这一点，你已经完成了一次成功的“人机协作开发”。

---

5.4 理解你的工程资产

到目前为止，你的项目目录下应该有这些文件：

comment-analyzer/
├── .env                     # API密钥（不提交Git）
├── .gitignore
├── spec_review_validity.md  # 评测规范文档（第4章产出）
├── test_data.csv            # 黄金标准测试集（第4章产出）
├── prompt_template.txt      # 业务智能体Prompt（本章产出，AI生成）
└── comment_agent.py         # 业务智能体脚本（本章产出，AI生成）

其中，comment_agent.py 是你现在手中最核心的资产。它虽然是由AI生成的，但：

• 你审查过它的逻辑，知道每一段代码在做什么。
• 你理解它的设计原则（输入校验、输出容错、统一错误结构），这些原则会贯穿你今后开发的所有智能体。
• 你可以随时修改它——用Claude Code帮你改，或者自己动手改。

---

5.5 首次Git提交

现在是保存阶段性成果的时刻：

git add comment_agent.py prompt_template.txt
git commit -m "v1.0: 由Claude Code生成的初版评论甄别智能体，经人工审查通过"

你的版本历史中，现在有了第一个可运行的智能体版本。

---

5.6 本章小结

• 我们让AI写了代码，而不是手写代码。给Claude Code一份清晰的指令（包含功能要求、健壮性要求、文件路径），它帮你生成了Prompt模板和完整的Python脚本。
• AI写代码，你来审代码。生成之后，你对照检查清单逐项核查，发现问题直接要求AI修正。这不是“偷懒”，而是更高级的工程协作方式。
• 当前的目标是“跑通”。智能体已经能够正确处理空输入、解析输出、应对异常。具体判断是否准确，我们留给第6章的系统评测来回答。
• 每一次阶段性成果都值得提交。git commit 是你最忠实的开发伙伴。

下一章，我们将搭建自动化评测体系。你会再次用Claude Code生成评测脚本，让“裁判”上场，给你的智能体打出第一个有数据支撑的分数。

---

课后练习

1. 检查你的 comment_agent.py：它是否在调用API之前先检查了空输入？如果没有，请修改代码或让Claude Code帮你修改。
2. 用 comment_agent.py 测试一条超长评论（超过2000字符）。它的截断逻辑是否正常工作？输出结果里有没有“评论过长，已截断”的提示？
3. 如果你对 prompt_template.txt 中某个维度的表述不满意，尝试在Claude Code中要求它修改。修改后重新运行测试，观察输出的变化。
4. （进阶）在 comment_agent.py 中添加一个可选参数 temperature: float = 0.0，并将其传递给 client.messages.create。观察不同 temperature 值对判断结果的影响。

---