personalization-subagent-pattern

个性化子 Agent 模式

大规模个性化冷邮件需要针对每条潜在客户信息生成内容。Claude Code 的 Task 工具可让你并行分派多个子 Agent，各自为潜在客户名单中的一部分进行个性化处理。本技能定义了可复用的审批循环模式。

始终使用 Task 工具——绝不使用 API 密钥

此技能完全通过 Task 工具在 Claude Code 内运行。不调用 Anthropic SDK，也不调用 OpenAI。这是有意为之：

• 无需额外 API 费用。 使用你的 Claude Code 套餐。
• 无需管理密钥。 开箱即用。
• 原生支持并行。 Claude Code 可在一条消息中启动多个 Task 子 Agent，让 100 条潜在客户信息在处理 10 条所需的时间内完成个性化处理。

规模特别大时（1,000 条以上潜在客户信息），可以选择将调优后的提示词交给 Anthropic API，以提高吞吐量。但调优和常规营销活动（少于 500 条潜在客户信息）始终通过 Task 工具进行。

审批循环（全面并行处理之前）

不要先为 500 条潜在客户信息生成个性化内容，再发现提示词有问题。先循环调整，再扩大规模。

第 0 轮——在 1 条潜在客户信息上测试

1. 从批次中挑选一条 company_description 丰富的潜在客户信息。
2. 向用户展示：“这是我正在处理的公司描述。根据这些信息，你会如何进行个性化处理？”
3. 展示你（Claude）会为 situation_line、value_line、cta_soft 生成的内容。
4. 询问：“感觉合适吗？请修改，我会重新调优。”

第 1 至 N 轮——每批 10 条并征求批准

1. 使用当前提示词和 10 条潜在客户信息，启动一个 Task 子 Agent。
2. 在表格中展示全部 10 条结果：

   Lead                  | situation_line                          | value_line                    | cta_soft
   [email protected]         | You're building the only APM for Ruby.  | Our Ruby customers find ...   | Worth 10 min?
   [email protected]      | ...                                     | ...                           | ...
   

3. 询问：“有什么需要修改的吗？请指出行号，并说明问题。”
4. 如果用户提出修改，请更新提示词（或添加“绝不使用 X 这个词”之类的规则），然后重新运行新的一批。
5. 如果用户连续 2 轮都没有任何修改，则锁定提示词。将处理范围扩大到完整名单。

扩大规模——全面并行处理

锁定提示词后：

• 将剩余潜在客户信息拆分为每批 10 至 20 条。
• 启动 3 至 10 个并行 Task 子 Agent（每个负责一个变体 × 一个批次）。
• 按 lead_id 合并结果。

适用场景

• 任何需要为每条潜在客户信息设置自定义变量的营销活动（不只是 {first_name}）
• 有 50 条以上潜在客户信息，且希望实现个性化处理而无需手动撰写
• /auto-research-public 或类似的编排技能需要并行进行个性化处理

不适用场景

• 小批次（少于 10 条潜在客户信息）——直接在主对话中进行个性化处理即可（无需并行分派）
• 静态文案（给每条潜在客户信息发送相同的邮件）——个性化处理会浪费 token

适用场景

• 任何需要为每条潜在客户信息设置自定义变量的营销活动（不只是 {first_name}）
• 有 50 条以上潜在客户信息，且希望实现个性化处理而无需手动撰写
• /auto-research-public 或类似的编排技能需要并行进行个性化处理

不适用场景

• 小批次（少于 20 条潜在客户信息）——直接在主对话中进行个性化处理即可
• 静态文案（给每条潜在客户信息发送相同的邮件）——个性化处理会浪费 token

模式

1. 准备潜在客户批次

并行分派之前，潜在客户批次应为 JSON 数组，其中每条信息都包含：

{
  "lead_id": "<stable identifier>",
  "first_name": "<str>",
  "last_name": "<str>",
  "email": "<str>",
  "company_name": "<str>",
  "company_domain": "<str>",
  "company_description": "<1-3 sentences about what the company does>",
  "title": "<str>",
  "linkedin_url": "<optional>",
  "enrichment_data": { ... any extra signals ... }
}

company_description 越详细，个性化效果越好。如果只有公司名称，生成的内容就会比较笼统。

2. 定义输出架构

提前确定每个子 Agent 必须返回哪些字段。示例：

{
  "lead_id": "<same id>",
  "situation_line": "<1 sentence — what you noticed about their company>",
  "value_line": "<1 sentence — connecting their situation to your offer>",
  "cta_soft": "<1 sentence — soft ask, e.g. 'worth a 15 min chat?'>"
}

字段越少，出错的可能性就越低。默认每个变体最多使用 3 个字段。

3. 拆分为不同变体（A/B/C）

如果要测试 3 种文案变体，则为每家公司（或每个批次）启动 3 个并行子 Agent。每个子 Agent 使用不同的切入角度提示词：

• 变体 A：以对痛点的观察开场。“注意到你们的网站上有 X……”
• 变体 B：以赞赏加过渡开场。“你们处理 Y 的方式很独特……”
• 变体 C：以提问开场。“你们如何看待 Z？”

这样可以从一份名单中获得 3 倍的数据——你可以进行 A/B/C 测试，看看哪种切入角度更能引起共鸣。

4. 批次大小

• 小批次是合适的默认选择：每个子 Agent 处理 10-20 条潜在客户线索。
• 批次越大 = Agent 越少 = 成本越低，但质量越差（Agent 会丢失上下文）
• 批次越小 = Agent 越多 = 质量越高，但主 Agent 的上下文占用也越多

对于 100 条潜在客户线索：

