干AI工程交付这两年我越来越确定一件事AI写代码的能力增长很快但工程流交付能不能稳住靠的是文档驱动这套“慢功夫”。很多团队一上来就让AI Agent写接口、写服务结果需求一改文档没跟上接口、数据库、前端模型全乱成一锅粥。这篇是“AI开发文档驱动实践”系列第二篇专门聊工程流交付环节里如何把文档变成流程的源头和验收的依据。这里说的文档不是那种写完了就没人看的Word而是从需求到接口、从数据模型到部署配置都能被机器读取、被流程校验的“活文档”。如果你正在做AI应用开发、产品设计、前后端联调或者负责模型服务的部署交付这篇文章应该能帮你把交付链路理得更顺。AI生成能力越强越需要一个稳定的、可信的参照系文档驱动就是这个参照系。1. 为什么工程流交付需要文档驱动1.1 从“一人写码”到“多人协作”的痛点一个人用AI写代码时所有上下文都在脑子里文档可有可无。但团队协作完全不同。我之前带过一个智能客服项目算法、后端、前端、测试、SRE五个角色同时进场一开始效率看起来很高AI半小时就能生成一个接口服务。但第三天问题就来了算法团队改了返回结构把字段名从customer_id改成了custId后端同步改了前端却还在解析旧字段测试脚本也跟着过期联调现场一片混乱。这个例子特别典型。问题不在于AI写得不好而在于团队里每个人的“上下文”不一样口头对齐的信息过了半天就失真。AI只会让代码产出速度变快但沟通速度没变快如果没有一份所有人共用的事实基准错误也会被加速放大。文档驱动在这里不是流程负担而是团队信息的“公共内存”让跨角色协作从“猜别人在想什么”变成“看同一份契约”。1.2 文档驱动不是“写文档”而是“让文档成为可执行契约”很多人听到文档驱动第一反应是“又要写一堆没人看的需求说明书”。其实不是。文档驱动开发的核心是先写文档让文档描述系统应有的行为、接口和数据模型然后基于文档生成代码、测试、部署配置。文档是源头代码是产物文档改了整个交付链跟着变。举个例子装修房子时施工队不会靠口头聊天来贴瓷砖。得先有设计图水电工按图改水电木工按图做柜子厨房和卫生间改了布局必须回到图纸上改再通知所有人。否则瓦工按旧图贴砖橱柜按新图下单最终一定返工。AI编程也一样。AI Agent写后端和前端时如果它们之间没有一张“施工图”两个模型各写各的接口对不上只是时间问题。下面用表格对比一下传统开发和文档驱动在几个关键环节的差异环节传统开发文档驱动起点白板、口头对齐、临时代码结构化文档、机器可读契约代码生成纯手写或AI自由发挥基于文档生成AI负责填充逻辑变更控制代码评审为主文档滞后文档评审先行联动CI校验测试依据测试人员的个人经验契约测试自动生成覆盖接口行为文档质量容易漂移几乎没人看文档就是验收依据不更新就报错表格列出来之后文档驱动的价值就很直白了它把“写文档”从成本项变成了控制项让文档不再是项目结束后的补作业而是每次变更的第一动作。1.3 为什么AI工程场景下文档驱动更紧急大模型生成代码有一个特点非确定性。同一个需求同一个模型你问它两次可能给你两套不同的接口命名、不同的字段结构甚至不同的业务逻辑。这在一人项目里还能接受但在工程流交付里就是灾难。文档驱动等于是给AI的随机性套了一个边界把关键决策放到文档里写死模型只能在这个边界内发挥。另一个原因是上下文窗口。AI Agent要执行的任务越多记录越容易丢。如果你让它长长地写一个服务它写到后面很可能会忘记前面已经定义好的字段。但是如果你把OpenAPI契约文件固定放在项目里在Prompt里明确告诉它“所有接口和数据结构以docs/api/openapi.yaml为准”它的跑偏概率会明显下降。实践下来这个动作比任何“提示词技巧”都稳。2. 核心拆解AI开发中的文档驱动闭环2.1 需求文档到技术方案的转化文档驱动的起点是需求但不是那种“你看我这个想法怎么样”的需求而是可验证的需求条目。我们内部习惯用一套模板用户故事、验收标准、优先级、关联接口。一条需求如果连验收标准都写不清楚那后续AI实现和测试验收都无从谈起。举个例子一条需求可以长这样用户故事作为客服管理员我希望按标签筛选会话记录以便快速定位问题会话。验收标准标签筛选在3秒内返回支持多选标签空结果显示友好提示。关联接口GET /sessions?tagstag1,tag2需求确认后技术方案要做的是把它翻译成系统语言需要哪些接口、每个接口的请求响应结构是什么、涉及哪些数据表、有没有缓存和限流要求。这个阶段最能体现文档驱动的价值因为你被迫在写代码之前把所有分歧摆到桌面上。我们常说要“把错误留在文档阶段不要留到代码阶段”因为改文档的成本远低于改代码和重新部署的成本。2.2 接口契约与数据模型的“单一事实源”工程流交付里最容易被AI写乱的就是接口。前后端各写一份文档甚至各自按照习惯命名联调必然出问题。我们的做法是整个服务只允许存在一份机器可读的接口契约所有代码生成、测试、Mock、文档展示都从这份契约出发它就是“单一事实源”。REST接口通常用OpenAPI规范来描述。下面是一个简化但足够说明问题的例子openapi: 3.0.3 info: title: Customer Service API version: 1.0.0 paths: /sessions: get: summary: 查询会话列表 parameters: - name: tags in: query schema: type: array items: type: string responses: 200: description: 返回会话列表 content: application/json: schema: type: array items: $ref: #/components/schemas/Session components: schemas: Session: type: object required: [id, customer_id, status] properties: id: type: string customer_id: type: string status: type: string enum: [open, closed, pending]这份文件同时能做到三件事人能读机器能解析AI生成代码时能被当作准确的约束。数据模型也可以从这里的components/schemas里引用数据字典和接口定义保持在同一个文件里避免字段命名出现多种风格。提示接口契约文件不要放在公司Wiki里Wiki无法做版本管理也无法接入CI校验。把契约文件放进代码仓库才能让文档变更走评审和流水线。2.3 从文档到代码的自动生成与校验有了契约文件下一步就是让文档直接生成代码。OpenAPI Generator是目前比较成熟的选择它支持Java、Python、TypeScript、Go等主流语言也能生成客户端和服务端骨架。生成命令大致是这样openapi-generator-cli generate -i docs/api/openapi.yaml -g typescript-axios -o packages/api-client openapi-generator-cli generate -i docs/api/openapi.yaml -g python-fastapi -o services/api-server第一次看到生成结果时你可能会觉得“这不就是我让AI写的吗”区别在于这份生成代码和文档百分百一致不会出现AI自由发挥的字段。生成出来的客户端SDK、类型定义、服务端路由骨架全部受契约约束业务逻辑是后面填进去的。更重要的是校验。光有生成代码还不够还要用契约测试验证服务行为。Dredd和Schemathesis是两种思路Dredd根据OpenAPI里的示例逐个请求检查响应是否符合schemaSchemathesis则用属性测试的方式自动构造大量边界请求能发现手工测试不容易覆盖的漏洞。对AI生成的服务实现来说契约测试是一张可靠的安全网因为大模型最容易犯的错误就是字段名对不上、枚举值多写或漏写、响应结构缺字段这些恰好都是契约测试能抓住的问题。2.4 文档变更驱动的交付流水线文档驱动闭环的最后一步是让文档变更本身成为流水线的触发源。我们采用docs-as-code的方式把文档和代码放在同一个仓库里任何接口调整都从改文档开始。一旦文档发生变更CI自动执行一整套动作格式检查、生成代码、跑契约测试、构建镜像、部署到测试环境。这样设计的意图很明确把“人自觉维护文档”变成“流程强制文档先行”。如果谁直接改了代码而没改文档CI里的生成结果对比会显示差异代码评审的时候就过不去。这不是为了卡人而是防止团队在AI加速之后把代码库变成一堆无法追溯的“一次性产物”。流水线跑起来后文档的地位就变了。它不是一个静态说明文件而是和代码一样需要评审、需要版本管理、需要测试的“交付物”。谁改了接口谁就要对文档负责文档不更新服务就不能继续往前走。3. 工程流交付实操从零搭建一套可落地的流水线3.1 文档结构设计一份能驱动交付的文档长什么样实务中文档驱动一开始别求大而全我见过很多项目想一步到位搭了一套复杂的文档体系结果团队根本维护不动没两周就废弃了。先保证最小的文档集能用起来再逐步完善。我们推荐从这样的目录开始docs/ 01-requirements/ REQ-001.md 02-design/ ADR-001.md 03-api/ openapi.yaml 04-data/ schema.json 05-architecture/ overview.md01-requirements需求条目和验收标准给产品、开发、测试共同使用。02-design架构决策记录记录关键技术选型和取舍给后续维护者看到“为什么这么做”。03-api接口契约文件机器会读它前后端也以它为准。04-data数据字典、JSON Schema数据库建模和模型校验的基础。05-architecture系统概览、部署架构给SRE和新人快速理解全貌。最小可用文档集其实只要四类接口契约、数据Schema、验收标准、架构概览。其他内容等团队适应了再慢慢补。文档过多过散和没有文档一样都会成为交付障碍。3.2 文档→代码生成器的选型与配置生成器选型要按场景来不要看见什么都用场景推荐工具说明REST接口OpenAPI Generator生态成熟多语言支持事件驱动消息AsyncAPI Generator管理Topic和消息Schema内部RPCprotoc bufgRPC场景效率高数据模型json-schema-to-pydantic 等从JSON Schema生成类型定义选型稳定下来后配置文件要提交到仓库里。OpenAPI Generator的配置文件openapitools.json长这样{ $schema: ./node_modules/openapitools/openapi-generator-cli/config.schema.json, generator-cli: { version: 7.6.0, generators: { client-ts: { generatorName: typescript-axios, inputSpec: docs/api/openapi.yaml, output: packages/api-client }, server-py: { generatorName: python-fastapi, inputSpec: docs/api/openapi.yaml, output: services/api-server } } } }这样做的最大好处是无论谁跑生成命令产出的代码都一致。AI Agent也好本地开发者也好CI也好使用的是同一套工具和配置杜绝“我机器上能跑”的尴尬。生成出的代码要不要提交进仓库我们建议提交。尤其是客户端SDK提交后前端直接引用依赖关系清晰如果真有人手改了SDK评审的时候也能在diff里发现。3.3 文档变更驱动的CI/CD流程CI/CD里最关键的配置是“文档路径触发”。下面是一段简化但可以直接参考的GitHub Actions配置name: api-contract on: pull_request: paths: - docs/api/openapi.yaml - docs/data/schema.json jobs: validate: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 - run: npx redocly/cli lint docs/api/openapi.yaml - run: npx openapitools/openapi-generator-cli generate - run: npm test - run: npm run contract-test触发路径只聚焦在契约文档上意味着只有接口和数据模型变更时才跑这一整套操作普通业务代码改动不会被误伤。lint那一步很值得做它能在早期发现OpenAPI语法错误、重复字段、循环依赖等低级问题免得生成器跑到一半报错。再往后可以接上更完整的交付链文档变更合并到主分支后自动生成新的Mock服务更新测试环境的API文档页面并给前端和测试推送变更通知。这样文档就真正活在了交付流程里而不是仓库里的一个装饰品。3.4 质量门禁文档与实现的偏差检测有了生成和契约测试下一步要设置“硬卡点”。我们常用的偏差检测工具是Schemathesis它会根据OpenAPI文件自动生成大量测试请求覆盖正常、异常、边界情况。命令行很简单schemathesis run docs/api/openapi.yaml --base-urlhttp://localhost:8000 --checks all在流水线里我们会给这个步骤设置“必须全绿”的规则。可以设定关键接口必须100%覆盖整体接口覆盖率不低于80%达不到就让流水线失败。这个动作把标准从“代码能跑”提升到了“行为符合文档”很多AI生成代码的神秘bug就是在这里被拦住的。另外OpenAPI还有个兼容性校验要加进去。用openapi-diff这类工具对比新旧版本一旦发现新增必填字段、删除枚举值等breaking changeCI应该立刻提示要求产品和技术负责人评审后再继续。整个交付流程因此有了明确的升级节奏不会出现“后端悄悄改了字段让所有客户端崩掉”的事故。4. 常见问题与排查技巧实录4.1 文档漂移怎么治文档漂移几乎每个团队都会遇到症状是文档还在写旧逻辑代码已经改成新逻辑了。要治它靠觉悟不行得靠机制。第一层机制是把文档变更和代码变更绑在同一个MR里谁改代码谁就要同步文档否则CI直接fail。第二层是让结构化契约文档接受机器校验OpenAPI文件格式错了、字段不一致了自动报错。第三层是我后来加上的用LLM做非结构化文档的语义检测。代码和文档都变化后让AI读一遍代码再读一遍文档判断两者描述的行为是否一致。当然这个只能作为人工评审的辅助不能当成绝对依据但它能快速标记可疑点省不少时间。实操心得不要在公司Wiki里维护接口文档Wiki没有版本管理也没有Codeowner机制。只有把文档放进代码仓库才能被CI、评审、权限管理兜住。4.2 生成代码不敢用怎么办初期团队对自动生成代码容易有抵触担心质量不可控。我们的做法不是“全盘生成”而是先划一个隔离层。比如OpenAPI Generator生成的代码单独放在packages/api-client和services/api-server里业务逻辑写在独立的实现目录。生成代码不手改需要调整就改模板或改契约避免下一次生成时被覆盖。另外试点范围很重要。先挑一个内部服务、两个基础接口跑通整条链路让团队看到契约测试帮忙拦下了多少个低级错误再逐渐扩大范围。实测下来把文档给到AI编程助手当上下文之后生成的业务代码质量明显提升因为模型不用猜接口和字段了它只要专注实现逻辑就好。这个对比很容易说服人。4.3 团队不配合文档先行怎么办很多时候不是团队懒而是他们觉得写文档没回报。所以要让“文档先行”这件事立刻带来好处。最容易见效的一招是把OpenAPI文件接入Mock服务后端接口还没写完前端就能根据文档跑假数据联调。测试也能从文档里自动生成测试用例减少手工造数据的痛苦。我之前在一个项目里只试点了一个服务两周后前端同事开始主动问“下一版接口文档什么时候出”。因为对他们来说文档不再是一堆文字而是能立刻生成可用Mock和SDK的东西省了大量等接口的时间。当团队意识到文档能减少等待、减少返工时就不需要你反复催了。4.4 常见问题速查表现象可能原因处理办法联调时接口字段对不上文档或生成产物没更新重新生成代码并跑契约测试生成代码覆盖了手写代码输出目录配置重叠把业务逻辑放到独立目录生成目录单独存放AC过但服务行为不符合示例和边界用例覆盖不足在OpenAPI里补充响应示例和约束条件AI不遵守枚举值上下文里没给完整枚举将枚举定义作为Prompt固定片段传入文档评审拖慢交付文档太厚重、过程繁琐拆分“契约文档”和“说明文档”契约优先评审遇到问题先看表大多数情况都能对应上。如果发现表中没有的场景建议从“文档和代码是否一致”这个根因开始查八成问题出在这里。5. 我的实操经验与后续扩展5.1 从落地项目里学到的三件事第一别想着从零完美设计文档。老项目可以先从现有代码反向生成第一版OpenAPI。哪怕字段不全先跑通一套契约测试让团队看到收益再慢慢把描述补完整。反向生成的文档也许丑但它让现状可见这是改进的前提。第二最小闭环比全套工具重要。文档驱动刚开始只需要“契约文件 一个生成器 一项契约测试”三件套就够。这三样都跑顺了再考虑加Mock服务、加语义检测、加AI Agent自动拆任务。一上来就上十几样工具最后大概率什么也没留下。第三让AI也读文档。我们的AI编程助手的system prompt里固定加了“所有接口和数据类型以docs/api/openapi.yaml为准生成代码前先核对文档”这一段。实践下来AI生成内容的稳定性提升非常明显。文档驱动不只是给人看的也是给AI看的控制面。5.2 后续可以继续深挖的方向文档驱动和AI结合还有很多可以继续扩展的地方。比如在多Agent协作里让文档成为任务脚本规划Agent负责拆分需求任务执行Agent按契约文档写代码测试Agent按验收标准自动判断完成状态整个流程会更接近“可验证的自动化交付”。再比如模型服务部署训练脚本和服务端推理接口经常各定义一套字段模型上线后才发现输入输出对不上。如果把模型的输入输出Schema也纳入文档驱动训练和部署之间就有了统一依据。事件驱动场景也可以用AsyncAPI管理消息契约别让REST文档管住了一切消息Topic里的字段同样需要被约束。我个人现在做新项目第一件事永远是先把OpenAPI骨架搭出来哪怕只有两个接口。等AI把真正的业务逻辑填进去的时候你才会发现文档驱动不是约束是给AI铺了一条不会跑偏的轨道。