构建知识闭环:用CodeBuddy打造自我进化的数据分析体系
难以查找海量库表、需求紧急复杂、重复性工作多、结果校验困难、追溯记录困难……数据分析时要如何破除这些痛点?QQ浏览器的信息流推荐架构团队基于CodeBuddy AI给出了迅速有效的答案。
1.引言
我们团队的部分职责是承担推荐数据分析的工作。在长期数据分析中,我们总结出以下业务痛点:
● 涉及到大量库表和口径,查找起来有困难;
● 需求紧急而复杂,仅有一人负责大部分工作,压力较大;
● 不同需求往往用到类似的口径,重复度较高;
● 数据分析对结果准确性要求极高,校验压力大;
● 代码和分析结果散落在各处,容易丢失,难以回溯。
我们的解决方案: 在有限的人力下快速试错、改进,构建了一个知识闭环体系。这个体系通过"让知识可沉淀 → 让知识可传递 → 让知识可生成 → 让知识可信赖 → 让知识可闭环"五个环节,形成了一个自我进化的良性循环。在此流程中,我们利用CodeBuddy AI来设计开发规范,还使用它的自定义Agent功能自动生成SQL代码,将编码过程从小时级下降到分钟级。
第一环:让知识可沉淀。 我们使用Git仓库管理所有数据分析代码和口径定义,使所有历史任务沉淀为可复用的知识库。
第二环:让知识可传递。 为了降低新负责人的学习成本,我们将代码目录结构化管理,并设定好代码规范。这样,原本只有一人负责的工作能方便地扩展到组内,让更多同学共同开发和维护。
第三环:让知识可生成。 为了降低数据分析过程中的重复工作量,我们利用CodeBuddy快速设计出一个数据分析Agent,它能够自动读取仓库内的历史代码,然后结合当前需求写出高质量的分析SQL。面对简单和中等复杂的情境,生成代码的准确率能达到80%以上;而对于复杂情境,在1~2次运行和反馈后,代码也普遍能达到满意效果。
第四环:让知识可信赖。 虽然代码编写重要,但后续对运行结果准确性的验证更重要且更有挑战。这要求我们在对业务指标具备认知的基础上,再运用AI进行逻辑复查。
第五环:让知识可闭环。 由于数据分析需求杂乱,此前的代码和分析结果往往散落在各处,导致需要修改周期重新运行或回看结果时难以查找。为此,在利用Git的版本控制能力的基础上,我们还设定了文件命名规范,并要求在代码文件中记录分析结果的链接,以保障所有结果可溯。更重要的是,经过验证的新口径、新代码会重新进入Git仓库,成为知识库的一部分,供后续任务复用。
总结来说,重构后的数据分析流程有如下表格所示的优势,是一件值得参考的AI实践案例。
知识闭环的价值: 这套体系最大的价值在于形成了正向循环。每次数据分析任务都在为知识库添砖加瓦,知识库越丰富,AI生成的代码就越准确,团队效率就越高。
在完成流程重构后,我们一方面反思教训、总结经验,认识到AI在代码生成上存在能力边界;另一方面,也展望通过AI自动化生成文档的优势,来攻克知识传递瓶颈,提升团队效率。
2.重构方法论:五环闭环体系
在解决这些痛点时,我们总结出一套可复用的方法论。这套方法论的核心思路是:构建一个知识自我进化的闭环体系。
这套体系由五个相互关联的环节组成,每个环节都承担着特定的职责。第一环是让知识可沉淀,通过Git管理代码并建立结构化目录来构建知识库,这样所有历史任务都能成为可复用的资产。第二环是让知识可传递,我们制定了统一的代码规范和文件注释标准来实现规范化协作,使得多人协作成为可能而不再依赖单个人。第三环是让知识可生成,利用Agent和Prompt工程实现AI自动化,提升编码效率。第四环是让知识可信赖,通过建立多层验证体系来保障质量。第五环是让知识可闭环,依靠版本控制和命名规范实现闭环增值,让经过验证的新知识重新沉淀回知识库,从而推动知识持续增长并形成正向循环。
通过这次实践,我们发现有五点特别重要:
基础工作不能跳过:没有Git知识库,AI就没有学习材料;没有代码规范,AI生成的代码质量就没保障 人的流程优先:先把人的协作流程搞顺畅,再用AI来加速,而不是一上来就用AI 验证是核心:AI生成代码只是第一步,验证准确性才是关键价值 闭环是灵魂:只有经过验证的知识重新沉淀,才能形成正向循环 边做边改:每个环节都要快速试一试,根据实际效果来调整方向
2.1.一个真实案例
接下来,我们先通过一个真实案例直观感受效果,然后再详细讲解每一步的实践过程。
需求: 筛选2025年9月21-27日期间关注过特定puin的一线城市用户,查询其在浮层场景的内容消费历史。
这个需求在重构前后的处理方式有着天壤之别。在重构前,整个流程需要花费30分钟翻阅各种文档来找到准确的口径定义,然后花费数小时手工编写复杂的多表关联逻辑,接着完全依赖人工检查来验证结果准确性,最后还要花10分钟手动记录各种信息到不同的文档和文件夹中,整个过程耗时且容易出错。
而在重构后,只需要2分钟就能让CodeBuddy自动检索Git仓库中的口径定义,然后10分钟就能生成符合团队规范的SQL代码,虽然验证环节仍然需要人工业务判断作为核心,但现在有了CodeBuddy辅助进行逻辑复查,最后借助Git版本控制只需1分钟就能完成归档工作,整个流程变得高效且规范。
下面,让我们详细讲解这套方案背后的工程实践以及细节思考。
3.构建知识库- 让知识可沉淀
通过分析我们发现,效率低下的根源主要体现在三个方面:首先是学习成本高,因为涉及大量的表、字段和口径定义,每次都需要花费大量时间去查找和理解;其次是单人负担重,由于只有一个人掌握数据分析技能,所有需求都压在一个人身上,工作压力巨大;最后是重复工作多,相似的需求需要反复编写类似的代码,大量时间浪费在重复劳动上。
3.1.规范管理代码
基于前面的分析,我们选择Git来管理所有数据分析代码。相比传统的在线文档或数据分析平台,Git有三个核心优势:
代码即知识:SQL代码本身就是最精确的知识表达,一行代码胜过千言万语 版本可追溯:天然支持版本控制,每次修改都有记录,为后续的知识闭环打下基础 大模型可解析:结构化的代码比自然语言更适合大模型理解和生成,维护成本更低
核心目标: 让每次数据分析任务都成为可复用的知识资产,而不是一次性的工作。
3.2.仓库结构设计
为了让Git仓库发挥好知识库的作用,我们需要对目录进行结构化管理。
在设计目录结构时,我们首先思考了一个问题:数据分析任务中哪些内容是可以复用的?经过分析发现,虽然每次分析需求都不同,但背后用到的数据口径往往是相似的,比如"一线城市用户"的定义、"浮层场景"的判断逻辑、"内容消费"的统计口径等,这些口径会在不同的分析任务中反复使用。基于这个洞察,我们确定了核心设计思路:将可复用的口径定义与具体的分析代码分离管理,让口径成为独立的知识资产。
分离"分析代码"和"口径定义":
● 分析代码:存所有历史任务的完整代码(如实验分析、异常兜底策略分析)
● 口径定义:保存这些任务用到的数据口径(如实验桶号、用户消费数据)
为什么要分离?
1.口径可以跨任务复用,避免重复定义
2.AI可以先检索口径,再生成分析代码
3.新人可以快速了解有哪些可用口径
目录结构示例:
数据分析代码仓库/
├── 分析代码/
│ ├── 实验/
│ ├── 用户/
│ ├── 异常/
│ └── 内容池/
└── 口径定义/
├── 实验/
├── 用户/
├── 消费/
├── 场景/
└── 内容/
实践经验:
● 目录结构可以用大模型辅助设计,再手动调整
● 根据业务特点调整
● 遇到新口径时,及时更新到口径定义目录
● 随着需求迭代,口径库会越来越完善,数据分析效率越来越高
通过Git仓库和结构化目录,我们成功建立了知识沉淀的基础设施。但仅有知识库还不够,我们需要让这些知识能够在团队中有效传递,让更多人能够理解和使用这些沉淀下来的代码。
4.制定规范 - 让知识可传递
有了Git仓库作为知识库,下一步是让这些知识能够在团队中有效传递。我们发现,知识传递的核心障碍不是找不到代码,而是看不懂代码和不知道怎么用。要让知识真正在团队中流动起来,需要建立一套完整的规范体系和协作机制。在规范生成过程中,CodeBuddy生成了最重要的初版内容,后续再由我们手动调整,使格式更加精炼易读。
4.1.为什么需要规范
在引入规范之前,虽然我们已经有了Git仓库,但团队协作仍然困难重重。每个人的代码风格不同,新人看历史代码如同天书,相似的逻辑在不同文件中写法各异,导致学习成本居高不下。更严重的是,当我们尝试让AI基于这些代码生成新代码时,由于缺乏统一规范,AI生成的代码质量参差不齐,有时甚至无法运行。这让我们意识到,必须建立统一的代码规范,让知识以标准化的形式沉淀和传递。
4.2.使用CTE
我们团队统一要求使用CTE(公用表表达式)编写数据分析代码,避免多层嵌套的SELECT语句。
我们之所以强制要求使用CTE,是因为在实践中发现AI生成嵌套子查询时经常出现括号层级错误,导致SQL无法正常执行。统一使用CTE格式后,AI生成的SQL语法错误明显减少,代码的可读性和可维护性也得到了显著提升。不过需要注意的是,每个CTE都应该有明确的业务含义,避免为了使用CTE而过度拆分逻辑。
在实际应用中,我们建议在Prompt中明确要求使用CTE,并提供具体的代码示例让AI学习正确的格式。对于AI生成场景来说,CTE比嵌套子查询更可控、更易维护,这不仅降低了语法错误的概率,也让后续的代码审查和优化工作变得更加轻松。
WITH
-- [CTE功能说明]
cte_name1 AS (
SELECT ...
FROM ...
WHERE ...
),
-- [CTE功能说明]
cte_name2 AS (
SELECT ...
FROM ...
WHERE ...
)
-- 结果输出
SELECT `[中文字段1]`, `[中文字段2]`
FROM ...
WHERE ...
4.3.文件注释规范:让代码自解释
数据分析代码往往行数较多(200行以上),且由于SQL的语法特性,其执行逻辑和自然语言逻辑差距较大。为了在不深入代码细节的前提下也能理解代码逻辑,我们决定在所有分析代码和口径定义文件的开头都加上规范的注释。
分析代码的注释格式如下所示,包含了任务名、用户范围、时间范围、场景限制、数据源、分析任务、产出结构和结果链接。
/*
* [分析任务名称]
*
* 【用户范围】
* - [用户圈定条件]
*
* 【时间范围】
* - [具体日期或时间周期]
*
* 【场景限制】
* - [场景说明]
*
* 【数据源】
* - [表名]([表定义])
* - [表名]([表定义])
*
* 【分析任务】
* - [任务1]
* - [任务2]
*
* 【产出结构】
* - [字段1]:[定义]([数据类型])
* - [字段2]:[定义]([数据类型])
*
* 【结果链接】
* - 待补充
*/
口径定义的注释格式如下所示,包含了口径名、功能、使用方法、筛选条件和输出字段。
/*
* [口径名称]
*
* 【功能】
* - [一句话简要描述功能]
*
* 【使用方法】
* - [需要关联什么字段来引用此CTE]
*
* 【筛选条件】
* - ${参数1}:[定义],格式如 [格式说明]([数据类型])
* - ${参数2}:[定义],格式如 [格式说明]([数据类型])
*
* 【输出字段】
* - [字段1]:[定义]([数据类型])
* - [字段2]:[定义]([数据类型])
*/
4.4.协作流程规范
为了防止不规范的代码污染知识库,我们建立了两项核心机制:主分支保护,所有修改必须通过feature分支提交;强制代码审查,至少一人review通过后才能合并到主分支,确保每一次提交都符合团队规范。
通过这一步,我们让知识真正在团队中流动起来,从单人负责变成多人协作,从个人经验变成团队资产。现在我们有多位同学共同数据分析,并基于Git进行版本管理,当某位同学处理新分析需求或新口径定义时,可以将代码便捷地推送至主分支,便于其他同学在后续数据分析任务中复用。接下来,我们需要让AI基于这些沉淀的知识自动生成新代码,进一步提升效率。
5.设计Agent - 让知识可生成
在完成知识沉淀和知识传递后,我们终于可以让AI基于这些知识自动生成新代码,从而大幅降低重复工作量。我们利用CodeBuddy快速设计出一个数据分析Agent,它能够自动读取仓库内的历史代码,然后结合当前需求写出高质量的分析SQL。
核心目标: 让AI基于已沉淀的知识自动生成新代码,实现效率的指数级提升。
重要提示: 这一步只是知识闭环的开始,AI生成的代码需要经过验证和沉淀,才能成为新的知识资产。
5.1.自定义Agent
在技术选型的过程中,我们考虑过自行部署Text2SQL框架(如vanna)和司内的一些AI数据分析平台(如dola),但这些方案或者试错成本较高,或者自身不够成熟。基于敏捷开发原则,我们优先选择试错成本最低的方案来快速验证想法,最终决定使用CodeBuddy来创建一个能理解代码仓库并生成SQL代码的Agent。
这个决策基于四个关键考虑:首先,CodeBuddy与我们日常使用的JetBrains IDE深度集成,作为后端开发团队,我们本来就在IDE中编写和管理代码,使用CodeBuddy可以在熟悉的环境中完成从需求分析到代码生成的全流程,无需切换工具,学习成本几乎为零;其次,我们已经有Git仓库作为知识库,CodeBuddy可以直接读取和理解这些代码,天然契合我们的工作方式;再次,小范围试用后效果超出预期,面对简单和中等复杂的数据分析需求,生成代码的准确率能达到80%以上,证明了这个方案的可行性;最后,即使这个方案最终不够理想,我们在Git仓库中沉淀下来的代码规范、口径定义和历史分析代码,也可以无缝迁移到其他Text2SQL框架或数据分析平台,这些知识资产不会因为工具切换而浪费,这让我们可以放心地快速试错。
参考codebuddy文档,创建自定义Agent的方式十分简单,几步即可完成。我们将这个数据分析Agent命名为"SQL大王",场景提示词填入下一节介绍的prompt内容,工具只需要选择"搜索文件"、"读取文件"、"搜索代码"和"编辑文件"即可,如下图所示。
提问时,建议选择编程能力最强的Claude-4.5-Sonnet模型。
5.2.Prompt设计
Prompt设定的好坏直接影响模型表现,我们参考同事的km文章,设计出了结构清晰的prompt。它由五个部分组成:角色与任务、核心原则、执行步骤、输出格式和生成案例。
角色与任务
角色与任务是最高指令,用简短的话唤醒模型在SQL生成方面的能力。
具体prompt:
# 角色与任务
你是专业的数据分析师,根据用户需求生成符合规范的SuperSQL代码或口径定义。
核心原则
核心原则是模型执行任务时必须遵守的最高准则,权重等级仅次于角色与任务。设定核心原则的目的是直接解决实践中的高频问题,例如字段名混淆、表名错误、SQL语法错误等。
具体prompt:
# 核心原则
### 字段使用规范
* 使用数据字段时,必须严格依据其定义口径,仅使用已明确声明的字段,禁止使用任何未定义的字段;同时,不同表对相同业务含义可能使用不同的字段名,使用前必须确认该字段在当前表中的准确命名。
* 示例1 :消费流水表的口径中未定义作者id字段`puin`,需通过已定义的`content_id`关联内容维表来获取。
* 示例2:对于“内容ID”这一业务含义,消费流水表中对应的字段名为`content_id`,而内容维表中对应的字段名则为`cid`。
### 最大引擎兼容性
* 严格遵守SuperSQL标准语法,禁止使用引擎专有语法特性,确保代码可在Spark、Presto、Starrocks等多引擎执行。
执行步骤
执行步骤用于约束模型按照固定流程思考。在"分析任务 -> 读取口径定义 -> 生成分析代码"这样逻辑性强的场景下,规定固定步骤能提升代码准确率和规范性。关键设计包括:先理解需求再生成代码、强制检索已有口径避免重复、每步都有明确输出便于人工检查。
具体prompt:
# 执行步骤
### 步骤1:任务类型识别
* 口径定义任务:定义指标/用户群体/内容范围等的标准SQL → 执行步骤2.1
* 数据分析任务:生成完整数据分析查询 → 执行步骤2.2
### 步骤2.1:口径定义生成
* 提取摘要:口径名称、功能、筛选条件、输出字段
* 确定分类:搜…