先理解再动手：让 AI 先检查仓库结构、汇报发现，确认无误后再改代码

一、问题的重新定义：为什么"盲改"必然翻车

过去两年，AI 编码工具的交互范式高度趋同：用户描述需求，模型直接输出代码补丁。这套范式在"单文件、自包含、无外部依赖"的任务上表现尚可，但一旦进入真实仓库——动辄数万文件、多层抽象、隐式约定遍布——失败率急剧上升。SWE-bench 系列基准的公开结果反复印证了这一点：早期模型在 SWE-bench 上的解决率长期停留在个位数到十几个百分点区间，即便到 2024—2025 年，头部模型在 SWE-bench Verified 上的成绩才逐步攀升至较高水平（数据来源：SWE-bench 官方 leaderboard，2025）。

值得注意的是，这些失败案例中，相当比例并非"模型不会写这个函数"，而是"模型不知道这个函数应该写在哪里、应该复用哪个已有工具、应该遵循哪种错误处理约定"。换言之，失败发生在"理解"环节，而非"生成"环节。这是本文立论的起点。

1.1 三类典型翻车场景

笔者在多个真实项目中归纳出三类高频失败，它们共同指向同一个根因——上下文缺失：

• 重复造轮子型：仓库里已有 utils/date.ts 提供了日期格式化，AI 却在业务文件里重新写了一个。原因是它没扫描工具目录。
• 约定违背型：项目统一用 Result 类型而非抛异常，AI 却抛了异常。原因是它没读项目的错误处理规范或既有代码模式。
• 接口错配型：AI 调用的函数签名与真实定义不符，因为它只看到了调用处，没看到定义处。

这三类问题的共同解法，不是"让模型更聪明"，而是"让模型先看再写"。本文评述：把可靠性问题归因于模型能力，是一种直觉上诱人但工程上低效的归因。能力提升是缓慢的、被动的；而改变上下文供给顺序，是当下即可主动施加的控制。

1.2 一个被忽视的事实：生成成本远低于理解成本

从 token 经济学看，生成一段 50 行的补丁，成本可能只有几百 token；而让模型真正理解一个中等仓库的相关上下文，往往需要读取数千到数万 token。这意味着，跳过理解直接生成，在短期 token 消耗上是"省钱"的，但在返工、调试、代码审查的总成本上是"烧钱"的。Aider 等工具之所以强调"repo map"（仓库地图）机制，正是因为它把理解成本前置，换取生成质量的提升（来源：Aider 官方文档，2024—2025）。

理解不是生成的前置装饰，而是生成质量的决定性变量。把理解显式化，就是把质量可控化。

二、理论根基：认知负荷、上下文窗口与仓库级理解

要论证"先理解再动手"不是经验之谈而是有理论支撑的工程原则，需要回到三个概念：认知负荷理论、上下文窗口的有效利用、以及仓库级代码理解的研究脉络。

2.1 认知负荷理论对 AI 的类比适用性

Sweller 在 1988 年提出的认知负荷理论（Cognitive Load Theory）区分了内在负荷、外在负荷与相关负荷（来源：Sweller, Cognitive Science, 1988）。本文评述：把这一框架类比到 LLM 编码任务上，具有启发意义——内在负荷对应任务本身的复杂度，外在负荷对应无关上下文的干扰，相关负荷对应真正有助于构建解决方案的信息。当模型在缺乏仓库上下文时被迫生成，它实际上是在用"猜测"填补相关负荷的缺口，从而产生高错误率。先侦察，就是把相关负荷"喂饱"，把外在负荷"过滤掉"。

需要说明的是，这是一种类比而非严格的心理机制等同。LLM 没有人类的工作记忆，但其注意力机制在长上下文中的"稀释效应"已被多项研究观察到（来源：Liu et al., "Lost in the Middle", TACL 2024）。该研究指出，模型对上下文中间位置信息的利用显著弱于首尾位置——这意味着"把整个仓库塞进上下文"不仅昂贵，而且低效，结构化侦察比暴力全量读取更符合模型的信息利用特性。

2.2 上下文窗口的"有效容量"问题

当前主流模型的上下文窗口已从早期的 4K、8K 扩展到 128K、200K 甚至更高。但"窗口大"不等于"有效容量大"。多项基准显示，模型在超长上下文中的检索与推理能力会随长度衰减（来源：Anthropic 长上下文评测、Google Needle-in-a-Haystack 系列，2023—2025）。