• 10 个子 Agent × 每个处理 10 条 = 质量不错
• 5 个子 Agent × 每个处理 20 条 = 更快
• 2 个子 Agent × 每个处理 50 条 = 质量下降

对于 1000 条潜在客户线索：

• 考虑按每轮 100 条运行（避免主 Agent 达到上下文限制）
• 每轮启动 10 个子 Agent，每个处理 10 条

5. 子 Agent 提示词模板

每个个性化子 Agent 都会收到以下结构的提示词：

You are personalizing cold email fields for N leads.

CONTEXT:
- We sell: <one sentence from client-profile.yaml>
- Our ICP: <one sentence>
- Our offer: <the CTA we're asking them to respond to>
- Tone: <casual | formal | peer-to-peer>

FIELDS TO GENERATE (per lead):
- situation_line: <definition + 1 good example + 1 bad example>
- value_line: <definition + 1 good example + 1 bad example>
- cta_soft: <definition + 1 good example + 1 bad example>

RULES:
1. Never fabricate facts. If the company description is thin, say something generic but not false.
2. Never use em dashes (—). Use periods or commas.
3. Never use the word "leverage", "synergy", "ecosystem".
4. Maximum length: <N words per field>.
5. If a lead is missing company_description, return "<fields cannot be generated — skip>"

LEADS:
<JSON array>

RETURN:
A JSON array with the same lead_ids and the personalization fields. Save to /tmp/personalization-<batch-id>.json and print "DONE" when complete.

6. 扇出代码模式

协调器的伪代码（在主 Claude Code 对话中运行）：

leads = load leads from JSON
batches = chunk leads into groups of 10-20

for each batch:
  for each variant in [A, B, C]:
    Task(
      description: "Personalize batch <i> variant <v>",
      subagent_type: "general-purpose",
      prompt: <template above with variant-specific angle>
    )

# All tasks run in parallel (multiple tool calls in one message)

Wait for all tasks to finish, then read /tmp/personalization-*.json and merge.

或者，在一条消息中通过多个 Task 调用一次性启动所有任务：

# Launch 3 parallel sub-agents for one batch (variants A, B, C)
Task(description: "batch-1-variant-A", ...)
Task(description: "batch-1-variant-B", ...)
Task(description: "batch-1-variant-C", ...)

7. 错误处理

子 Agent 可能会：

• 返回格式错误的 JSON
• 跳过潜在客户线索（如果数据过于单薄）
• 拒绝生成内容（如果内容似乎有风险）

协调器应当：

1. 验证每个返回的 JSON 都符合输出架构
2. 对于缺失的 lead_ids：使用强调不得跳过的“严格模式”提示词重试一次
3. 对于确实无法个性化的潜在客户线索（缺少描述）：将其标记为 personalization_status: "skipped"，并改用静态文案

绝不要发布包含 "cannot be generated" 或类似字符串的个性化字段——上传前应将其过滤掉。

8. 合并并上传

所有子 Agent 完成后：

1. 读取 /tmp/personalization-*.json 文件
2. 按 lead_id 合并
3. 每条潜在客户线索现在都有：

   {
     ...original lead fields,
     "variant_a": { "situation_line": "...", "value_line": "...", "cta_soft": "..." },
     "variant_b": { ... },
     "variant_c": { ... }
   }
   

4. 上传到 Smartlead/Instantly 时，将每个字段映射到一个自定义变量。约定：
   • Smartlead：使用 {{situation_line_a}}、{{value_line_a}} 等
   • 如果运行 3 个 A/B/C 活动，则将 variant_a 字段上传到活动 A，variant_b 上传到活动 B，以此类推。

审批循环停止规则

满足以下任一条件时，循环会自动退出：

• 用户连续 2 轮、每轮 10 条潜在客户线索都未提出任何修改，或
• 用户明确表示“就这样，扩大规模”

停止时：

1. 将最终调整好的提示词保存到 ~/cold-email-ai-skills/profiles/<business-slug>/personalization-prompt.txt
2. 保存一条 client-profile.yaml 元数据：

   personalization_prompt:
     path: profiles/<slug>/personalization-prompt.txt
     variant_count: 3
     tuned_at: YYYY-MM-DD
     rounds_to_convergence: 3
   

3. 对剩余的潜在客户线索启动并行扇出。

如果用户在 2 轮审批通过后，于第 N+1 轮提出修改，也没关系——计数器会重置，循环继续。

质量检查

上传前，手动随机抽查每个变体的 5 条潜在客户线索。常见问题：

• 不同潜在客户线索间重复（子 Agent 把同一句话写了 10 次）→ 添加多样性指令后重试该批次
• 事实性错误（声称公司在做 X，但实际上在做 Y）→ 在提示词中加强“绝不捏造”规则
• 措辞不自然（每次都使用“I was intrigued by...”之类的 AI 腔表达）→ 添加禁用短语列表
• 含糊或模棱两可（“贵公司可能在做 X……”）→ 添加规则：“直接断言，不要含糊”

参考资料

• references/prompt-template.md — 可复制粘贴的提示词模板
• references/example-output.json — 个性化处理良好的批次示例
• references/failure-modes.md — 常见的子 Agent 故障及其检测方法

接下来要做什么

这是一份模式文档，不是独立技能。 当 /auto-research-public 和 /campaign-copywriting 需要大规模逐条个性化处理时，会调用它。

如果你是直接阅读本文档，那么你很可能正在设计新的活动编排流程——请返回将你引导到这里的技能。

相关技能

• /auto-research-public — 此模式的主要使用方
• /icp-onboarding — 生成提示词所需的 client-profile.yaml
• /cold-email-starter-kit 会引用 03-campaign-copywriting.md 中的文案原则，供提示词执行