AI从零介绍代码架构的复盘(含要使用的提示词)

复盘:如何用提问,引导 AI 产出一份完整的代码深度解析

这份文档复盘了"channelLive 深度解析"是怎么一步步被问出来的,以及下次面对一个陌生项目,如何提问才能让 AI 产出同样质量的 step-by-step 讲解。

阅读对象 :希望用 AI 快速吃透新代码/新项目的开发者。

可迁移范围:任何陌生代码库(Java 微服务、Python ML、Go 后端、前端项目......),不限于 Spark/Scala。

一、一次成功对话的时间线复盘

复制代码

开场
└── "把我当从没看过代码的人,讲清楚业务,包括隐藏的逻辑细节"
    └── AI 输出一版完整的业务地图(宏观 → 流程 → 坑)

深化(逐步下钻)
├── 质疑来源:"冷启动概念从哪里来?"
│     └── 迫使 AI 区分"代码事实"和"推测"
├── 要求锚点:"加上代码出处,重新产出一遍"
│     └── 迫使 AI 每条结论都带 文件:行号
├── 指定对象:"讲一下 getClickRDD 和 getNewUserRDD"
│     └── 从宏观下钻到具体方法
├── 继续下钻:"brace glob 说明一下"
│     └── 从代码行为下钻到底层机制
└── 提供事实:贴出 properties 文件
      └── 把抽象的"窗口"坐实为"1 小时",并修正之前举例

对齐理解(复述验证)
├── "是不是用 1 小时点击 + 全天新增?"
├── "startRDD 是时间最早那条,对吧?"
├── "Step 3 是先按 2 个条件过滤,对吧?"
├── "拉活的 1002 只和 1 小时点击匹配,对吧?"
└── "Kafka 的 offset 从来没被读过,对吧?"

扩展边角(连环问)
└── Step 5 三连问:
    ├── PlatPartitioner 如何绑定媒体名和分区号?
    ├── 目录是不是按日期分、不按媒体分?
    └── UseUser 是出现 1002/2002 就记,还是匹配上点击才记?
          └── 第三问暴露了初版遗漏的"今日第一次打开必须是拉活"业务约束

收尾
└── "把以上所有讨论整理成文档,但排除 XX 问题"
    └── 产出结构化 Markdown 文档

关键观察 :这份文档不是 AI 一次输出的,是用户用 15 轮问题逼出来的。每次用户问"XX 对吗?",AI 都要重新读代码确认,很多细节(如 UseUser 保存条件比 isChannelLive 松得多)是在"验证"时才被挖出来的。

二、哪些做法起了作用(按作用大小排序)

1. 开场明确了"受众 + 深度",最重要

原话:

"把我当成一个从来没有看过这些代码的人,给我讲清楚业务"

"包括严格的数据匹配字段,各种隐藏在代码之间的逻辑细节"

这一句话里包含 3 个关键信号:

信号	作用
受众:零背景的人	AI 必须补齐术语和背景
宽度:业务 + 逻辑细节	不能只讲 happy path
深度:"隐藏在代码之间"	必须读完代码,不能靠文件名/注释敷衍

对比:如果开场只是"讲一下 channelLive 做什么",AI 可能只会给前三段。差距 80% 来自开场的具体性。

2. 要求"代码出处",是文档质量的分水岭

一句"加上代码出处,重新产出一遍",迫使 AI:

不敢再合理推测,必须真读代码
文档读者可以跳到代码核实,不用全信 AI
AI 下次对话可以根据文档回溯

对比:没有行号的概述文档,过几个月就没人敢用了,不如直接读代码。

3. "是不是 XX,对吧?"式验证,是最高效的提问句式

统计用户在这次对话里的使用次数:

"是不是用 1 小时点击..."
"startRDD 是最早那条,对吧?"
"Step 3 是过滤后保留..."
"拉活的 1002 只和 1 小时点击匹配,对吧?"
"Kafka 的 offset 从来没被读过,对吧?"

