接手一个陌生代码库
Apache Superset 是一个成熟的开源 BI 项目。在 ADE 生成的工程 Wiki 中，这个项目被直接识别为《Apache Superset 工程 Wiki》（见 image3），开篇也将其定位为面向企业级 BI 场景的 Web 应用。它的代码仓库包含前端（React/TypeScript）、后端（Python/Flask）、数据库引擎适配层、SQL 解析器、可视化组件等数十个子模块，文件数以千计，整体代码量在百万行级别。
接手这类规模的存量项目，研发团队最常见的目标其实不是从零重写，而是在已有代码上做二次开发——加一个功能、改一处逻辑、适配一个新的数据源。但百万行存量项目的二开，第一道坎是读懂：读不懂，改动寸步难行；改不动，需求只能停在 backlog 里。
在读懂之前，团队普遍面临三重障碍：
第一，入口不明。新人打开仓库，不知道该从哪个目录开始读，哪些文件是核心入口、哪些是边缘工具。花两天翻完目录结构，仍无法建立全局认知。
第二，上下文断裂。模块间依赖关系散落在 import 链、配置文件和运行时行为中，静态阅读难以还原。读懂单个函数容易，理解它在整个系统中的角色很难。
第三，专家资源被反复消耗。每次有新人加入或跨团队协作，核心开发者都要重复讲解同一套架构逻辑。同样的问答在不同人身上反复发生。
这不是某个团队的特殊困境，而是所有维护中大型代码库的研发组织共有的结构性问题——代码量越大、模块越多、历史越久，认知成本越高，且随人员流动持续放大。
代码解读为什么难
代码解读的本质困难不在于单文件的语法理解，而在于三个维度上的信息缺失：
规模维度。一个典型的大型开源项目，源码文件动辄数千。人工通读不现实，即使只覆盖核心路径也需要数天到数周。更关键的是，不同模块的代码风格、设计模式和约定往往不一致，读者需要不断切换心智模型。
上下文维度。代码的真正含义隐藏在调用链、数据流和隐式约定中。一个函数的参数从哪里来、返回值被谁消费、在什么条件下被触发——这些信息分散在整个代码库的不同位置，需要交叉索引才能拼出完整图景。
知识传递维度。资深开发者的隐性知识（为什么这样设计、哪些地方踩过坑、哪些接口不能改）大多停留在口头或零散文档中，没有沉淀为可检索、可复用的结构化资产。一旦关键人员离开，这部分知识随之流失。
传统工具链对这三个维度的支持有限：IDE 的跳转功能解决的是单点导航问题；文档生成工具输出的是 API 级别的参考手册；代码搜索工具返回的是匹配结果而非解读。三者都无法替代一个"读过整个代码库并能回答具体问题"的角色。
用 code wiki 让 ADE 逐层解读 SuperSet
以下演示使用织灵 Coda Loom 2.0（工程级 AI 原生研发平台）的 code wiki skill，引导 ADE（数字机器人，AI R&D Engineer）对 Apache Superset 代码库进行一次完整的自动解读。整个过程分为七个步骤，从项目级概览深入到单行代码语义。
第一步：启动 code wiki skill
用户在 ADE 的意图框中输入了这样一句话：「我想新增/修改 Superset 工程中的代码」——这是一个典型的二次开发诉求。
但要动笔改代码之前，得先读懂这个项目。ADE 因此从"理解"而非"改动"起步：调用 code wiki skill，自动读取 Wiki 模板并扫描项目目录结构。这次代码解读的目标，是为后续的二次开发做准备——先建立全局认知，再谈改动。
第二步：ADE 自动规划任务并执行
ADE 基于项目结构自动生成任务清单，按优先级依次推进：读取前端配置文件、列出核心源码目录、分析路由和入口文件、梳理包依赖关系等。任务列表实时更新完成状态。
第三步：生成完整工程 Wiki 文档
ADE 完成全部分析后，自动生成一份结构化的代码解读文档——"Apache_SuperSet_工程Wiki"。文档涵盖项目概述、核心架构、目录结构、技术栈选型、数据库引擎适配、前后端通信机制等九个章节，每个章节下有分层展开的技术细节。
第四步：针对特定模块发起深入解读
拿到整体文档后，用户聚焦到其中一个技术难点："请详细解读一下数据库引擎适配模块"。ADE 收到指令后，重新规划针对 db_engine_specs 子模块的分析任务，定位到 76 个相关源文件。
第五步：生成模块级深度解读文档
ADE 对数据库引擎适配模块完成逐层分析后，输出独立的详细解读文档——"Superset 数据库引擎适配模块（db_engine_specs）详解"。文档共 16 个章节，覆盖模块定位与设计理念、BaseEngineSpec 核心机制、两条继承链路（PostgreSQL 系列与 Presto 系列）、SQL 生成与转换、方言特性差异、认证机制、分区支持等全部关键技术点。
第六步：对文档中的具体表述追问
用户在已生成的 Wiki 中标记了一句话："Superset 将 SQLStatement 视为抽象基类，而不是 EngineSpec"，要求 ADE 给出代码证据层面的解释。这是从"文档级解读"进入"代码证据级验证"的关键一步。
第七步：ADE 以代码证据逐句解答
ADE 定位到 db_engine_specs/base.py 第 1360 行和第 1373 行的实际代码，展示 get_limit_from_sql 和get_cte_query 两个方法的具体实现，说明 SQLStatement 如何作为抽象基类持有 engine 属性进行解析委托，以及它与 EngineSpec 在类层次结构中的真实关系。同时给出完整的继承体系图：BaseSQLStatement → SQLStatement / KustoQLStatement，以及 SQLScript 作为容器类的定位。
从自动规划到逐层追问：code wiki 的工作方式
上述七步演示揭示了一个关键区别：code wiki skill 不是一次性脚本，而是一个可持续深入的解读工作流。
自动规划阶段。ADE 接到解读指令后，不需要人工拆解任务或指定阅读顺序。它基于 code wiki skill 内置的分析框架，自行决定先读配置文件、再扫目录结构、然后深入各子模块——这个规划过程对应了有经验开发者接手新项目时的自然顺序。
结构化输出阶段。ADE 不是零散地回答问题，而是按照 Wiki 模板生成带目录、分章节的结构化文档。这份文档本身就是可复用的知识资产，后续团队成员可以直接查阅，无需重复提问。
逐层深入阶段。当用户从项目级概览聚焦到某个具体模块时，ADE 能够在该模块范围内重新执行完整的分析流程——定位文件、读取源码、梳理依赖、生成新的专门文档。这一步不是对前文的补充，而是独立的一次深度分析。
代码证据阶段。最关键的区分在于最后一步：当用户对文档中的某句话提出质疑或要求进一步解释时，ADE 不做泛泛的理论阐述，而是直接定位到具体的源码行号、展示实际代码、画出类层次结构图。这种"文档→代码证据"的双向追溯能力，是静态文档工具无法提供的。
这套工作流的核心价值在于：它将"读懂一个代码库"这件事，从一个依赖个人经验和时间投入的黑盒过程，转化为一个可重复、可追溯、可积累的结构化流程。每一次解读的结果都沉淀为文档资产，每一次追问都锚定到具体代码位置。
研发知识的可沉淀性
代码库本身不会说话。让它开口的，是持续投入其中的阅读者、调试者和维护者。但这些认知长期散落在个体头脑里、聊天记录中和临时笔记上——存在过，却没有被结构化地保存下来。
对一个需要二次开发的存量项目，这种散落会被放大成直接风险。二开不是对着空白文件写新功能，而是在别人留下的百万行代码里落子；落子之前，须先看懂棋盘——哪些是活路、哪些是雷区、哪条调用链动一处会牵动全局。看不懂就改，等于蒙眼拆弹。
当一个 AI 研发智能体能够自动完成"扫描—规划—解读—文档—追问—代码证据"的全链路工作时，它做的不仅是替人阅读代码，而是将原本难以传递的隐性知识显式化、结构化、可复用化——这些沉淀下来的理解，正是后续二次开发赖以落子的地图。
一次完整的 code wiki 解读，产出的不仅是一份文档，而是一套可供后续所有成员直接调用的代码知识基座。新成员入职不再需要专人带读，跨团队协作不再需要反复对齐认知，代码评审不再需要从头解释设计意图，二次开发也不再需要从零重新理解存量逻辑。
研发组织中最大的浪费，不是写错了代码，而是同一份代码被不同的人反复以不同的方式解读。把解读结果沉淀下来，让下一次提问直接命中已有答案——理解沉淀后，才改得动；读懂，是二开的第一步。