摘要

claude_test_agent 是一个面向测试工程自动化的 Agent 化实践项目。它并不是简单把原有 Python 测试用例生成逻辑搬到大模型里，而是尝试将“测试用例设计工作流”拆分为可被 Claude Code 调度的 Skill 节点，并由 Python Runtime 负责状态机、校验、路由和导出，从而形成一种更工程化、可审计、可扩展的智能测试用例生成体系。

从工程定位上看，claude_test_agent 解决的是测试资产生成环节的问题：给定 AUTOSAR、RCP 或 Web 等领域需求输入，系统通过一组明确的节点完成测试点设计、测试点门禁、测试用例生成、覆盖映射、用例集合校验、单条用例评审和结果导出。与传统“一次性调用大模型生成所有内容”的方式相比，该项目更强调流程拆解、状态持久化、节点校验、失败回跳和交付产物可追踪。

本文结合仓库设计与已有实现思路，梳理 claude_test_agent 的技术架构、核心流程、与原 LangGraph 版本的关系，以及后续可拓展方向。

---

1. 项目背景：为什么要从 LangGraph 工作流走向 Claude Code Skill Runtime

在早期 test_agent 设计中，测试用例生成主要采用 Task / Workflow / Registry / Orchestrator 模型，并通过 LangGraph 编排测试用例设计流程。公共测试用例设计引擎承担父图与子图的执行：父图负责测试点设计、用例生成、覆盖映射、集合校验和最终输出；子图负责单条测试用例的格式检查与内容评审。

这种模式的优点是工程结构清晰、状态转移明确、适合在 Python 服务中统一运行。但当目标变成“让 Claude Code 直接参与测试用例生成过程”时，原有 LangGraph 方案会遇到几个问题：

1. 模型调用与流程控制耦合较重：节点逻辑、Prompt、状态字段和路由规则容易混杂在 Python Workflow 中。
2. Claude Code 的交互能力没有充分利用：Claude Code 更适合通过 Skills、Hooks、文件系统上下文和命令行工具参与工程任务。
3. 中间过程不够天然可审计：虽然 Python 状态可以记录，但对于人机协作式工作流，更适合把每一步节点输入、输出、校验结果显式落盘。
4. 后续领域扩展成本较高：如果每个领域都复制一套图节点，Prompt、模板、规则和导出逻辑容易分散。

因此，claude_test_agent 的核心思路不是简单恢复原 LangGraph，也不是完全依赖 Claude Subagent，而是采用：

Claude Code Orchestrator 负责调度，Skills 负责节点能力，Python Runtime 负责确定性状态机、校验、路由和导出。

这种架构可以理解为“Skill Direct Runtime”：Skill 直接承担内容生成任务，而 Python Runtime 只处理可确定、可验证、可复现的工程逻辑。

---

2. 总体架构：Orchestrator + Skills + Runtime + Hooks

claude_test_agent 的整体架构可以拆成四层。

用户输入 / 需求文档 / 任务参数
        ↓
Claude Code Orchestrator Agent
        ↓
.claude/skills/testcase-* 节点技能
        ↓
Python Runtime CLI / State Machine / Validator / Exporter
        ↓
.runs/{run_id}/ 状态、节点输出、校验结果、最终测试用例

2.1 Orchestrator Agent：只做调度，不做业务细节

Orchestrator Agent 的职责是维护整体执行节奏：初始化任务、按路由结果调用下一个 Skill、在节点结束后触发校验、根据 Runtime 的路由结果决定继续、回跳或导出。

它不应该直接实现测试用例生成规则，也不应该直接修改核心状态文件。这样做的好处是：

• 主控逻辑简单，便于排查；
• 业务能力下沉到 Skill，领域差异更容易隔离；
• 状态流转交给 Python Runtime，避免大模型随意改状态；
• 后续可以替换 Claude Code 调度入口，而不影响核心 Runtime。

2.2 Skills：面向节点的最小能力单元

仓库中围绕测试用例设计流程拆分了一组 Skill 节点，例如：

