📌 这是「量化研究员的AI工作流实战手册」系列的第 2 篇，共 3 篇 上一篇讲了为什么先用 Gemini 规划，这一篇讲具体的 Claude Code 执行架构。

🗺️ 系列导航

⚡ Claude Code 多 Agent 架构实战：量化金融工程的「三权分立」

💡 一个 Claude 不够用。三个 Claude 互相制衡，才是真正可靠的 AI 工程流程——这篇分享我如何在量化金融项目里设计 Agent Swarm。

📍 背景：为什么一个 Claude 会翻车？

先说一个让我印象深刻的教训。

第一次做这个项目，我直接让 Claude Code 写代码。它写出来的程序能跑，测试也通过了。但几天后检查结果时发现：

⚠️ 最终数据集只有 10 万行，而正确答案应该是 140 万行 ⚠️ Rolling Beta 用了手写 for 循环（慢 10 倍以上） ⚠️ 所有 .py 文件全堆在项目根目录——根本没有工程结构

问题不是 Claude 不聪明。问题是：一个 Agent 同时承担了架构师、程序员、测试员、审计员四个角色——这会让任何人翻车。

所以我设计了一个三权分立的 Agent 架构。

🎯 三权分立：核心架构设计

整个架构受到软件工程里"职责分离"原则的启发：让每个 Agent 只做一件事，做到极致。

flowchart TD
    Guide[📋 Guide.md\n宪法文件] --> A

    A[🏛️ 架构师 Architect\nPlan Mode / Sonnet] -->|任务拆解| B
    A -->|测试规格| C

    B[👨‍💻 首席开发 Dev\nSonnet] -->|代码输出| D[代码文件]
    C[🔬 测试工程师 SDET\nSonnet] -->|测试脚本| E[verify_logic.py]

    D --> F{测试通过？}
    E --> F
    F -->|❌ 失败| B
    F -->|✅ 通过| G[📊 输出结果]

    H[🛡️ 金融逻辑卫士\n特定时机唤醒 / Opus] -.->|审计金融逻辑| B

👆 这是完整架构图。注意每个 Agent 的分工是严格隔离的。

📌 Agent 1：架构师（Architect）

角色定位：读懂需求，拆解任务——只负责思考，不写代码。

触发时机：项目开始时，在 Plan Mode 下运行。

输入：Guide.md（上一篇里和 Gemini 共同打磨的宪法文件）

输出：

• 完整的文件结构规划（ src/、 data/、 tests/ 分别放什么）
• 数据流程图（原始文件 → 中间产物 → 最终输出）
• 给 SDET 的测试规格（每个函数应该验证什么）
• 给 Dev 的实施细节（用哪个库、注意哪些边界条件）

🔑 架构师的核心价值：把模糊的需求翻译成可执行的清单。越清晰的任务清单，Dev 出错的概率越低。

实际用法：

你是一个高级量化工程师（架构师角色）。
你的任务是读取 Guide.md，产出完整的实施计划。
你只负责规划，不写任何代码。
计划必须包含：文件结构、数据流程、SDET 测试规格、Dev 实施细节。

📌 Agent 2：测试工程师（SDET）

角色定位：写测试脚本——测试必须在 Dev 开始写代码之前就存在。

这是整个架构里最反直觉、也最重要的设计。

为什么要先写测试？

在量化金融里，一个逻辑错误可能让你的数据完全错误，但代码本身不会报任何错误。

举个例子：

• Lag-1 特征：如果你忘了按股票代码分组再 shift，你的"昨天的收益率"实际上可能是另一只股票的今天收益率——数据能跑，结果是垃圾。
• Winsorization by year vs global：两者都能跑，结果天差地别。

🔑 SDET 的任务就是：造几行假数据，用人为设定的答案，验证代码的金融逻辑是否正确。

实际输出（verify_data_logic.py）：

# SDET 生成的测试脚本示例
import pandas as pd
import numpy as np

def test_lag1_feature():
    """验证 Lag-1 特征必须 by PERMNO 分组"""
    # 造两只股票的假数据
    df = pd.DataFrame({
        'PERMNO': [1, 1, 1, 2, 2, 2],
        'date': pd.date_range('2020-01-01', periods=6),
        'ret': [0.01, 0.02, 0.03, 0.10, 0.20, 0.30]
    })
    # 正确做法：by PERMNO 分组 shift
    df['ret_lag1'] = df.groupby('PERMNO')['ret'].shift(1)

    # 验证：第一只股票第2行的 lag1 应该是 0.01（不是第2只股票的值）
    assert df.loc[1, 'ret_lag1'] == 0.01, "Lag-1 分组逻辑错误！"
    print("✅ Lag-1 测试通过")

def test_winsorization_by_year():
    """验证 Winsorization 必须 by year，不能 global"""
    # 具体验证逻辑...
    pass

这个测试脚本在 Dev 开始写代码之前就存在。Dev 的代码必须通过这些测试，才算完成。

📌 Agent 3：首席开发（Dev）

