Claude HowTo 实战：用 data-scientist 子代理为 Claude Code 打造 SQL 与 BigQuery 数据分析专家-平芜编程栈

Claude HowTo 实战：用 contenteditable="false">【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto

导读

在 Claude Code 中，子代理（Subagent）是拥有独立上下文窗口、专属系统提示词与受限工具集的专职 AI 助手，适用于把大型任务拆解给专业角色并行处理。本文以仓库提供的 uk/04-subagents/data-scientist.md 为骨架，完整讲解如何部署一个专职数据分析子代理：它负责编写优化的 SQL 查询、通过bq命令行操作 BigQuery、汇总统计结果并输出数据驱动的结论。读完本文，你将掌握该子代理的完整定义文件、每个配置字段的含义、它的内置工作流程与分析规范，并能直接复制到自己的项目中投入使用。

1. 文件全貌：一份可复制的子代理定义

仓库04-subagents/目录下存放着一批"开箱即用"的示例子代理，data-scientist.md是其中之一。整份文件由两部分组成：YAML frontmatter（元数据）与Markdown 系统提示词（角色行为定义）。这与 Claude Code 的标准子代理文件格式完全一致——Claude Code 通过在.claude/agents/<name>.md中放置同类文件来加载自定义子代理，详见 04-subagents/README.md。

uk/04-subagents/data-scientist.md的 frontmatter 如下：

--- name:># 运行查询（关闭 Legacy SQL，使用标准 SQL） bq query --use_legacy_sql=false 'SELECT * FROM dataset.table LIMIT 10' # 导出查询结果为 CSV 文件 bq query --use_legacy_sql=false --format=csv 'SELECT ...' > results.csv # 获取表的 schema 结构 bq show --schema dataset.table

参数说明：

--use_legacy_sql=false：强制使用 BigQuery 标准 SQL（SELECT *、DATE_TRUNC等语法均需标准 SQL 支持），务必保留
--format=csv：将查询结果以 CSV 格式输出，配合>重定向可落盘为results.csv，供后续分析与汇报使用
bq show --schema dataset.table：在编写查询前先探查表结构，属于"理解需求→探查数据→写查询"流程中的关键一步

结合文件结构可推断，Read工具负责读取需求与结果文件，Bash工具负责执行上述bq命令，Write工具负责把分析结论与结果落盘——三者配合构成完整的数据分析闭环。

6. 三类分析任务（Analysis Types）

系统提示词把该子代理能承接的分析工作归纳为三类，每类附带了具体动作清单：

6.1 探索性分析（Exploratory Analysis）

数据画像（Data profiling）
分布分析（Distribution analysis）
缺失值检测（Missing value detection）

适用场景：新数据集上手、数据质量初检、特征与字段盘点。

6.2 统计分析（Statistical Analysis）

聚合与汇总（Aggregations and summaries）
趋势分析（Trend analysis）
相关性检测（Correlation detection）

适用场景：业务指标走势、事件规律、变量关联关系验证。

6.3 报表输出（Reporting）

关键指标提取（Key metrics extraction）
周期对比（Period-over-period comparisons）
管理层摘要（Executive summaries）

适用场景：周报/月报数据支撑、向上汇报、跨周期业绩对比。

7. 标准输出格式：每次分析的固定骨架

为保证结论一致、可追溯，文档规定该子代理的每一次分析都必须按以下五个字段组织输出：

Objective（目标）：我们在回答什么问题
Query（查询）：使用的 SQL（带注释）
Results（结果）：关键发现
Insights（洞察）：基于数据的结论
Recommendations（建议）：建议的下一步行动

这套"目标—查询—结果—洞察—建议"的五段式结构，让数据分析产出天然具备"可复现、可引用、可决策"的特征，也方便主代理直接把这些字段拼接进最终回复。

8. 内置示例查询：月度活跃用户趋势

文档内置了一条带注释的示例 SQL，用于演示该子代理的查询风格——这是理解其 SQL 规范的最佳范本：

-- Monthly active users trend SELECT DATE_TRUNC(created_at, MONTH) as month, COUNT(DISTINCT user_id) as active_users, COUNT(*) as total_events FROM events WHERE created_at >= DATE_SUB(CURRENT_DATE(), INTERVAL 12 MONTH) AND event_type = 'login' GROUP BY 1 ORDER BY 1 DESC;

这条查询集中体现了前文的全部优化原则：

注释先行：首行用--注释说明查询意图
避免SELECT *：只投影month、active_users、total_events三个必要列
尽早过滤：WHERE同时限定 12 个月时间窗口与event_type = 'login'事件类型，减少进入聚合的数据量
合理聚合：COUNT(DISTINCT user_id)计算去重活跃用户，COUNT(*)统计事件总量，按DATE_TRUNC(created_at, MONTH)月维度聚合
结果可控：ORDER BY 1 DESC按月份倒序，便于观察最新趋势

将其改写为bq命令行即可直接执行：

bq query --use_legacy_sql=false --format=csv ' SELECT DATE_TRUNC(created_at, MONTH) as month, COUNT(DISTINCT user_id) as active_users, COUNT(*) as total_events FROM events WHERE created_at >= DATE_SUB(CURRENT_DATE(), INTERVAL 12 MONTH) AND event_type = "login" GROUP BY 1 ORDER BY 1 DESC;' > mau_trend.csv

9. 分析检查清单（Analysis Checklist）

文档在结尾固化了子代理交付前的自检清单，确保每次分析完整收尾：

需求已理解（Requirements understood）
查询已优化（Query optimized）
结果已校验（Results validated）
发现已记录（Findings documented）
建议已提供（Recommendations provided）

这五条检查项与第 2 节的五步流程、第 7 节的五段输出格式一一呼应，构成"流程—产出—质检"的完整闭环，是系统提示词设计中的良好示范。

10. 安装与使用：将>Create a project-level subagent that analyzes data with SQL and BigQuery. Give it access to Bash, Read, and Write.

Claude 会写出带合适 frontmatter 的.claude/agents/data-scientist.md文件（注意：自 v2.1.198 起/agents交互式创建向导已移除，建议直接让 Claude 生成或手动编辑文件）。

方式二：从仓库复制。将本文件复制到项目或用户级 agents 目录：

# 项目级（仅当前项目可用） mkdir -p .claude/agents cp 04-subagents/data-scientist.md .claude/agents/ # 用户级（所有项目可用） mkdir -p ~/.claude/agents cp 04-subagents/data-scientist.md ~/.claude/agents/

安装后可用claude agents命令确认子代理已被识别（参见 04-subagents/README.md 的claude agentsCLI 一节）。

10.2 使用方式

由于description中写入了Use PROACTIVELY，主代理会在遇到数据分析类需求时自动委派该子代理。也可以显式调用：

> Use the contenteditable="false">【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考