testcase-init-run
testcase-design-testpoints
testcase-gate-testpoints
testcase-design-cases
testcase-map-coverage
testcase-validate-case-set
testcase-review-cases
testcase-build-output
testcase-complete-node
testcase-route-next
testcase-validate-output
testcase-export-result

每个 Skill 只负责一个明确职责。例如：

Skill	主要职责
testcase-init-run	初始化一次运行，创建 .runs/{run_id} 目录与初始状态
testcase-design-testpoints	基于需求上下文生成候选测试点
testcase-gate-testpoints	对测试点做门禁校验，判断是否可冻结为 canonical test points
testcase-design-cases	基于冻结后的测试点生成测试用例
testcase-map-coverage	建立测试用例与测试点之间的覆盖关系
testcase-validate-case-set	对用例集合做编号、覆盖、重复、异常输入等规则校验
testcase-review-cases	对单条测试用例进行格式与内容复核
testcase-complete-node	节点结束时写入输出、快照和状态更新
testcase-route-next	根据当前状态计算下一节点
testcase-export-result	导出 JSON、Excel 或最终交付结构

这种拆分方式的关键不是“把 Prompt 分成多个文件”，而是把测试用例生成流程变成一个可控的状态机，每个节点有输入、有输出、有校验、有边界。

2.3 Python Runtime：确定性工程逻辑的承载层

在该架构中，Python Runtime 不负责“创作性生成”，而负责确定性逻辑，包括：

• 初始化运行目录；
• 维护 manifest.json 与 current_state.json；
• 保存节点输出和快照；
• 校验节点输出字段；
• 校验测试点与测试用例集合；
• 计算下一节点；
• 导出最终 JSON / Excel；
• 防止非法状态修改。

典型 CLI 工具可以包括：

init_agent_team_run.py
route_next_node_cli.py
validate_node_output_cli.py
validate_case_set_cli.py
complete_node_task.py
export_testcase_excel_cli.py

Runtime 的设计原则是：大模型可以生成内容，但不应该直接决定状态是否合法；状态是否合法必须由规则和 Runtime 判断。

2.4 Hooks：守住状态边界和流程门禁

Hooks 用于约束 Claude Code 的行为，避免模型在执行过程中绕过 Runtime 直接改写核心文件。典型约束包括：

• 禁止直接修改 .runs/{run_id}/state/current_state.json；
• 禁止直接修改 .runs/{run_id}/manifest.json；
• 节点输出必须先通过 validate_node_output_cli.py；
• 测试用例集合必须通过 validate_case_set_cli.py；
• 节点完成必须通过 complete_node_task.py 写入状态。

Hooks 的价值在于把“生成自由度”和“工程边界”分开。Claude 可以在 Skill 内生成候选内容，但最终写入和流转必须经过 Runtime。

---

3. 运行目录设计：让每一次生成过程都可追踪

claude_test_agent 的一次运行建议使用 .runs/{run_id} 作为工作目录。一个典型目录结构如下：

.runs/{run_id}/
├── manifest.json
├── state/
│   └── current_state.json
├── snapshots/
│   ├── 000_initial.json
│   ├── 001_testpoint_designer.json
│   └── ...
├── node_outputs/
│   ├── testcase-design-testpoints.json
│   ├── testcase-gate-testpoints.json
│   ├── testcase-design-cases.json
│   └── ...
├── artifacts/
│   ├── final_testcases.json
│   └── final_testcases.xlsx
└── logs/
    └── run.log

其中：

文件或目录	作用
manifest.json	记录运行 ID、领域、输入文件、当前节点、运行状态等元信息
state/current_state.json	保存业务状态，例如需求、测试点、测试用例、覆盖映射、校验结果
snapshots/	保存每个节点后的状态快照，便于回溯和调试
node_outputs/	保存每个 Skill 的原始输出
artifacts/	保存最终可交付产物
logs/	保存运行日志和异常信息