注：上表 token 量级为工程经验性整合估计（模拟数据），非单一文献精确测量，仅供量级参考。

2.3 仓库级代码理解的研究脉络

仓库级理解并非新问题。在 LLM 之前，代码检索、程序依赖图（PDG）、调用图分析已有长期积累。RepoBench（2023）等工作把"跨文件代码补全"作为基准，明确要求模型利用仓库上下文（来源：RepoBench, ICLR 2024）。SWE-agent（2024）则进一步把"与仓库交互"本身建模为智能体行为，让模型通过命令（如查看文件、搜索、运行测试）逐步建立理解（来源：SWE-agent, NeurIPS 2024）。

本文评述：SWE-agent 的关键贡献不在于"更强的模型"，而在于"给模型一套可操作的仓库交互接口"。这印证了本文主线——改变交互顺序与接口，比单纯堆模型能力更能提升仓库级任务的成功率。侦察阶段，本质上就是把这套交互接口固化成一个标准流程。

三、三阶段范式：侦察（Recon）—汇报（Report）—确认（Confirm）

基于上述理论，本文提出一个可落地的三阶段范式。它不是对现有工具的替代，而是对现有工具使用方式的"流程约束"。

这条主线的核心洞察是：把"理解"从模型的隐式内部状态，转化为一个显式的、可被人类审查的中间产物。一旦理解被显式化，错误就能在"改代码之前"被拦截，而不是在"测试失败之后"才被发现。这与软件工程中"设计评审先于编码"的经典实践一脉相承。

四、侦察阶段：让 AI 读懂仓库结构的操作路径

侦察阶段的关键是"有章法地读"，而不是"漫无目的地读"。下面给出一套可复用的操作路径。

4.1 第一步：建立仓库地图（Repo Map）

仓库地图是对"这个仓库由什么组成"的高层抽象。Aider 的实现思路是：用 tree-sitter 解析各文件的关键符号（类、函数、方法签名），再按重要性排序压缩成一份紧凑的符号清单（来源：Aider repo map 文档，2024）。本文评述：这种做法的聪明之处在于，它不注入完整代码，只注入"骨架"，从而在极低 token 成本下让模型获得全局结构感。

一个最小可行的仓库地图应包含：

• 顶层目录结构与各目录职责（如 src/、tests/、scripts/）
• 构建与依赖清单（package.json、pyproject.toml、go.mod）
• 核心模块的公开接口签名
• 测试框架与运行方式

可参考的拓展资源：Aider Repo Map 官方文档；tree-sitter 官方站点 tree-sitter.github.io。

4.2 第二步：定位相关子系统

拿到地图后，AI 需要根据任务定位相关子系统。推荐用"由粗到细"的三轮检索：

1. 关键词检索：用任务中的核心名词（如"订单""支付回调"）在仓库中做全文检索，得到候选文件列表。
2. 依赖追踪：对候选文件，向上追踪其被谁调用、向下追踪其调用了谁，形成一个小型依赖子图。
3. 模式确认：在子图内寻找"同类功能是怎么写的"，以此推断项目约定。

侦察的目标不是"读得多"，而是"读得准"。三个精准的文件，胜过三十个无关文件。

4.3 第三步：提取约定与规范

项目约定往往不写在文档里，而藏在代码里。侦察阶段应主动提取以下信号：

关于代码规范提取，可参考 Google Style Guides 作为通用参照，但更重要的是识别项目自身的既有模式。

4.4 侦察阶段的提示词骨架

下面给出一个可直接改造的侦察提示词骨架（以通用编码助手为例）：

你现在的角色是"仓库侦察员"，禁止修改任何文件。

任务背景：{用户需求}

请按以下步骤执行，并只输出发现，不输出补丁：
1. 列出仓库顶层目录，说明每个目录的职责（若无法确定，标注"不确定"）。
2. 用关键词 {核心名词} 检索，列出最相关的 3–8 个文件及其作用。
3. 对每个相关文件，给出其对外暴露的关键函数/类签名。
4. 总结项目在错误处理、命名、测试上的既有约定，并各举一个代码位置作为证据。
5. 列出你仍然不确定、需要人类澄清的问题。

输出格式：Markdown，分节对应上述 5 步。

