主题
企业工作流与大代码库
一句话：企业级 AI Coding 不是让模型多写代码，而是把模型嵌进已有的研发流程——AI 负责执行效率，流程负责质量，人负责方向与风险。换来的是吞吐，代价是每个环节都多一次确认、一次验证。
为什么需要
把需求原样丢给 AI，通常得到三种结果：代码能跑但没人敢合；改动看似正确，上线后崩在另一个模块；或者一次会话烧掉大量 token，产出却只有几十行。原因不在模型能力，而在流程缺位：没有验收标准，AI 不知道"做完"是什么；没有影响面分析，AI 不知道改动的边界在哪；没有回归门禁，AI 的自信输出就成了唯一质量依据。
企业里真正的约束是三件事——代码库大到装不进上下文、改动的影响面跨模块跨服务、出错要回滚并且要有人负责。这三个约束决定了 AI 只能承担执行，判断必须留在流程和人身上。
核心机制
需求到交付的七个环节
每个环节都要回答三个问题：AI 在这里能加速什么、人必须决定什么、留下什么可验收的产出物。
| 环节 | AI 介入点 | 人的决策点 | 产出物 |
|---|---|---|---|
| 需求评审 | 完整性检查、边缘场景补全、可行性初评 | 业务价值、优先级、是否立项 | 需求说明 + 范围外清单 |
| 技术方案 | 生成 2–3 个候选方案、选型对比、接口与数据模型草案 | 架构决策、与现有系统兼容性、非功能指标 | 方案文档 + 被否方案的理由 |
| SDD 规格 | 起草规格、补全验收标准、拆任务 | 验收标准签字、任务粒度 | 规格 + 任务清单 |
| 编码 | 按任务实现、同步写单测、自验证 | 抽查关键路径、纠正架构偏离 | 可运行的增量提交 |
| 自测 | 跑测试、生成报告、静态扫描、性能基准 | 对照验收标准、确认边界条件 | 测试报告 + 未覆盖项 |
| Code Review | 风格/安全/性能初筛、给出修复建议 | 业务逻辑、架构合理性、最终 Approve | 评审记录 + 合入决定 |
| 测试上线 | 生成用例、发布说明、回滚方案 | 上线决策、灰度比例、回滚触发条件 | 发布单 + 回滚预案 |
箭头方向说明了一件事：AI 的产出永远是下一环节的输入，而不是终点。每个环节的人都有一票否决权，所以质量门禁是串联的，任何一环跳过，后面环节的 AI 都会在错误前提上继续放大。反过来说，规格和验收标准写得越具体，后面五步需要人介入的频率越低。
六类场景：AI 介入度由历史包袱决定
| 场景 | AI 介入度（经验值） | AI 怎么用 | 人怎么把关 | 最大风险 |
|---|---|---|---|---|
| 新模块 0→1 | 高 | 方案对比、脚手架、按接口契约并行编码 | 架构与技术选型 | 过度设计，加不需要的抽象层 |
| 老功能兼容升级 | 中 | 先读代码出理解报告，再给影响面清单 | 兼容性与历史原因 | 把"为兼容而留"的代码当冗余删掉 |
| 业务迭代/需求变更 | 高 | 变更影响报告、只改必要部分、识别回归范围 | 需求理解与影响面确认 | 规格与代码脱节 |
| 线上 Bug 修复 | 中 | 生成最小复现、日志归因、按概率排序假设 | 根因确认与紧急度取舍 | 治标不治本，问题复发 |
| 大型重构/微服务拆分 | 中 | 依赖与调用关系梳理、分步迁移计划 | 迁移节奏与每步验收 | 范围蔓延，顺便改的越来越多 |
| 跨语言/框架迁移 | 中高 | 语法翻译、行为测试生成、性能对比 | 惯用法与设计模式适配 | 语义差异，测试覆盖不到的行为漂移 |
- 老功能升级：接口做版本化，新旧逻辑双写一段时间，再按流量灰度切换。
- 新模块：接口契约先行，前后端按同一份契约并行编码，再合并联调。
- 跨语言迁移：先补特征测试锁住现有行为，迁移后先比行为，再比性能。
规律很直接：AI 介入度和代码库的历史包袱成反比，而不是和任务难度成正比。历史越少，AI 越能自由发挥；历史越多，AI 的第一项工作必须是理解而不是修改。老系统里最高频的事故，是 AI 把一段看似冗余的兼容代码"优化"掉——它没有能力从代码本身推断出"这是为了绕开某个老系统的 bug"。
大代码库的三个矛盾
| 矛盾 | 表现 | 应对方向 |
|---|---|---|
| 窗口有限 vs 代码无限 | 十万行项目塞不进上下文，塞进了也贵 | 检索优先，只给相关代码 |
| 信息全 vs 注意力散 | 上下文越长，中段信息越容易被忽略 | 最小够用，按任务裁剪 |
| 改一处 vs 影响一片 | 改一个函数，十个调用方受影响 | 先做影响面分析，再动手 |
第二条最反直觉：上下文不是越多越好。把整个模块粘进去，模型的注意力会被大量无关代码稀释，关键约束反而更容易漏。所以判断标准不是"给够信息"，而是"给到的每段代码都能回答'为什么需要它'"。
影响面分析：先定范围，再写代码
影响面分析不是让 AI 凭记忆猜，而是让它用检索工具把调用链、数据表、消息主题、测试文件逐项列出来，人只负责补它没找到的部分。两者的分工不能颠倒：AI 擅长穷举，人擅长判断哪些"看起来无关"的东西其实有关——跨仓库调用、定时任务、配置中心、外部消费方，这几类最容易漏。
闭环的关键在第一个判断节点：影响面没确认就进入编码，后面的测试只能证明"改的这处是对的"，证明不了"没改坏别处"。而确认动作放在人身上，是因为 AI 的影响面清单天然偏向它检索到的内容，漏掉的恰恰是它没想到要搜的。
五种上下文管理策略
| 策略 | 做什么 | 代价 |
|---|---|---|
| 按需加载 | 先检索，只把命中的片段和签名读进上下文 | 需要可靠的检索入口，冷启动慢 |
| 架构图 | 维护模块边界、依赖方向、关键数据流 | 图会过期，必须随代码更新 |
| 代码检索 | 按符号/调用关系定位，而非按文件名猜 | 命名不规范时召回差 |
| 增量修改 | 一次只改一个任务，改完验证再进下一个 | 任务拆得不好会频繁切换 |
| 分层摘要 | 目录级摘要 + 文件级摘要 + 原文，逐层下钻 | 摘要本身会丢细节，关键约束要保留原文 |
这五种不是并列选项，而是有顺序的：架构图决定"去哪找"，检索决定"找到什么"，分层摘要决定"读多深"，按需加载控制"进多少"，增量修改控制"改多少"。跳过前面的层直接加载原文，成本最高、效果最差。
配合的七步工作流是：明确验收标准 → 影响面分析 → 定位相关文件 → 拆任务 → 逐任务实现与测试 → 集成跑全量 → 提交评审。第三步之后不要再扩大范围，第四步之后不要再改需求，否则前面的分析全部作废。
工具能力与成本
选工具看四个维度，不看宣传：上下文窗口决定单次能装多少；索引方式决定检索召回（本地符号索引 vs 向量检索 vs 两者结合）；指令文件（如 AGENTS.md）决定项目约定能否自动注入；权限模型决定它能读哪些目录、能不能执行命令。窗口只是上限，有效上下文由检索、压缩与注意力共同决定，长上下文普遍存在中段遗忘。具体窗口大小和计费以各工具官方文档为准，不同版本差异很大。
成本通常是输入 token 占大头（单次输入乘以请求次数），但不是绝对：长生成、高输出单价模型、推理模型都要单独核算输出成本。所以省钱的手段和提质量的手段常常是同一个：先检索再加载。实践上，检索和影响面分析用便宜的小模型，核心编码用强模型；项目约定写进指令文件让它每次自动带上，而不是每次粘贴；一个任务结束就重开会话，不要把无关历史带进下一轮。
实战场景
场景：百万行仓库里，AI 第一周就废了
怎么死：接入第一周，Agent 在支付域的产出连续被打回三类问题：引用了已下线两年的 PayClientV1；把改动写进 order/legacy/ 里那个和现役模块同名的旧目录；影响面清单列了 14 个调用方，实际漏了 3 个、多列 6 个不相关的。到第二周，工程师发现自己读 AI 产出、纠错的时间超过了直接写——不是因为模型不会写代码，而是它每次都从错误的落点开始写。团队当时的第一反应是“换个更强的模型”，实测一周后错误几乎没变——问题不在模型质量，在大库的索引与检索质量：同名旧模块在检索里得分更高（文档更全），废弃 API 在语料里出现频次更高（历史代码引用多）。
根因拆开是三条：仓库没有可信的“去哪找”入口；检索只做语义相似，不做符号与调用关系确认；项目约定只在人脑和 wiki 里，AI 每轮都得重新猜。
修法一：仓库地图（模块职责卡）。每个模块一份 20–40 行的卡（长度是经验值，需按团队校准，超出就拆成子模块卡），只写机器检索需要的字段：职责边界、公开接口、owner、依赖方向（谁能调谁）、禁改区、已废弃及替代者。关键约束是引用而不是复制——卡片链接到源文件与测试命令，避免第二真相源过期。
修法二：代码搜索工具优先于向量检索。改代码前必须先有一次符号级/调用图级的落点确认（grep、LSP、git log -- <path>），向量检索只承担“用自然语言描述→找到候选目录”这一步，命中结果一律不当落点用。对应正文五种策略的顺序：架构图决定去哪找，检索决定找到什么，摘要决定读多深，按需加载决定进多少。
修法三：AGENTS.md 分层放置，根级放全局，模块级放本地约定，废弃模块只声明边界：
text
/AGENTS.md # 根：技术栈、构建与测试命令、全局红线、模块地图入口
/pay/AGENTS.md # 模块：接口版本规则、禁用 API 清单、本模块回归命令
/pay/legacy-order/AGENTS.md # 只读声明：deprecated，替代者 xxx，改动一律走新模块再补一道机器闸：把“禁用 API”变成 CI 里的 lint 规则而不是一句提示词——AGENTS.md 是提示不是权限，AI 写了 PayClientV1 就让流水线红。错误暴露在 CI 里是一次构建，暴露在 review 里是一轮人来回讨论。落地后需要人纠正的引用类问题明显下降（内部按“回退原因分类表”周度统计，绝对值依仓库规模而定，经验值，需按团队校准）。
场景：monorepo 的跨模块改动，让 AI 一次改 12 个文件是错的
怎么死：一个“给订单加一种履约方式”的需求，牵动订单、库存、风控、结算四个模块。图省事让 AI 一次改完，产出 12 个文件、约 900 行 diff，接着连跑三轮全量回归三轮红，每轮失败原因还不一样：第一轮是契约字段名不一致，第二轮是某模块沿用了旧枚举，第三轮修 A 坏了 B。最后一律回退重写，代价是三次全量回归的时间加一次推翻。根因不是模型不行，而是它同时在维护 12 处未经确认的契约假设，任何一处对不上都要回改其余 11 处，改动规模越大这个乘法越贵——正是正文“改一处 vs 影响一片”那条矛盾的实操形态。
改成契约先行：接口先定、测试先红、逐模块跟进，一次只有一个可变单元。
| 步 | 谁主导 | 产出 | 门禁 |
|---|---|---|---|
| 1 定契约 | 人定接口、数据结构、错误码；AI 起草候选 | 接口层 diff + 契约测试 | 接口评审签字，此后视为冻结 |
| 2 先红 | AI | 针对新契约的失败测试（实现未动） | 测试必须红在契约上，不是红在导入错误 |
| 3 逐模块 | AI，一次一个模块 | 该模块实现 + 模块级回归 | 单模块绿即 commit，不跨模块攒改动 |
| 4 集成 | AI 跑，人判 | 全量结果 + 影响面清单四类补查（跨仓库调用、定时与异步消费、配置开关、外部对接方） | 合并前全绿 |
真实节奏：同一个需求，第 1 步要花掉约半天（含一次评审），看着比一次改完慢；第 3 步每个模块一到两个会话，改完即绿、失败即回退一个 commit，第 4 步通常一次全量就过。慢在开头，快在不用推倒——而且第 1 步的评审记录顺手补上了规格与代码的一致性（见 03-SDD规格驱动）。两条附带纪律：旧接口在契约层保留兼容转发，删旧路径单独提需求；过程中不许“顺手重构”，那是另一条流水线的账（见 06-代码重构与调试）。
案例：多 Agent 并行开发，最后互相覆盖
现象：同一个 monorepo 上开三个 Agent 做同一需求的三个部分，两小时后合并：A 把 B 刚抽出的公共模块签名改了回去，C 的格式化 diff 覆盖了 A 的业务改动。Git 层面几乎没冲突——它们在不同分支改不同文件，真正的冲突在语义层。合并出来的分支编译通过、测试全绿，但行为是错的：测试也是 AI 写的，锁的是同一份误解。
修法一：按目录所有权切分，且落到工具配置而不是提示词。一个 Agent 一个可写目录集，其余只读：
yaml
agents:
- name: pay-core
write: ["pay/core/**", "pay/tests/**"]
- name: risk-adapter
write: ["risk/adapter/**", "risk/adapter/tests/**"]
frozen: ["pay/shared/dto/**", "common/util/**", "AGENTS.md", "**/uv.lock"]公共部分（共享 DTO、通用工具、根指令文件、锁文件）设冻结区：只有 owner 能写，改动先单独合入主干，再让各并行分支重新拉取。冻结不是建议，是工具侧拒绝写入。
修法二：合并仲裁规则。按顺序合而不是并行合，后合者负责 rebase 并跑受影响模块的回归；判定冲突看函数不看文件——两个 Agent 的 diff 触碰同一函数即判冲突，交人裁决，禁止“自动取较新版本”这种默认策略。回归测试的基线以主干为准，分支自带的断言不许反过来改被测代码。
修法三：并行之前先做一次契约冻结，直接复用上一场景的第 1 步。接口没定就开三个并行，并行执行的正是“未确认的假设”，冲突只是把错误同时推进了三个方向。并行的上限按可独立回归的模块数定，而不是按任务数或人力定：跨模块强耦合的需求，两个以上并行净收益通常为负（经验值，需按团队校准）。
这三条合起来回答的是同一个问题：AI 并行的瓶颈不在算力，在“谁有权改哪一段”。目录所有权划清写权限，契约冻结划清语义边界，合并仲裁划清冲突责任——顺序反过来做，就会回到那个编译通过、测试全绿但行为错误的分支。平台侧的权限落地方式见 09-工具链与MCP平台。
最小上手
前提：代码库可被工具检索，项目根目录已有 AGENTS.md（技术栈、目录结构、构建与测试命令）。把下面模板复制到会话开头，先只让它做前两段。
text
任务：在 {模块} 中实现 {需求}，验收标准：{可观测的行为}。
范围外：{明确不做的部分}。
第一步只做影响面分析，不要写代码：
1. 列出该函数/类的所有调用方（文件:行号），区分直接与间接
2. 指出接口或行为变化会影响哪些调用方
3. 列出相关的数据表、缓存键、消息主题、配置项
4. 列出需要更新或新增的测试
5. 给出风险等级与建议修改顺序
约束：
- 检索后只引用必要的文件，单次不超过 5 个
- 不确定的历史原因先标注「待确认」，不要自行删除
- 输出影响面清单后停下，等我确认
验证命令：{单测命令} / {集成测试命令} / {静态检查命令}确认清单后，再按任务逐条让它实现，每条实现完立刻跑验证命令。若一次会话接近上下文上限，先让它输出"当前进度 + 已确认结论"，把结论带进新会话，而不是继续硬塞。
生产动作
- 评审门禁：MR 描述里必须附影响面清单和验证命令的输出；规格与代码的一致性检查进 CI；支付、权限、数据迁移类改动强制两人审，AI 的初筛意见与人的意见分开记录，避免"AI 说没问题"成为合入依据。
- 影响面确认：AI 清单出来后，人固定补查四类——跨仓库调用、定时任务与异步消费、配置与开关、外部对接方。这四类占漏报的多数。
- 增量提交：一个任务一个提交，先骨架后填充；"顺手重构"单独提需求，不混进功能提交，否则回滚时无法只回退一半。
- 回归验证：受影响模块的测试必跑，全量测试在合并前跑；数据迁移和微服务拆分做新旧双跑对比；灰度开关和回滚预案必须先于代码上线，而不是上线后再补。
- 上下文纪律：会话开始时限定目录和任务，接近窗口上限就重开；长期约定写进指令文件，不靠每次粘贴。
- 排障路径：AI 给出的修改导致别处失败 → 回看影响面清单缺了哪一类 → 补齐后重跑受影响测试 → 把该类遗漏写进项目的检查清单。
边界
- 流程会变重：七步里每步都有人工确认，短期交付速度一定下降。收益来自返工减少，如果团队本来返工就少、代码库也小，这套流程是净负担。
- 影响面分析不是保证：它依赖检索召回，动态调用、反射、跨仓库依赖都可能漏。把它当"待验证的假设"，不要当"已确认的结论"。
- 无测试的遗留系统最危险：AI 会给出看起来很完整的影响面清单，实际遗漏更多，此时直接改比不用 AI 风险更大。正确顺序是先补行为测试锁定现状。
- 新模块容易过度设计：AI 介入度最高的场景恰恰最容易加无用抽象，规格里必须写清"不做什么"。
- 工具对比会过期：窗口大小、索引能力、计费都在快速变化，选型以当期官方文档和自己的小规模实测为准，不看二手评测。
- 常见误区：把上下文塞满当充分；把小模型的分析结论直接当决策；让 AI 同时做影响面分析和编码，导致它先有结论再补理由。
讲清楚
企业里用 AI 写代码，瓶颈不是能不能写出来，而是写出来的东西敢不敢合。所以要把它嵌进需求评审、方案、规格、编码、自测、评审、上线七步：AI 出执行结果，人做判断。六类场景的介入度由历史包袱决定：新模块多放手，老系统先理解再动手，线上故障先定根因再最小修复，大型重构 AI 做计划但人控节奏。大代码库的三个矛盾是窗口装不下、注意力会稀释、改一处影响一片，做法是先做影响面分析定范围，再用架构图、检索、分层摘要、按需加载、增量修改逐层收窄上下文。记住两句：先分析再编码，上下文最小够用比最大覆盖更重要。
适用：2026 年企业级 AI Coding 实践 | 初稿 2026-10