这种设计对测试用例生成任务非常关键。因为测试用例不是一次性文本输出，而是工程交付资产。测试点为何生成、哪些测试点被门禁拒绝、用例为什么回跳、最终导出的字段从何而来，都应该有记录。

---

4. 核心流程：从需求到测试用例的 Skill 调用链路

claude_test_agent 的核心链路可以抽象为：

testcase-init-run
        ↓
testcase-design-testpoints
        ↓
testcase-gate-testpoints
        ↓
testcase-design-cases
        ↓
testcase-map-coverage
        ↓
testcase-validate-case-set
        ↓
testcase-review-cases
        ↓
testcase-complete-node
        ↓
testcase-export-result

4.1 测试点设计

testcase-design-testpoints 接收需求内容、领域 Profile、模板约束和历史状态，输出候选测试点。测试点是后续测试用例设计的锚点，不能只生成泛泛描述，而应包含：

• 测试点 ID；
• 关联需求编号；
• 输入类别；
• 操作动作；
• 预期结果；
• 正常场景 / 异常场景 / 边界场景分类。

4.2 测试点门禁

testcase-gate-testpoints 对候选测试点进行规则校验和语义评审。门禁通过后，测试点会被冻结为 canonical_test_points。

冻结机制很重要。后续测试用例可以修复描述，但不能随意改变覆盖范围。这样可以避免模型在反复修复过程中“越修越偏”，导致原始需求覆盖丢失。

4.3 测试用例生成

testcase-design-cases 基于冻结后的测试点生成测试用例。这里的用例不是自然语言说明，而应是结构化数据，通常包含：

• 用例编号；
• 关联需求编号；
• 关联测试点 ID；
• 前置条件；
• 输入数据；
• 操作步骤；
• 预期结果；
• 用例类型；
• 优先级；
• 自动化可行性。

4.4 覆盖映射

testcase-map-coverage 建立测试用例与测试点之间的映射关系。该节点用于回答一个关键问题：

当前测试用例集合是否覆盖了所有已冻结测试点？

覆盖映射不是可有可无的附加信息，而是后续 case set 校验和回跳修复的依据。

4.5 用例集合校验

testcase-validate-case-set 属于强规则节点。它应尽量少依赖大模型，而更多依赖确定性规则，例如：

• 是否存在未覆盖测试点；
• 是否存在重复用例；
• 是否存在一个用例覆盖多个不应合并的测试点；
• 是否存在缺失字段；
• 用例编号是否规范；
• 正常 / 异常 / 边界场景是否均衡；
• 是否修改了 locked cases；
• 是否存在不支持自动化执行的描述。

若校验失败，Runtime 可以生成修复任务，并路由回 testcase-design-cases。

4.6 单条用例评审

testcase-review-cases 更关注单条用例的格式、描述、可执行性和一致性。它可以修复描述性问题，但不应修改覆盖相关字段，例如：

• 测试点 ID；
• 相关需求编号；
• 输入类别；
• 核心操作动作；
• 核心预期结果。

这对应了原 LangGraph 子图中“允许修复描述，不允许改变覆盖”的思想。

4.7 最终导出

testcase-export-result 将最终通过校验的测试用例导出为 JSON 或 Excel。后续若接入自动化测试平台，也可以进一步生成 pytest 脚本、Test_Framework 用例目录或测试报告模板。

---

5. 与原 LangGraph 版本的关系：不是推翻，而是迁移执行形态

claude_test_agent 与原 test_agent / origin 的关系可以概括为：

保留原工作流语义，替换执行载体。

原 LangGraph 版本强调：

testpoint_designer
    → testpoint_gate
    → testcase_designer
    → coverage_mapper
    → case_set_validator
    → case_runner
    → final_output

claude_test_agent 则将这些节点拆成 Claude Code 可调用的 Skills，同时由 Runtime 复刻原有路由行为。也就是说，它不是把所有逻辑交给 Claude 自由发挥，而是要求 Skill 节点职责、Prompt 内容、状态字段、输出结构和回跳逻辑尽量对齐原 origin 版本。

这种迁移方式的价值在于：