本文评述：这个骨架的关键设计是第 4 步"举证据"和第 5 步"列不确定"。前者强制模型把结论锚定到具体代码位置，降低幻觉；后者把模型的"知识边界"显式暴露，为确认阶段提供输入。

五、汇报阶段：结构化发现报告的设计与模板

侦察产出的是原始信息，汇报产出的是"可决策的理解"。两者的差别，类似于"日志"与"诊断报告"的差别。

5.1 一份好的发现报告应回答什么

笔者认为，发现报告应至少回答六个问题：改哪里、依赖谁、遵循什么、风险在哪、不确定什么、建议怎么做。这六问构成一个完整的"变更前认知"。

## 1. 变更范围
- 拟修改文件：xxx.ts（第 N 行附近）
- 拟新增文件：无 / yyy.ts
- 不涉及：zzz 模块

## 2. 依赖关系
- 上游调用方：a.ts, b.ts
- 下游依赖：utils/date.ts 的 formatDate()
- 外部库：lodash（已在 package.json 中）

## 3. 需遵循的约定
- 错误处理：返回 Result，证据：src/core/result.ts
- 命名：camelCase 函数，PascalCase 类型，证据：src/models/*.ts
- 测试：vitest + 就近 __tests__ 目录，证据：src/utils/__tests__/

## 4. 风险点
- 该函数被 3 处调用，签名变更会波及调用方
- 涉及异步时序，需注意竞态

## 5. 不确定项（需人类确认）
- 是否应复用 utils/date.ts 而非新写？
- 错误码是否需要新增枚举值？

## 6. 建议方案
- 方案 A：在 xxx.ts 内新增分支，复用 formatDate
- 方案 B：抽出新函数放入 utils
- 推荐：方案 A，改动面最小

5.2 为什么"不确定项"是报告的灵魂

很多 AI 编码流程的失败，源于模型"假装自己懂了"。它会自信地给出一个方案，而人类直到测试失败才发现前提错了。本文评述：强制模型输出"不确定项"，是一种低成本的"校准"机制。它把模型的置信度外化，让人类可以在最便宜的时刻介入——在写代码之前，而不是在调试之后。

这一思路与"校准"（calibration）研究相呼应：让模型表达不确定性，有助于下游决策（来源：Kadavath et al., "Language Models (Mostly) Know What They Know", 2022）。虽然该研究并非专为编码场景，但其结论对本文范式具有支撑意义。

5.3 汇报的粒度控制

报告过粗则无用，过细则淹没重点。建议按任务风险分级控制粒度：

六、确认阶段：人工门禁与风险分级

确认阶段是整套范式的"闸门"。没有闸门，前两阶段的价值会大打折扣——因为模型仍可能带着错误理解进入生成。

6.1 确认的三种形态

• 人类确认：由开发者审阅报告，逐项打勾或修正。适合高风险变更。
• 规则确认：用脚本校验报告是否满足硬性条件（如"必须列出测试文件""必须标注不确定项"）。适合中低风险。
• 对抗确认：让另一个模型扮演"审查者"，专门挑报告中的漏洞。适合需要规模化处理的场景。

本文评述："对抗确认"值得单独强调。让生成者与审查者分离，是一种经典的工程制衡。在 LLM 场景下，审查者模型不需要更强，只需要"立场不同"——它的任务是找茬，而非附和。这与软件工程中的代码评审文化同构。

6.2 确认清单（Checklist）

6.3 确认失败的常见处理

确认不通过时，不应直接让模型"再改改"，而应把人类的修正意见作为新的侦察输入，回到阶段一。本文评述：这个"回退到侦察"的设计很重要。它避免了在错误理解上叠加修补，从而陷入"越改越乱"的泥潭。理解错了，就重新理解，而不是在错误的地基上盖楼。

七、工程落地：工具链、提示词与自动化编排

理论要落地，必须有工具链支撑。本节给出一套可操作的工程方案。

7.1 工具链选型

拓展资源：SWE-agent GitHub；OpenHands GitHub；ast-grep 官网。

7.2 用 CI 固化"确认门禁"

一个实用的做法是：要求 AI 在提交代码前，先提交一份 RECON.md，并在 CI 中校验其结构完整性。例如用一段简单脚本检查报告是否包含必要小节：

#!/usr/bin/env bash
# check_recon.sh —— 校验侦察报告结构
REQUIRED=("变更范围" "依赖关系" "需遵循的约定" "风险点" "不确定项" "建议方案")
for section in "${REQUIRED[@]}"; do
  if ! grep -q "$section" RECON.md; then
    echo "缺少小节: $section"
    exit 1
  fi
done
echo "侦察报告结构完整"

本文评述：把"理解"变成 CI 的一部分，是这套范式从"个人习惯"升级为"团队规范"的关键一步。它让"先理解再动手"不再是靠自觉，而是靠流程强制。

7.3 与现有工作流的集成

在 Pull Request 流程中，可以把侦察报告作为 PR 描述的第一部分，把代码补丁作为第二部分。评审者先看理解，再看实现。这种"先理解后实现"的 PR 结构，本身就是对本文范式的天然载体。

八、实证与基准：从 SWE-bench 到真实仓库的差距

任何方法论都需要接受实证检验。本节梳理公开基准给出的信号，并讨论基准与真实仓库的差距。

8.1 SWE-bench 系列给出的信号

SWE-bench 由 Princeton NLP 团队提出，任务是从真实 GitHub issue 出发，在真实仓库中生成补丁并通过测试（来源：Jimenez et al., "SWE-bench", ICLR 2024）。其 Verified 子集经过人工筛选，去除了描述不清或测试不可靠的样本。公开 leaderboard 显示，模型成绩在 2023—2025 年间快速提升，但即便头部方案，仍有相当比例的 issue 无法解决（数据来源：SWE-bench 官方 leaderboard，2025）。

本文评述：SWE-bench 的价值在于它把"仓库级理解"变成了可量化的任务。但需要注意，它仍是"离线、单轮、有明确测试"的设定。真实开发中，需求模糊、测试缺失、跨团队协作等因素会进一步拉低成功率。因此，基准成绩应被视为"上限参考"，而非"生产可用性"的直接证据。

8.2 RepoBench 与跨文件理解

RepoBench 聚焦跨文件代码补全，明确测试模型能否利用仓库中其他文件的信息（来源：RepoBench, ICLR 2024）。其结论之一是：提供相关跨文件上下文能显著提升补全质量，但"如何选对上下文"本身仍是难点。本文评述：这恰好印证了侦察阶段"读得准比读得多更重要"的判断。检索质量，而非上下文长度，才是关键变量。

8.3 基准与真实仓库的三重差距

这三重差距说明：真实场景比基准更依赖"理解与确认"环节。这也正是本文范式在工程上更有价值的原因。

九、前沿预判：仓库级上下文工程的下一步

基于当前研究趋势，笔者对"先理解再动手"范式的演进做几点审慎预判。

9.1 从"检索增强"到"理解增强"

当前主流是 RAG（检索增强生成）式的上下文注入。下一步可能走向"理解增强"：不仅检索相关代码，还主动构建调用图、数据流图、变更历史图，把"结构化理解"作为一等公民注入模型。本文评述：这与本文侦察阶段的方向一致，只是自动化程度更高。未来的侦察，可能由专门的"理解智能体"完成，而非通用编码模型兼职。

9.2 理解产物的标准化

如果"发现报告"能形成行业通用格式（类似 SARIF 之于静态分析），那么不同工具、不同模型之间的理解产物就可以互相校验、复用。这是一个值得期待的工程标准化方向。

9.3 人机确认界面的演化

确认阶段目前主要靠文本报告。未来可能出现更结构化的"理解可视化"界面：以图的形式展示 AI 对仓库的认知，人类直接在图上修正。本文评述：这本质上是把"心智模型对齐"从文本层提升到图形层，有望进一步降低确认成本。

9.4 需要警惕的过度依赖

任何范式都有边界。如果团队把"确认"完全自动化、无人把关，那么错误理解仍可能被放行。本文评述：确认环节的价值恰恰在于"人类判断的不可替代性"。高风险变更上，人类不应把确认权外包给规则或模型。这是工程审慎，也是责任边界。

十、结论与行动清单

回到本文主线：AI 编码的可靠性瓶颈，本质上是"上下文获取顺序"的问题，而非"生成能力"的问题。把理解显式化为可审查的中间产物，是当前阶段提升 AI 编码可信度性价比最高的手段。

"先理解再动手"听起来像一句朴素的工程常识。但在 AI 编码的语境下，它需要被重新设计为一套可执行的流程、可校验的产物、可度量的收益。本文所做的，正是把这句常识，翻译成可落地的工程语言。

主要参考文献