角色定位：写主程序——基于架构师的规划，在测试的约束下实现功能。

Dev 接收的输入非常明确：

• 架构师输出的任务清单
• SDET 已经写好的测试文件
• Guide.md 里的技术规范

关键约束： ✅ 所有 .py 文件必须放在 src/ 目录下（根目录只放 main.py） ✅ 必须通过 SDET 的所有测试 ✅ Rolling Beta 必须用 statsmodels.regression.rolling.RollingOLS（不允许手写循环） ✅ 每个新增的 Python 包目录都需要 __init__.py

⚡ Agent 4：金融逻辑卫士（可选，Opus 模型）

这是架构里最特殊的一个角色——它不参与日常流程，只在特定场景下被唤醒。

使用 Opus 4.6 的原因：Opus 在复杂推理和专业领域知识上比 Sonnet 强，但日常任务用 Opus 太浪费（贵且慢）。这个 Agent 只在需要深度金融逻辑审计时才开启。

触发场景（三种）：

1️⃣ 实施计划完成时：审计整个数据处理流程的金融逻辑——Lag 方向是否正确、因子构造是否符合学术规范

2️⃣ 出现金融逻辑相关的 Bug 时：比如"为什么我的 Beta 和文献里的数字差这么多"

3️⃣ 写报告时：审计结论的金融解读是否合理

你是一个严格的量化金融逻辑审计员（"金融逻辑卫士"）。
你的唯一任务是从金融逻辑角度审计代码/计划，不写任何代码。
重点检查：时序泄露（look-ahead bias）、因子构造规范性、统计假设合理性。
发现任何问题，必须明确指出并说明为什么它在金融上是错误的。

🔑 并不是所有任务都该用 Opus。简单任务用 Sonnet 更快更便宜，复杂推理才换 Opus。这是资源配置的基本原则。

📌 三个让架构真正 Work 的工程细节

有了架构设计只是第一步，让它真正运转还需要这几个细节：

❶ 宪法文件（Guide.md）是一切的基础

所有 Agent 都从 Guide.md 出发。Guide 越清晰，每个 Agent 的输出质量越高。我在 Guide 里明确写了：

• 禁止在根目录创建逻辑脚本
• 禁止使用手写循环做滚动计算
• ID 匹配必须 Link Score ≤ 2

❷ Human-in-the-loop 的暂停点

架构设计了两个强制暂停点：

• 架构师输出计划后 → 人工审核，确认再让 Dev 开始
• git commit 之后 → 人工检查 .gitignore 是否正确，再 push

🔑 "安全暂停"技巧极好用：在 git push 之前强制暂停，你可以检查 .gitignore 是否漏掉了 5GB 的 CSV 文件。

❸ 同错三次的 Hook 机制

在 Claude Code 的 CLAUDE.md 里写入规则：

如果同一个 Bug 修改三次仍未解决：
1. 停止修改代码
2. 退一步，重新分析根本原因
3. 如果是金融逻辑问题，唤醒"金融逻辑卫士"
4. 向用户报告问题并说明原因

这防止了 Claude 在一个错误方向上死磕，越改越乱。

✨ 总结：关键收获

✅ 收获一：三权分立的核心价值——架构师只规划、SDET 先写测试、Dev 只写代码，职责隔离让每个 Agent 都能做好自己的事 ✅ 收获二：TDD（测试驱动）在量化金融里尤其重要——代码能跑不等于金融逻辑正确，造假数据验逻辑是必须的 ✅ 收获三：Opus 只在需要深度推理时使用，日常用 Sonnet——模型选择也是工程决策 ✅ 收获四：Human-in-the-loop 的强制暂停点，是防止灾难性错误（比如 push 了几 GB 数据文件）的最后防线

💬 写在最后

这套架构的设计过程本身也很有意思——我最开始只有一个模糊的想法"要不要搞多个 agent"，然后在和 Gemini 反复讨论之后才确定了"三权分立"的框架。

架构设计不是一次性的，它是在踩坑中不断演化的。我这套也经过了三次迭代（从单 Agent → 双 Agent → 三 Agent + 卫士）。

你有没有在用 Claude Code 做过多 Agent 设计？遇到过什么坑？评论区聊聊 💬

📌 系列进度: 2/3 ⬅️ 上一篇：为什么我先用Gemini打磨，再让Claude Code执行 ➡️ 下一篇：数据漏洞排查实录：AI法医如何把样本从10万找回140万 — 当你的数据量只有预期的 7%，如何系统地找到根因？

觉得有用的话记得 ⭐收藏 + 👍点赞，方便追完整个系列～ 有问题欢迎评论区交流 💬

#干货分享 #AI工具 #Claude #量化金融 #软件工程 #Agent #TDD #金融工程

📝 备选标题

1. 🔥 【推荐】Claude Code多Agent架构实战：量化工程的「三权分立」（附完整设计图）
2. ⚡ 一个Claude会翻车，三个Claude互相制衡才靠谱｜量化金融工程实战
3. 💡 量化作业的TDD实践：为什么测试工程师要比程序员先动手？