1. 复用原工作流经验：不重新发明测试用例设计流程。
2. 增强 Claude Code 工程协作能力：让 Claude 直接在仓库上下文中按节点执行。
3. 保留确定性校验：路由、字段、导出、状态写入仍由 Python 控制。
4. 提升可调试性：每个节点输出独立落盘，失败原因更容易定位。

---

6. 领域扩展机制：Profiles / Prompts / Templates / Rules

为了支持 AUTOSAR、RCP、Web 等不同领域，claude_test_agent 不应该把领域知识硬编码在 Skill 里，而应通过领域配置扩展。

推荐结构如下：

test_agent/
├── design_autosar_testcase/
│   ├── profile.py
│   ├── prompts/
│   ├── templates/
│   └── rules/
├── design_rcp_testcase/
│   ├── profile.py
│   ├── prompts/
│   ├── templates/
│   └── rules/
├── design_web_testcase/
│   ├── profile.py
│   ├── prompts/
│   ├── templates/
│   └── rules/
└── testcase_design_engine/
    └── runtime/

不同领域只替换：

• 需求解析方式；
• Prompt 模板；
• 测试用例字段模板；
• 规则校验器；
• 导出格式；
• 领域术语和测试设计原则。

公共 Runtime 不关心是 AUTOSAR 还是 RCP，它只关心当前状态是否合法、节点输出是否满足 Schema、下一步应该路由到哪里。

---

7. 工程设计中的关键取舍

7.1 为什么不是完全使用 Subagent

Subagent 适合隔离上下文、执行独立评审、做局部分析，但如果把每个业务节点都做成 Subagent，容易带来上下文传递复杂、状态一致性难保证、输出格式不稳定等问题。

因此，claude_test_agent 更适合采用 Skill Direct 的方式：Skill 是主流程节点，Subagent 可作为辅助能力用于复杂评审或离线分析。

7.2 为什么 Runtime 不直接生成内容

Runtime 的职责是确定性工程逻辑。如果 Runtime 也负责生成内容，就会重新回到传统 Python Workflow 模式，Claude Code 的工程协作能力无法体现。

更合理的边界是：

Skill：生成候选内容
Runtime：校验、路由、落盘、导出
Hooks：限制非法修改

7.3 为什么要保留 current_state.json

测试用例生成是多阶段任务。仅依赖对话上下文无法保证长期稳定，尤其是多轮回跳、节点失败重试、人工介入修改时。因此必须有显式状态文件作为单一事实源。

current_state.json 的存在使系统具备：

• 可恢复运行；
• 可审计过程；
• 可比较快照；
• 可复现导出；
• 可做自动化测试。

---

8. 与 Test_Framework 的关系：生成测试资产，执行测试资产

如果将 claude_test_agent 放入更大的测试平台体系中，它与 Test_Framework 的关系可以这样理解：

模块	主要职责
claude_test_agent	需求解析、测试点设计、测试用例生成、用例校验、测试资产导出
Test_Framework	UI 编排、配置驱动、pytest 执行、公共库调用、日志抓包、报告产出

两者结合后，可以形成完整闭环：

需求文档
  ↓
claude_test_agent 生成测试点和测试用例
  ↓
导出 JSON / Excel / pytest 脚本候选
  ↓
Test_Framework 筛选与执行
  ↓
日志 / pcap / HTML 报告
  ↓
AI 辅助分析失败原因并反哺测试资产

这里的关键是职责分离。claude_test_agent 不需要直接控制硬件、抓包或执行测试；Test_Framework 也不需要理解需求文档如何拆解成测试点。一个负责测试资产生成，一个负责测试资产执行。

---

9. 后续可拓展方向

9.1 从测试用例生成扩展到测试脚本生成

当前系统已经具备测试用例生成的流程基础。下一步可以接入脚本生成能力：

测试用例 JSON
  ↓
分析 Test_Framework Library API
  ↓
检索历史测试脚本示例
  ↓
生成 pytest 测试脚本骨架
  ↓
