摘要
随着大语言模型和智能编程代理在软件研发流程中的普及，AI Coding 正在显著改变代码生成、重构、测试与评审的组织方式。对于小型项目而言，AI 往往能够在有限上下文中完成相对完整的实现任务；然而，在大型软件项目中，代码规模、历史债务、隐式业务规则、模块耦合和团队协作流程共同构成了复杂的工程环境。此时，AI Coding 的主要价值并不在于简单提升代码产出速度，而在于通过结构化理解、特征测试、活文档、Git 管理和持续集成门禁，构建一个可验证、可追踪、可回退的质量治理体系。
本文围绕大型项目中 AI Coding 的典型风险展开分析，进一步提出一种以“理解—锁定—小步变更—自动验证—人工裁决”为核心的软件工程治理框架。该框架强调：AI 不应被直接赋予无边界的系统设计与重构权限，而应在明确的架构边界、行为规范和质量门禁中承担高频、机械、可验证的实现工作。人的角色则从传统意义上的代码实现者，逐渐转向边界定义者、验证标准制定者和最终语义裁决者。
关键词：AI Coding；遗留系统；特征测试；GitHub Workflow；持续集成；软件工程治理；活文档；大型项目重构
1. 引言
AI Coding 的出现，使软件开发过程中的代码生成效率获得了显著提升。对于个人项目或小型系统，AI 可以基于完整上下文快速完成函数、页面、接口或模块的实现。然而，大型项目具有完全不同的工程特征：代码库规模庞大、上下文无法一次性完整输入模型、历史逻辑难以追溯、业务行为高度依赖隐式约定，且团队协作会将多个开发者与多个 AI Agent 的产出同时推向主干分支。
在这种背景下，单纯使用更强大的模型并不能根本解决问题。模型能力增强虽然可以提升局部代码生成质量，但上下文窗口、遗留行为、代码所有权、测试覆盖率和主干门禁等工程问题依然存在。大型项目真正需要的不是“让 AI 写得更多”，而是“让 AI 的产出进入可治理的工程系统”。
因此，AI Coding 在大型项目中的核心命题应当从“如何生成代码”转向“如何安全地生成、验证、追踪和合并代码”。这意味着团队需要建立一套围绕 AI 产出的质量控制机制，使 AI 的高产能不再成为系统风险的放大器，而成为工程效率的可控增益。
2. 大型项目中 AI Coding 的三类核心风险
大型项目中的 AI Coding 风险主要体现在三个方面：上下文不完整、遗留代码不敢改、产出规模难以治理。
2.1 上下文不完整导致局部合理、全局错误
AI 模型通常只能基于有限上下文作出判断。在百万行级别的代码库中，一个函数、一个类或一个模块可能与大量调用方、配置项、数据库副作用、事件机制和历史兼容逻辑相关联。AI 在局部上下文中生成的代码可能是合理的，但一旦放入全局系统，就可能破坏未被模型看到的依赖关系。
这类风险并非源于模型“随意编造”，而是源于模型无法完整感知系统全貌。大型项目中的许多错误并不是语法错误或局部逻辑错误，而是跨模块、跨状态、跨历史行为的系统性偏差。
2.2 遗留代码行为不明导致重构风险上升
大型系统中的老代码往往已经在线上运行多年。其结构可能混乱，命名可能不清晰，甚至存在多个计算路径和不一致的业务口径。然而，这些代码之所以难以修改，是因为团队无法确认其中哪些行为是错误，哪些行为已经被下游系统、财务规则、运营流程或客户使用习惯所依赖。
AI 具备较强的重构能力，但这反而会放大风险。若没有测试和行为规范约束，AI 很容易在“整理代码”的同时顺手修正看似不合理的逻辑。问题在于，一旦重构和修 bug 混在同一个变更中，线上行为发生变化后，很难定位风险来源。
2.3 AI 高产出冲击传统代码审查机制
当团队成员普遍使用 AI Agent 后，PR 数量和代码变更量会显著增加。过去依赖人工经验和个人责任感维系的代码审查机制，可能无法承受这种产出速度。若缺乏自动化门禁，AI 生成的大量代码会快速涌入主干，导致主干质量失控。
因此，AI Coding 的工程治理不能只关注单个开发者如何使用 AI，而必须关注团队层面的产出管理机制。Issue、Branch、Commit、PR、CI、Required Check 和人工 Review 必须共同构成主干保护系统。
3. 大项目中的 AI 分工转变：从“写实现”到“填边界”
在小型项目中，AI 可以被视为一个较完整的实现者。由于项目规模有限，模型能够在上下文窗口中获取较完整的信息，从而完成端到端实现。
然而，在大型项目中，AI 不适合直接承担系统级设计职责。大型项目的架构通常不是一次性设计完成的，而是在业务演进、技术债务、组织调整和历史兼容中逐步形成的。模块边界、接口契约、兼容策略和状态迁移方案往往需要人基于业务背景和历史经验进行判断。
因此，大型项目中的合理分工应当是：
- 人负责定义架构边界；
- 人负责明确模块职责；
- 人负责制定接口契约；
- 人负责确定验证标准；
- AI 负责在明确边界内完成实现、补测试、抽函数、修复 lint 和整理重复逻辑。
这意味着人的价值并未降低，而是从“具体编码”转向“边界设定和质量裁决”。AI 的优势在于高频、机械、可验证的代码操作；人的优势在于业务语义判断、架构取舍和风险承担。
4. 上下文工程：大型项目中 AI Coding 的前置条件
大型项目中 AI 的典型失败并非来自“不会写代码”，而是来自“缺少必要上下文”。因此，上下文工程成为 AI Coding 的关键基础设施。
上下文工程并不是把整个代码库塞给 AI，而是在每次任务中准确选择与当前变更相关的信息。有效的上下文工程通常包含三类方法。
4.1 按需检索
围绕当前任务入口，检索相关调用方、被调用方、测试用例、配置项、数据库表结构、历史 issue 和相关 PR。这样可以让 AI 在相对有限的上下文中获得高价值信息。
4.2 分层摘要
对于复杂模块，可以先生成模块级摘要，包括 public API、核心状态、主要依赖和关键业务流程。只有在需要修改具体逻辑时，再下钻到具体实现文件。
4.3 活文档
对于长期维护的系统，文档必须与代码共同演进。一次性生成的 spec 很快会过期，只有将 spec 与 issue、代码、测试和 PR 绑定，才能形成持续有效的知识资产。
上下文工程的目标不是“更多信息”，而是“更准确的信息”。信息过少会导致 AI 猜测，信息过多则会淹没关键上下文并增加误判概率。
5. 遗留代码治理：先理解，再重构
在遗留系统中，第一步不应是让 AI 修改代码，而应是让 AI 只读代码并形成结构化理解。对于复杂遗留模块，AI 首先应输出以下内容：
- Public API 与入口清单：明确哪些函数、类、接口或 import 路径被外部依赖。
- 职责板块划分：识别计价、库存、风控、持久化、通知、审计等职责分别散落在哪里。
- 状态地图：标注数据库、缓存、全局变量、配置、事件和审计记录的读写路径。
- 多套实现识别：找出同一业务逻辑是否存在多个计算路径或历史版本。
- 可疑行为清单：识别看起来可能是 bug、但重构前必须先保持不变的行为。
这一阶段的核心原则是：先描述现状，不提出重构方案；先理解行为，不判断行为是否合理。
大型遗留系统中经常存在多套“事实”。例如，报价逻辑、下单逻辑、老版本结算逻辑、新版本结算逻辑和区域化结算逻辑可能并不一致。若不先承认这些不一致，就无法安全重构。
6. 特征测试：把当前行为锁进测试
遗留系统重构的关键不是立即写出“正确行为”，而是先锁住“当前行为”。这正是特征测试的价值。
特征测试关注的问题不是“系统是否符合理论上的正确规则”，而是“重构前后系统行为是否一致”。它尤其适合用于不敢轻易修改的遗留代码，因为团队往往并不完全知道什么是正确行为，但至少可以知道当前线上系统正在如何运行。
6.1 特征测试与普通测试的区别
| 维度 | 普通测试 | 特征测试 |
|---|---|---|
| 核心问题 | 行为是否正确 | 改动前后是否一致 |
| 适用场景 | 新功能、新规则 | 遗留代码、安全重构 |
| 对 bug 的处理 | 直接写正确行为 | 先锁住当前 bug，后续单独修复 |
| 失败含义 | 实现不符合预期 | 系统行为发生变化 |
| 主要价值 | 保证需求正确实现 | 保证重构不改变既有行为 |
在遗留系统中，任何看似明显的 bug 都不应在重构过程中被顺手修复。正确做法是：先通过特征测试锁住当前行为；如果业务确认该行为确实错误，再单独创建 bug issue 和修复 PR。
6.2 行为面不应只包含返回值
大型系统的行为不仅包括函数返回值，还包括：
- 数据库写入；
- 库存扣减与释放；
- 审计记录；
- 事件发布；
- 日志字段；
- 异常路径；
- warning 类型；
- public import 路径；
- 性能边界；
- 兼容入口。
如果特征测试只验证输入输出，而忽略状态副作用和系统边界，就无法真正保护遗留行为。
7. 安全重构：小步变更与红绿验证
当特征测试补齐并全绿后，才允许进入重构阶段。此时必须坚持一个基本定义：
重构是改变代码结构，而不是改变业务行为。
AI 重构时最容易混入三类不受控行为：顺手优化、顺手修 bug、顺手改命名。为了避免这些行为破坏系统稳定性，应采用小步重构策略。
7.1 保留入口，内部委托
对外 public API、入口函数、返回结构和 import 路径保持不变。内部逐步拆分职责函数或新模块，使下游调用方无感知。这类似于缩小版的绞杀者模式：新结构逐步在旧系统外围生长，并逐步接管内部实现。
7.2 一次只移动一个边界
每次只重构一个函数、一个职责块或一个文件。这样 diff 足够小，人工 review 才能有效进行；测试失败时，也能快速定位是哪一步导致行为变化。
7.3 测试红灯必须立即停止
当特征测试失败时，不应继续扩大修改范围。必须先判断：
- 是测试隔离不足；
- 是测试本身写错；
- 是行为确实发生变化；
- 是 AI 顺手改变了业务逻辑。
如果行为变化不符合本次重构目标，应优先回滚最近一步，而不是继续让 AI 扩大修复范围。
8. Git：AI Coding 的质量控制轨道
在 AI Coding 场景下，Git 不只是版本管理工具，更是质量治理系统的基础轨道。它将 AI 的高产出切分为可理解、可审查、可定位、可回退的工程单元。
| Git 动作 | 工程价值 | 对 AI 产出的意义 |
|---|---|---|
| Issue | 定义目标、验收标准和边界 | 防止 AI 扩大 scope |
| Branch | 隔离风险 | 半成品不污染主干 |
| Commit | 固化小步变化 | 出问题可定位 |
| Diff | 展示真实变更 | 人审基于代码而非聊天记录 |
| Revert | 快速回退 | 避免手工恢复 |
| Bisect | 定位坏提交 | 应对高频 AI 产出 |
| PR | 形成审查对象 | 讨论、评论和合并均有载体 |
“一个 PR 只做一件事”在 AI Coding 中尤其重要。重构、修 bug 和新功能若混在同一个 PR 中，任何线上问题都难以定位根因，也难以局部回滚。
9. 活 Spec：从一次性文档到状态账本
AI 可以快速生成代码说明、模块摘要和行为 spec，但如果这些文档没有维护机制，很快就会变成过期信息。因此，大型项目需要将 spec 设计为可演进的状态账本。
一个最小可用的 spec 治理结构可以包括：
AGENTS.md
spec/
README.md
governance/
planned/
implemented/
archived/
SPEC_TEMPLATE.md
其中：
AGENTS.md用于记录 AI Agent 必须遵守的项目规则；governance/存放长期有效的工程规则；planned/存放已设计但未落地的方案；implemented/存放已实现并有代码锚点的规范；archived/存放废弃、搁置或历史方案；SPEC_TEMPLATE.md统一单条 spec 的描述格式。
活 spec 的核心不在于文档写得多完整，而在于它能回答三个问题：
- 这条 spec 当前处于什么状态？
- 它对应哪些代码、测试、issue 和 PR？
- 代码变更后，spec 状态是否同步更新？
没有状态、归属和验收动作的文档，只是静态记录；具备这些机制的 spec，才是团队和 AI 共同使用的工程账本。
10. GitHub Workflow：将 AI 产出纳入确定性门禁
大型项目不能依赖“最好跑一下测试”这种弱约束。对于 AI Coding，质量检查必须从建议变成强制门禁。GitHub Workflow 可以将 lint、测试、安全扫描和构建流程自动化，并与 Branch Protection 结合，形成主干合并前的 required check。
一个最小可用的团队质量管线如下：
issue -> branch -> commit -> pull request -> workflow -> human review -> merge
最小 workflow 可以只包含 lint 和测试：
on:
push:
branches: [main]
pull_request:
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.11"
- run: pip install -e ".[dev]"
- run: ruff check src tests
- run: pytest -q
这类 workflow 的核心价值不在 YAML 本身，而在于：
- 自动触发；
- 环境一致；
- 结果可见；
- 红灯阻止合并；
- 可逐步扩展。
AI Review 可以作为辅助工具，但不能取代确定性 workflow。因为 AI Review 可能遗漏问题，标准也可能随模型版本漂移。主干门禁必须建立在可复现、可审计、可强制执行的检查之上。
11. 质量飞轮：生成、验证、修正与人工裁决
大型项目中的 AI Coding 应当被放入一个持续运转的质量飞轮中：
AI 生成
-> Spec / 特征测试 / Lint / Pytest / PR 模板验证
-> 失败信息结构化回喂给 AI
-> AI 最小修正
-> 人工最终裁决
这一飞轮的关键在于，每一步都必须产生可验证对象：
- 架构梳理让 AI 获得正确上下文；
- 特征测试锁住遗留行为；
- 小步重构控制 diff 和回退面；
- Git 保证变更可追溯；
- 活 spec 保证知识持续对账；
- GitHub Workflow 保证主干门禁自动执行；
- 人工 Review 保证业务语义和架构方向正确。
AI 的可信度并不来自它声称“已经完成”，而来自它的产出被放进了 spec、测试、Git、Workflow、PR 和人工 Review 共同组成的工程系统。
12. 人的角色变化：从实现者到治理者
在 AI Coding 时代，人的角色并不是被替代，而是发生迁移。
传统开发者主要承担代码实现工作；而在大型项目中，人将越来越多地承担以下职责：
- 定义系统边界；
- 制定验收标准；
- 审核 AI 生成的 spec；
- 审核 AI 生成的特征测试；
- 裁决业务语义；
- 判断架构演进方向；
- 控制主干合并权限。
AI 则承担大量重复性、机械性和可验证的工作，例如读代码、生成结构摘要、补测试、抽函数、修复 lint、根据失败日志做最小修复等。
这种分工变化意味着，未来高质量工程师的核心能力不仅是写代码，更是定义边界、设计验证系统和维护工程秩序。
13. 结论
大型项目中 AI Coding 的价值不应被简单理解为“更快地产生代码”。如果没有上下文工程、特征测试、Git 管理、活 spec 和 CI 门禁，AI 的高产出反而会放大系统风险。
更合理的路径是建立一套以工程治理为核心的 AI Coding 方法论：
先理解，再锁住；
先小步，再验证；
先入 Git，再进主干；
先过 Workflow，再由人裁决。
在这一框架下，AI 不再是一个不受约束的代码生成器，而是被纳入软件工程质量体系中的高效执行单元。它可以显著降低遗留代码理解成本，提高测试补齐效率，加速安全重构过程，并帮助团队形成更稳定的知识账本。
最终，大型项目能否安全使用 AI Coding，并不取决于模型是否足够强，而取决于团队是否建立了足够可靠的治理机制。只有当 AI 的每一步产出都可验证、可追踪、可回退时，AI Coding 才能真正从个人效率工具，升级为团队级工程能力。
附录：大型项目 AI Coding 实践清单
A. 遗留代码分析清单
请只读代码，不要修改任何文件。
请输出：
1. Public API 与入口清单；
2. 职责板块划分；
3. 状态地图；
4. 多套实现路径；
5. 可疑行为清单；
6. 第一批应补充的特征测试。
要求：
先描述现状，不要给重构方案；
不要顺手修 bug；
不要修改业务代码。
B. 特征测试生成清单
请基于当前行为生成特征测试。
要求：
1. 测试锁住当前行为，而不是理想行为；
2. 可疑行为必须原样锁住；
3. 数据库、缓存、全局变量和配置必须隔离；
4. 每条测试说明锁住了哪条现状；
5. 不要修改业务代码。
C. 安全重构执行清单
现在特征测试已经全绿，请执行一次小步安全重构。
约束：
1. 保留 public API；
2. 保留返回结构；
3. 一次只重构一个职责块；
4. 每完成一步运行全部特征测试；
5. 测试失败时先解释行为变化；
6. 不要顺手修 bug；
7. 不要新增功能。
D. GitHub Workflow 管线清单
请按当前 issue 工作：
1. 复述目标；
2. 明确验收标准；
3. 明确不要动的范围；
4. 创建只解决本 issue 的小步修改；
5. 提交信息包含 Refs #<issue号>；
6. PR 正文包含 Closes #<issue号>；
7. 运行本地等价检查；
8. 如果失败，只根据失败信息做最小修复；
9. 不要自动合并；
10. 不要扩大 scope。
