# sds-claude-agents **Repository Path**: wds-sync/sds-claude-agents ## Basic Information - **Project Name**: sds-claude-agents - **Description**: Claude Code 数据需求开发Agent， 帮助用户完成从数据需求分析->了解数据->处理数据->分析数据的全流程数据开发和分析。 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2025-12-17 - **Last Updated**: 2026-06-17 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # SDS Claude Agents - 数据需求开发工作流 > **知数(SDS) Data Agent** - 基于 Claude Code 的智能数据需求开发工作流系统 [![Version](https://img.shields.io/badge/version-2.0-blue.svg)](https://github.com) [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) [![Claude](https://img.shields.io/badge/Claude-Code-purple.svg)](https://claude.ai) --- ## 📖 项目简介 **SDS Claude Agents** 是一个基于 Claude Code 构建的智能化数据需求开发工作流系统,旨在帮助数据分析师、数据开发人员和业务人员快速完成从**需求分析**到**数据交付**的完整流程。 ### 核心特性 ✨ **智能需求识别** - 自动识别4种数据需求类型(了解数据、生成SQL、处理数据、分析数据) 🔍 **上下文感知** - 自动分析项目已有代码、文档、表结构,提供精准的数据支持 🤖 **多轮澄清对话** - 基于三种方法论深度挖掘需求,确保需求清晰无歧义 📊 **智能需求拆分** - 按4种策略自动拆分复杂需求,支持最多5轮迭代分析 ⚙️ **自动化流程编排** - 根据需求类型自动调用专业Agents完成子任务 📝 **规范化代码生成** - 生成的SQL/PySpark代码严格遵循项目规范 📈 **可视化报告输出** - 直击用户痛点,输出关键要素,支持图表展示 --- ## 🏗️ 项目结构 ``` sds-claude-agents/ ├── .claude/ # Claude Code 配置目录 │ ├── commands/ # 斜杠命令定义 │ │ └── data-task.md # /data-task 命令定义 │ │ │ ├── skills/ # 技能定义(Skill) │ │ ├── data-requirement-dev-workflow/ │ │ │ └── SKILL.md # 数据需求开发工作流主流程 │ │ ├── requirement-analyzer/ │ │ │ └── SKILL.md # 需求分析器(废弃) │ │ └── skill-rules.json # 技能自动激活规则 │ │ │ ├── agents/ # 专业Agent定义 │ │ ├── data_requirement_type_classifier.md # 需求类型分类器 │ │ ├── project-context-analyzer.md # 项目上下文分析器 │ │ ├── know_data_tool.md # 数据查找工具 │ │ ├── req-clarification-orchestrator.md # 需求澄清编排器 │ │ ├── req-extractor.md # 需求拆分专家 │ │ ├── know-data-agent.md # 了解数据Agent │ │ ├── generate-sql-agent.md # SQL生成Agent │ │ ├── deal-data-agent.md # 数据处理Agent │ │ └── analyze-data-agent.md # 数据分析Agent │ │ │ └── templates/ # 模板文件 │ ├── req-structuring-know-data.md # 了解数据需求模板 │ ├── req-structuring-generate-sql.md # 生成SQL需求模板 │ ├── req-structuring-deal-data.md # 处理数据需求模板 │ ├── req-structuring-analyze-data.md # 分析数据需求模板 │ ├── coding-standards.md # 编码规范(HiveQL/SparkSQL/StarRocks/MySQL) │ └── code-review-checklist.md # 代码审查清单 │ ├── dev/ # 开发工作目录 │ └── active/ # 活跃任务目录 │ └── {task-name}/ # 单个任务目录 │ ├── context.md # 任务上下文 │ ├── clarification_result.json # 澄清结果 │ ├── data_requirement.md # 需求文档 │ ├── final_report.md # 最终报告 │ └── {子需求名}/ # 子需求执行目录 │ ├── result.md # 子需求结果 │ ├── result_data.csv # 数据结果 │ ├── query.sql # SQL代码 │ └── implementation-log.md # 实施日志 │ └── README.md # 项目说明文档(本文件) ``` --- ## 🚀 快速开始 ### 前置要求 - 已安装 [Claude Code CLI](https://github.com/anthropics/claude-code) - Claude API Key (需要 Claude 4.5 Sonnet 或更高版本) - 项目已初始化为 Claude Code 项目 ### 使用方法 #### 1️⃣ 基础用法 - 启动数据开发任务 ```bash /data-task 你的数据需求描述 ``` **示例：** ```bash # 了解数据类型 /data-task 贷款金额相关的指标有哪些？ # 生成SQL类型 /data-task 我想知道最近一个月微信渠道的贷款金额，帮我生成SQL # 处理数据类型 /data-task 查询最近一个月的贷款金额 # 分析数据类型 /data-task 分析最近一个月微信渠道的贷款金额趋势 ``` #### 2️⃣ 多轮对话 当系统向你提出澄清问题时,直接回复即可: ```bash # 系统提问: "请问你需要按天还是按月统计贷款金额？" # 你的回答: 按天统计 ``` #### 3️⃣ 查看任务进度 ```bash # 查看当前任务的上下文 cat {task-working-dir}/context.md # 查看最终报告 cat {task-working-dir}/final_report.md ``` --- ## 🎯 支持的需求类型 ### 1. 了解数据 (KNOW_DATA) **适用场景**: 查询数据表元数据、指标业务口径、计算逻辑等 **关键词**: 业务口径、元数据信息、指标定义、计算逻辑 **示例**: - "贷款金额相关的指标有哪些？" - "昨日登录用户数的计算逻辑是什么？" - "核销前是什么意思？" **输出**: 结构化的元数据信息表格,包含中英文名称、业务口径、计算逻辑、数据来源等 --- ### 2. 生成SQL (GENERATE_SQL) **适用场景**: 只需生成SQL代码,不需要执行查询 **关键词**: 生成SQL、输出SQL、生成查询语句 **示例**: - "我想知道最近一个月微信渠道的贷款金额,帮我生成SQL" - "生成查询昨日新增用户数的SQL" **输出**: - 完整的可执行SQL代码 - 代码说明(功能、数据源、输出字段、筛选条件) - 使用方法说明 --- ### 3. 处理数据 (DEAL_DATA) **适用场景**: 查询数据并展示结果 **关键词**: 查询、查看、展示、计算数值 **示例**: - "查询最近一个月的贷款金额" - "昨日登录用户数是多少" - "各渠道的贷款金额占比" **输出**: - 核心数据表格(单值/趋势/对比) - 关键发现 - 原始数据CSV文件 - SQL代码 --- ### 4. 分析数据 (ANALYZE_DATA) **适用场景**: 分析趋势、分布,生成图表,深度洞察 **关键词**: 分析、趋势、分布、图表(饼图、柱状图、折线图) **示例**: - "分析最近一个月微信渠道的贷款金额趋势" - "各渠道的贷款金额占比,以饼图展示" - "分析用户留存率的变化情况" **输出**: - 分析结论 - 数据可视化图表(Mermaid图表) - 核心发现(趋势特征、分布特征、异常点) - 详细数据表格 - 分析过程说明(如果是迭代分析) --- ## ⚙️ 完整工作流程 系统会自动执行以下8个阶段,全流程自动化,无需人工干预(除非需求不清晰): ### Phase 1: 初始化和上下文分析 ⭐ **目标**: 理解项目现状,为后续分析提供上下文 **执行内容**: - 检查并生成项目上下文文件 `~/.claude/projects/[project-name]/project-context.json` - 分析已有代码(HQL/SQL/StarRocks/PySpark等) - 分析已有文档(MD/TXT/CSV/XLSX等) - 分析代码规范(建表规范、自定义变量、UDF函数等) - 判断项目类型(新项目 vs 现有项目) **输出**: 项目类型、建表文件清单、业务知识清单、SQL代码清单、代码规范 --- ### Phase 2: 意图识别 🎯 **目标**: 准确识别需求类型,并扩写需求描述 **执行内容**: - 提取用户需求描述 - 调用 `data_requirement_type_classifier` Agent 进行类型识别 - 结合对话上下文适当扩写或补充需求描述 **输出**: - 原始需求 - 改扩写后的需求描述 - 需求类型 (KNOW_DATA/DEAL_DATA/GENERATE_SQL/ANALYZE_DATA) - 置信度 (0-100%) - 优先级 (P0/P1/P2) - 判断依据 **特殊处理**: 如果置信度 < 65%,会提示用户明确指定需求类型 --- ### Phase 3: 创建任务工作区 📁 **目标**: 创建任务目录和context.md文件,为后续阶段提供上下文跟踪 **执行内容**: - 生成任务名称: `【需求类型】+简短描述` - 创建任务目录: `{task-working-dir}/` - 创建任务上下文文件: `{task-working-dir}/context.md` **输出**: 任务目录和context.md文件 --- ### Phase 4: 阶段1 - 了解数据 ⚙️ **目标**: 查找关联的业务知识、黑话、代码和表结构信息 **执行内容**: - 从需求描述中提取关键业务术语、指标名称、表名等 - 调用 `know_data_tool` Agent 查找关联信息: - 从项目上下文中查找业务知识、黑话、代码、表结构 - 从MCP Tools中查询元数据、指标信息(如果可用) - 持续查找直到信息完善(最多3轮) **输出**: - 需求清晰置信度 (0-100%) - 业务知识清单(来源: MCP/Project) - 黑话清单(来源: MCP/Project) - 表结构信息清单(建表语句,来源: MCP/Project) - 参考代码清单(SQL代码,来源: MCP/Project) - 完善度判断 **⚠️ 关键**: 此阶段是**强制执行**的,不允许跳过,避免后续生成的SQL使用虚构的表名/字段名 --- ### Phase 5: 阶段2 - 需求澄清 💬 **目标**: 执行多轮澄清对话,深入挖掘用户真实需求 **前置条件**: 如果需求清晰置信度 >= 85%,跳过此阶段 **执行内容** (仅当置信度 < 85%): - 调用 `req-clarification-orchestrator` Agent 执行多轮澄清对话 - 基于三种方法论深度挖掘需求: - **第一性原理**: 追问"为什么" - **目标拆解法**: 分解最终目标 - **苏格拉底式提问**: 循序渐进引导思考 - 生成澄清结果: `{task-working-dir}/clarification_result.json` **输出**: - 澄清轮次 - 澄清点个数 - 需求清晰置信度 (必须 >= 85%) - 澄清简述 **特殊处理**: 如果澄清后置信度仍 < 85%,终止流程并建议用户重新明确需求 --- ### Phase 6: 阶段3 - 需求拆分 📝 **目标**: 判断需求复杂度,拆解为一个或多个子需求 **执行内容**: - 调用 `req-extractor` Agent 执行需求拆分 - 按4种策略拆分: - **策略A**: 按需求类型拆分(非数据任务拆分) - **策略B**: 按指标拆分(DEAL_DATA/GENERATE_SQL/KNOW_DATA) - **策略C**: 按SQL复杂度拆分(单个SQL不超过3层嵌套) - **策略D**: 按分析思路拆分(ANALYZE_DATA迭代分析,最多5轮) - 生成需求文档: `{task-working-dir}/data_requirement.md` **输出**: - 子需求总数 - 数据类型子需求个数 - 非数据类型子需求个数 - 是否拆分 - 子需求列表(包含: 需求名称、需求类型、状态、需求描述、父依赖、推荐Agent) - 执行树(如果有依赖关系) --- ### Phase 7: 阶段4 - 流程编排 📐 **目标**: 根据子需求类型执行对应的处理流程 **执行内容**: #### 7.1 数据类型子需求处理 根据需求类型调用对应的专业Agent: | 需求类型 | 对应Agent | 输出 | |---------|----------|------| | KNOW_DATA | `know-data-agent.md` | 元数据信息 | | GENERATE_SQL | `generate-sql-agent.md` | SQL代码 | | DEAL_DATA | `deal-data-agent.md` | 数据结果 + SQL | | ANALYZE_DATA | `analyze-data-agent.md` | 分析报告 + 图表 + 数据 | **每个Agent的输出**: - 文本结果: `{task-working-dir}/{子需求名}/result.md` - 数据结果: `{task-working-dir}/{子需求名}/result_data.csv` - 图片结果: `{task-working-dir}/{子需求名}/result_[图片名称].png` - SQL代码: `{task-working-dir}/{子需求名}/query.sql` - 实施日志: `{task-working-dir}/{子需求名}/implementation-log.md` (复杂流程) #### 7.2 非数据类型子需求处理 使用Claude现有Tools直接执行: - **提取发现**: 从前置分析结果中提取关键发现(异常点、趋势特征、需要深入分析的问题) - **分析原因**: 基于发现推理可能原因,提出验证假设 - **预测趋势**: 基于历史数据趋势进行合理外推 - **验证假设**: 基于新数据验证之前的假设 - **得出结论**: 综合所有分析形成最终结论 **输出**: 按子需求依赖关系顺序执行,所有子需求的执行结果 --- ### Phase 8: 阶段5 - 报告生成 🎉 **目标**: 根据需求类型生成用户友好的最终报告 **执行内容**: - 读取所有子需求的执行结果 - 根据需求类型选择对应的报告模板: - **KNOW_DATA模板**: 元数据信息表格 - **GENERATE_SQL模板**: SQL代码 + 使用说明 - **DEAL_DATA模板**: 核心数据表格 + 关键发现 - **ANALYZE_DATA模板**: 分析结论 + 可视化图表 + 核心发现 - 生成最终报告: `{task-working-dir}/final_report.md` **输出**: - 用户友好的最终报告 - 直击用户痛点 - 输出关键要素(数据/代码/分析/可视化) - 不展示中间过程(澄清、拆分过程) - 简洁专业,结构清晰 **报告原则**: - 用数据说话,减少文字描述 - 核心内容置顶(用户最关心的) - 详细数据次之 - 技术信息最后(SQL代码、文件路径) --- ## 🛠️ 代码规范 项目遵循严格的SQL代码规范,支持多种SQL方言: ### 支持的SQL方言 - **HiveQL** - Hadoop数据仓库查询语言 - **SparkSQL** - Spark分布式计算引擎 - **StarRocks** - 实时OLAP分析引擎 - **MySQL** - 关系型数据库 ### 编码规范要点 ✅ **格式规范**: 使用2-4空格缩进,每行不超过80-100字符 ✅ **命名规范**: 蛇形命名法(snake_case),如 `user_id`, `loan_amount` ✅ **注释规范**: 所有表/字段必须包含COMMENT,复杂逻辑添加行内注释 ✅ **性能优化**: 合理使用分区、索引、物化视图 ✅ **安全规范**: 禁止生成DROP/DELETE/GRANT等高危语句 详细规范请查看: [`.claude/templates/coding-standards.md`](.claude/templates/coding-standards.md) --- ## 🎓 核心概念 ### Skill vs Agent 的区别 | 类型 | 定义 | 触发方式 | 复杂度 | 示例 | |-----|------|---------|--------|------| | **Skill** | 完整的工作流程 | 斜杠命令 或 自动激活 | 高(多阶段) | `data-requirement-dev-workflow` | | **Agent** | 单一职责的专业工具 | 由Skill调用 | 中(单阶段) | `generate-sql-agent` | ### 8阶段工作流 ``` Phase 1: 初始化和上下文分析 (自动) ↓ Phase 2: 意图识别 (自动) ↓ Phase 3: 创建任务工作区 (自动) ↓ Phase 4: 了解数据 (自动, 强制执行) ↓ Phase 5: 需求澄清 (条件: 置信度<85%, 可能需要用户交互) ↓ Phase 6: 需求拆分 (自动) ↓ Phase 7: 流程编排 (自动, 调用专业Agents) ↓ Phase 8: 报告生成 (自动) ``` ### 4种拆分策略 - **策略A** (按需求类型): 区分数据任务 vs 非数据任务 - **策略B** (按指标): 多个指标拆分为独立子需求 - **策略C** (按SQL复杂度): 单个SQL不超过3层嵌套 - **策略D** (按分析思路): ANALYZE_DATA支持最多5轮迭代分析 --- ## 📝 配置文件说明 ### `.claude/commands/data-task.md` 定义了 `/data-task` 斜杠命令,是系统的入口命令。 **职责**: - 接收用户输入 - 立即调用 `data-requirement-dev-workflow` Skill - 传递用户输入给Skill **⚠️ 关键约束**: 该命令**禁止直接执行任务**,必须调用Skill! --- ### `.claude/skills/data-requirement-dev-workflow/SKILL.md` 定义了完整的8阶段数据需求开发工作流。 **版本**: v2.0 **更新日期**: 2025-12-17 **关键特性**: - ✅ 自动创建和更新TODOs跟踪进度 - ✅ 自动创建和更新context.md文件 - ✅ 强制执行所有8个阶段(除非前置条件不满足) - ✅ 禁止中途退出对话(除非置信度<65%) - ✅ 强制执行Phase 4了解数据(避免瞎编SQL) --- ### `.claude/agents/*.md` 定义了各种专业Agent,负责执行特定任务。 **Agent清单**: | Agent | 职责 | 调用者 | |-------|------|--------| | `data_requirement_type_classifier` | 需求类型分类 | Phase 2 | | `project-context-analyzer` | 项目上下文分析 | Phase 1 | | `know_data_tool` | 数据查找 | Phase 4 | | `req-clarification-orchestrator` | 需求澄清编排 | Phase 5 | | `req-extractor` | 需求拆分 | Phase 6 | | `know-data-agent` | 了解数据 | Phase 7 | | `generate-sql-agent` | 生成SQL | Phase 7 | | `deal-data-agent` | 处理数据 | Phase 7 | | `analyze-data-agent` | 分析数据 | Phase 7 | --- ### `.claude/templates/*.md` 定义了各种模板文件。 **模板清单**: - `req-structuring-*.md`: 4种需求类型的结构化模板 - `coding-standards.md`: SQL编码规范 - `code-review-checklist.md`: 代码审查清单 --- ### `.claude/skills/skill-rules.json` 定义了Skill的自动激活规则。 **激活条件**: - 关键词匹配: 查看数据、查询数据、生成SQL、分析数据等 - 意图模式匹配: 正则表达式匹配 - 命令触发: `/data-task` --- ## 🔒 设计原则 ### 1. MVP优先原则 系统遵循**最小可用版本(MVP)**原则: - 先实现核心功能,不过度设计 - 只实现用户明确要求的功能 - 延迟优化,避免过早抽象 ### 2. 严格约束策略 - **禁止自由发挥**: 严格按需求范围执行 - **禁止过度设计**: 不引入不必要的复杂度 - **禁止改变架构**: 锁定技术栈和模式 - **禁止影响兼容性**: 保持向后兼容 ### 3. 架构一致性原则 **存量系统改造铁律**: - 技术栈锁定: 不升级主版本,不更换框架 - 架构模式锁定: 保持现有分层结构 - 变更审批机制: 高危操作需人工审批 ### 4. 代码复用原则 - 优先使用项目已有代码 - 复用现有工具类和方法 - 避免重复造轮子 --- ## ⚠️ 重要约束 ### 强制执行的约束 #### ✅ 必须遵守 (MUST) 1. **Phase 4了解数据阶段必须执行** - 避免生成虚构的表名/字段名 2. **每个Phase结束必须更新TODOs** - 使用TodoWrite工具 3. **每个Phase结束必须更新context.md** - 使用Edit工具 4. **必须按顺序执行8个Phase** - 不允许跳过或颠倒顺序 5. **所有生成的SQL必须符合编码规范** - 参考 coding-standards.md #### ❌ 禁止行为 (MUST NOT) 1. **禁止中途退出对话** - 除非置信度<65%需要用户澄清 2. **禁止跳过Phase 4了解数据** - 这是关键阶段 3. **禁止生成DROP/DELETE/GRANT等高危语句** - 安全第一 4. **禁止引入新的框架或依赖** - 保持技术栈一致 5. **禁止修改现有代码的行为** - 保持向后兼容 --- ## 🐛 常见问题 ### Q1: 如何暂停和恢复任务? **暂停**: 输入 "暂停" 或 "停止" 系统会保存当前进度到 `{task-working-dir}/context.md` **恢复**: 重新执行 `/data-task [task-name]`,系统会自动检测未完成的任务并继续。 --- ### Q2: 如何查看任务执行进度? **方法1**: 查看TODOs列表 系统会自动创建8个Phase的TODOs,实时更新状态。 **方法2**: 查看context.md文件 ```bash cat {task-working-dir}/context.md ``` 文件中包含: - 当前阶段 - 下个阶段 - 阶段完成情况清单 --- ### Q3: 如果生成的SQL有错误怎么办? **步骤1**: 查看实施日志 ```bash cat {task-working-dir}/{子需求名}/implementation-log.md ``` **步骤2**: 检查代码审查清单 参考 `.claude/templates/code-review-checklist.md` **步骤3**: 手动修复或重新执行 - 手动修复: 直接编辑 `query.sql` 文件 - 重新执行: 删除任务目录,重新执行 `/data-task` --- ### Q4: 如何自定义报告模板? 在需求描述或澄清过程中明确指定报告格式,系统会优先使用用户指定的模板。 **示例**: ```bash /data-task 分析贷款金额趋势,报告格式要求: 1. 先展示图表 2. 再展示数据表格 3. 最后是关键发现 ``` --- ### Q5: 系统支持哪些MCP Tools? 系统会自动扫描所有可用的MCP Tools,并在Phase 4了解数据阶段调用相关接口。 **常见MCP Tools**: - 元数据查询工具 - 指标查询工具 - 表结构查询工具 - 业务知识查询工具 如果没有可用的MCP Tools,系统会从项目已有代码和文档中查找信息。 --- ## 📄 许可证 MIT License --- ## 🤝 贡献指南 欢迎提交Issue和Pull Request! **贡献流程**: 1. Fork本仓库 2. 创建特性分支 (`git checkout -b feature/AmazingFeature`) 3. 提交更改 (`git commit -m 'Add some AmazingFeature'`) 4. 推送到分支 (`git push origin feature/AmazingFeature`) 5. 创建Pull Request --- ## 📮 联系方式 - 项目主页: [GitHub Repository](https://github.com) - 问题反馈: [Issues](https://github.com/issues) - 邮箱: support@example.com --- ## 🙏 致谢 感谢以下项目的启发和支持: - [Claude Code](https://github.com/anthropics/claude-code) - Anthropic官方CLI工具 - [Claude API](https://www.anthropic.com/api) - Claude AI API - 所有使用本项目的开发者和贡献者 --- **最后更新**: 2025-12-17 **版本**: v2.0 **作者**: 知数(SDS) DataAgent Team