Claude 补全测试逻辑
  ↓
python -m py_compile / pytest collect 校验

这样可以把测试资产从“可读用例”推进到“可执行脚本”。

9.2 接入 Test_Framework 自动执行

在导出用例或脚本后，可以进一步调用 Test_Framework 执行入口：

• 自动写入测试配置；
• 自动筛选目标用例；
• 调用 pytest 执行；
• 采集 log、pcap、HTML report；
• 将执行结果写回 .runs/{run_id}/artifacts/。

最终平台可以从“生成测试用例”升级为“生成并执行测试用例”。

9.3 增强失败分析与报告评审

执行完成后，可以增加 AI 报告评审节点：

HTML 报告 / pytest 输出 / 日志 / pcap
        ↓
失败定位
        ↓
协议字段解析
        ↓
用例问题 / DUT 问题 / 环境问题分类
        ↓
生成缺陷摘要或复测建议

这会让系统从设计阶段扩展到测试闭环阶段。

9.4 引入知识库与 RAG

对于 AUTOSAR、RCP、诊断、通信协议等领域，Prompt 本身不能承载所有知识。后续可以增加 RAG 能力：

• 检索 AUTOSAR SWS 需求片段；
• 检索历史测试用例；
• 检索已有缺陷和问题单；
• 检索 Test_Framework 公共库 API 文档；
• 检索项目特定约束。

RAG 的结果可以作为 Skill 输入上下文，而不是让模型凭空生成。

9.5 建立质量评价指标

为了避免系统只停留在“能生成”，需要建立质量指标：

指标	含义
JSON 合法率	节点输出是否可解析
Schema 通过率	字段是否完整、类型是否正确
需求覆盖率	测试点是否覆盖目标需求
测试点覆盖率	测试用例是否覆盖所有 canonical test points
重复率	是否存在语义重复用例
可执行性	是否能转成自动化脚本或手工步骤
回跳收敛率	多轮修复后是否能通过校验
人工修改率	导出前人工需要改多少内容

这些指标可以帮助判断系统是否真正提升测试设计效率。

9.6 多领域 Profile 化

后续可以将 AUTOSAR、RCP、Web 进一步 Profile 化：

profile = {
  domain: "autosar_cp",
  requirement_parser: ...,
  prompt_pack: ...,
  schema: ...,
  rule_checker: ...,
  exporter: ...
}

新增领域时，不修改核心 Runtime，只新增领域 Profile、Prompt、模板和规则。

9.7 MCP 化与平台化调用

如果系统需要被其他平台调用，可以将 Runtime 能力封装为 MCP Tools 或 HTTP API：

• init_run；
• run_skill_node；
• validate_node_output；
• route_next_node；
• export_result；
• query_run_status。

这样 Claude Code、Web UI、CI/CD 或内部测试平台都可以复用同一套 Runtime。

---

10. 总结

claude_test_agent 的价值不在于“用 Claude 生成一批测试用例”，而在于把测试用例设计流程工程化：

• 用 Orchestrator 控制流程；
• 用 Skills 承载节点能力；
• 用 Python Runtime 管理状态、校验、路由和导出；
• 用 Hooks 限制非法修改；
• 用 .runs/{run_id} 保存完整过程证据；
• 用 Profiles 支撑 AUTOSAR、RCP、Web 等领域扩展。

这种设计让大模型能力从“文本生成工具”变成“测试工程流程中的受控节点”。它既保留了 Claude Code 在代码仓库、文件系统和任务协作中的优势，又避免了将关键状态和流程判断完全交给大模型。

从后续演进看，claude_test_agent 可以继续向三个方向扩展：

1. 测试资产生成闭环：从需求到测试点、测试用例、测试脚本。
2. 自动化执行闭环：与 Test_Framework 打通，实现生成后自动执行。
3. 质量反馈闭环：基于执行日志、报告和缺陷信息反哺测试设计。

最终，它可以演进为一个覆盖“需求解析—测试设计—脚本生成—自动执行—证据分析”的智能测试工程平台。