为什么高效:

迫使 AI 判断对错,而不是重复讲
AI 必须给严格答案("对,但 X 要微调")而不是模糊肯定
用户每复述一次,AI 就有机会补一条边角(例如 Step 3 复述时补了"两个数据源时间窗口不同")

4. 挑战来源("从哪里得来的?")

"冷启动"那一问是漂亮的反击。AI 原本在复用代码注释当事实,被这一问逼得分出四个层级:

来源	可信度
代码事实(if/filter/断言)	高
代码注释	中
样例日志的相关性	中偏低
AI 的常识推测	低

对工程判断的价值:知道哪些结论能押注,哪些只是"大概率"。

5. 从宏观一路下钻到底

问题序列的"下钻层级":

复制代码

业务全貌 (宽)
  → 具体方法 getClickRDD (中)
    → 方法里某一行 brace glob (窄)
      → 底层机制 (glob 对空分支的处理)

每层下钻都带着上一层的上下文。避免"每轮重新讲背景"的浪费。

6. 用具体问题暴露初版盲区

Step 5 的三连问尤其有价值:

问题	暴露的盲区
PlatPartitioner 怎么绑定媒体名和分区号?	初版只说"按媒体分区",没讲排序和映射构造
目录是不是按日期分、不按媒体分?	初版默认用户知道,实际是关键的设计选择
UseUser 是出现就记还是匹配上才记?	暴露了初版遗漏的"今日第一次打开必须是拉活"业务约束

没有第三个问题,这个重要业务约束就被埋了。

三、哪些做法作用一般、或可以更好

1. 开场可以再加几个要素

初版开场主要定了"宽度 + 深度"。可以更明确地加:

输出格式:"用步骤 + 表格,不要大段散文"
锚点要求:"每条结论带文件:行号"(避免被反复催)
AI 的无知边界:"告诉我哪些你没把握"
交付物:"结束时能形成一份可以转发给新人的文档"

2. "验证式提问"虽好,但有疏漏兜底

每轮验证只能覆盖用户想到的部分。有些 AI 讲过但用户没验证的,可能带着错误被当真。可以主动问:

"我上面哪些描述有可能是错的?"
"你上面讲的每一条,置信度分别有多高?"
"你有没有合理推测被我当成事实接受了?"

3. 应该更早要配置文件

properties 读到 "1 小时" 后,之前的例子全要修正。如果一开始就说:

"相关的配置文件(properties/yaml)在 XX,先读一遍再讲"

就不会出现"举例用假设值,后来一堆地方改口"的问题。

四、下次给陌生项目的"开场模板"

适用场景:想在一次会话里,把一个完全陌生的模块彻底搞懂,并产出可留存的文档。

模板(照抄即可,替换括号里的内容)

复制代码

我想完整理解 [项目/模块路径],把我当成从未看过代码的人。
请按下面的方式工作:

【第一步 探测范围】
先把模块的入口文件和主要类列出来,给我一张"文件 → 作用"地图。
配置文件 (properties / yaml / xml) 优先读完,把实际配置值告诉我,
不要用假设值举例。

【第二步 讲业务】
一句话定位这个模块做什么业务。
然后按 "输入 → 流程 → 输出" 讲一遍。
每条结论带代码出处 (文件:行号),便于我跳转。

【第三步 讲细节】
把这些内容分开讲:
  - 严格的数据匹配字段(每个字段的筛选条件和默认值)
  - 跨批次 / 跨进程 / 跨服务的状态存储(存哪、读哪、保留多久)
  - 隐藏在代码之间的坑(容易误解的、容易改坏的、硬编码的假设)
  - 配置热更新 / 定时任务 / 分区策略 等机制

【第四步 诚实边界】
明确告诉我:
  - 哪些结论来自代码事实(if、filter、断言)
  - 哪些来自代码注释(可能是经验,也可能过时)
  - 哪些是你的推测或常识补齐
不要混在一起。

【输出格式要求】
- 用步骤 + 表格 + 代码块,少用大段散文
- 关键函数用完整签名引用,附上行号
- 每一步末尾用一句话 "本步做了什么" 收束

【交付物】
全部讨论结束后,整理成一个 Markdown 文档保存到 [路径]。

这个模板能避免什么

✅ 开场就定了"受众 + 格式 + 锚点 + 边界",AI 不用猜
✅ 配置文件先读,后续举例不会废
✅ 分块讲(数据/状态/坑/机制),用户不会抓不住重点
✅ 明确要求区分"事实 / 注释 / 推测",AI 不会把注释当事实
✅ 交付物在开场就定,收尾更顺

五、追问阶段的"4 把钩子"

模板只是开场。真正把文档拉深的是追问阶段。推荐 4 种钩子,轮流用。

钩子 1:复述验证

"是不是 XX,对吧?" / "我理解是 YY,对吗?"

作用:逼 AI 给精确答案而不是啰嗦复讲
收益:AI 每次会告诉你"对,但 X 要微调",微调里往往有金子
节奏:讲完一段 → 用自己的话复述 → AI 校准

钩子 2:来源追问

"这个结论从哪里得来的?" / "这个数字写在哪里?"

作用:把 AI 的"合理推测"揪出来,区分事实和经验
收益:知道哪些结论能押注,哪些需要再确认
时机:AI 下断论的时候问一句

钩子 3:单点下钻

"讲一下 XX 方法/类/字段" / "展开讲一下 YY 这个机制"

作用:避免宏观讲完就停,把宏观下的具体细节挖出来
收益:最深的坑往往藏在某个 private 方法的一行里
时机:宏观流程看完,挑一个最重要/最可疑的点

钩子 4:边界探测

"如果 XX 不存在会怎样?" / "跨零点怎么处理?" / "多个线程同时 XX 会怎样?"

作用:暴露代码的隐含假设
收益:找出硬编码的脆弱点、未处理的边界、隐性契约
时机:主流程理清后

六、一个反例对照

如果开场只说:

"讲一下 channelLive"

AI 大概率会给:

包的名字含义
入口类
大概流程
2-3 条业务概述

4 段话就结束了,看不出任何细节,也没法当文档。

两种开场的差距 ,80% 来自"是否明确了受众 + 深度 + 格式"。模板里那三行是关键。

七、简化版清单(贴墙上)

开场说清 4 件事

受众(把 AI 当什么人:新人、同事、专家)
宽度 + 深度("业务 + 隐藏逻辑")
输出格式(步骤 / 表格 / 代码出处)
诚实边界(事实 / 注释 / 推测分开)

追问用 4 把钩子

复述验证 ------ "是不是 XX,对吧?"
来源追问 ------ "这个从哪来的?"
单点下钻 ------ "讲一下 YY"
边界探测 ------ "边界情况怎样?"

收尾说一句

"把以上所有讨论整理成 Markdown,保存到 XX"

八、这次对话里几个值得记住的瞬间

瞬间	为什么值得记住
"冷启动从哪来?"	质疑来源,是比确认答案更珍贵的习惯
"加代码出处重来一遍"	让文档从"概述"升级到"可用参考"
"是不是 XX,对吧?" 系列	低成本高收益的验证句式
Step 5 第三问	一个具体问题挖出了被埋藏的核心业务约束
贴出 properties	用事实把抽象配置坐实

九、最后一句

这份方法不是"问 AI 的技巧",而是"任何陌生代码库自学的方法":

复制代码

先摸地图(入口 + 配置)
  → 看主干(业务 + 流程)
    → 挖细节(字段 + 状态 + 坑)
      → 验证理解(复述)
        → 质疑来源(事实分级)
          → 整理落盘(可留存文档)

AI 只是把这个流程压缩到一次对话里。真正的能力是你知道该问什么、该挑战什么、该坐实什么。