CI全绿不等于需求验收：AI Coding时代的验收断层与应对

1. 从一次"全绿翻车"说起：CI 通过不等于需求验收

CI 流水线全绿，部署也成功了，但需求方打开页面一看，直接打回来重做——这个场景在 AI Coding 越来越普及的今天，出现的频率高得离谱。我自己就经历过好几次：GitHub Actions 上每一个 job 都是绿色对勾，MkDocs 构建成功，Pages 部署成功，链接也能打开，但产品经理看完只说了一句"这不是我要的东西"。

问题出在哪？出在我们把"技术层面的通过"当成了"需求层面的通过"。CI 能验证的东西非常有限：代码能不能编译、测试用没通过、构建产物能不能生成、部署有没有报错。但 CI 验证不了的是：这个功能是不是用户真正要的、文案对不对、交互流程顺不顺、边界情况处理得合不合理。AI 写代码的时候，它擅长的是"把指令翻译成能跑的代码"，但它不擅长"理解指令背后真正的业务意图"。

这篇文章我想把这件事拆开讲透。适合谁看？适合正在用 AI Coding 辅助开发、用 GitHub Actions 做 CI、用 MkDocs 维护文档站或者做静态站点发布的朋友。不管你是刚入门 AI Coding 的新手，还是已经能熟练配置流水线的老手，这篇内容应该都能帮你少踩几个坑。核心关键词就几个：CI、MkDocs、GitHub Actions、AI Coding、Markdown——但我要讲的不是这些工具怎么用，而是它们凑在一起时，那个最容易被忽略的"验收断层"。

先说结论：CI 全绿只是"代码没坏"，离"需求做对"还差着十万八千里。下面我从几个角度把这个问题彻底拆开。

2. CI 到底验证了什么，又漏掉了什么

2.1 GitHub Actions 的检查清单里没有"需求"这一项

我们先看一个典型的 GitHub Actions 工作流在做什么。假设你有一个 MkDocs 项目，流水线大概长这样：

name: Build and Deploy Docs on: push: branches: [main] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: python-version: '3.11' - run: pip install mkdocs mkdocs-material - run: mkdocs build --strict - uses: actions/upload-pages-artifact@v3 with: path: site

这个流程跑完，CI 告诉你的是：依赖装上了、MkDocs 构建没报错、产物上传了。如果再加一个部署 job，它还会告诉你 Pages 部署成功了。但注意，mkdocs build --strict这个--strict标志只会把警告当错误处理，它检查的是链接有没有断、Markdown 语法有没有问题，它不检查你写的内容对不对。

这就是第一个断层：CI 验证的是"形式正确"，不是"内容正确"。AI 生成的 Markdown 文档，语法上完美无缺，标题层级规范，链接全部有效，但内容可能是它自己编的，跟你的实际业务对不上。

2.2 AI Coding 的"自信幻觉"：它永远觉得自己写对了

用 AI 写代码或者写文档，最大的陷阱是它会用一种非常笃定的语气输出。你让它写一个发布流程的说明文档，它会洋洋洒洒写一大篇，步骤清晰、格式漂亮，但里面可能有几个关键步骤是它"推测"出来的，跟你们团队实际的做法根本不一样。

我踩过的一个典型坑：让 AI 帮我写 MkDocs 的部署文档，它写了一套用mkdocs gh-deploy的流程，看起来很标准。但我们团队实际用的是 GitHub Actions 自动部署，根本不用手动gh-deploy。文档发出去之后，新来的同事照着做，本地跑gh-deploy把分支搞乱了。CI 全绿，文档也构建成功，但内容误导了人。

AI 不会告诉你"我不确定这一步"，它只会用最流畅的语言把最合理的猜测写出来。这就是为什么 AI Coding 场景下，人工验收这一环绝对不能省。

2.3 需求验收的四个维度，CI 一个都覆盖不了

我把需求验收拆成四个维度，你可以对照看看自己的 CI 覆盖了几个：

你看，CI 能碰到的只有后两个维度的一小部分，前两个维度完全靠人工。而 AI Coding 恰恰最容易在前两个维度出问题，因为它不理解业务上下文。

3. MkDocs 构建成功背后的内容陷阱

3.1 Markdown 语法正确不代表文档可用

MkDocs 用的是 Python-Markdown 或者 Material 主题自带的解析器，它对 Markdown 语法的容忍度其实挺高的。你写个表格，列数对不齐它也能渲染；你写个链接，路径写错了它可能只是警告。--strict模式能抓出一部分问题，但抓不出内容问题。

举个具体的例子。Markdown 表格复制到 Excel 是很多人的需求，AI 生成的表格经常出现这种情况：

| 参数 | 说明 | 默认值 | |------|------|--------| | timeout | 超时时间 | 30 | | retry | 重试次数 | 3 |

看起来没问题对吧？但如果你的实际配置里timeout默认是 60 秒，AI 写了 30，CI 照样全绿，文档照样构建成功，但用户照着配就出问题了。这种错误 CI 永远抓不到。

3.2 数学公式和特殊语法的渲染盲区

现在很多技术文档会用到数学公式，MkDocs 需要装pymdown-extensions并配置arithmatex才能渲染 LaTeX 公式。AI 写文档的时候，如果它不知道你的 MkDocs 配置，可能会写出这样的内容：

行内公式 $E = mc^2$ 多行公式： $$ \begin{aligned} a &= b + c \\ d &= e + f \end{aligned} $$

如果mkdocs.yml里没配arithmatex，这些公式在页面上就是一堆乱码似的文本。但 CI 构建不会报错，因为对 Markdown 解析器来说，这就是普通文本。你打开页面才发现公式没渲染，但那时候已经部署上线了。

Markdown 大括号多行公式这种写法，在 GitHub 上能渲染，在 MkDocs 上不一定能，取决于你的插件配置。这种"平台差异"是 AI 最容易忽略的，因为它训练数据里混了各种平台的写法。

3.3 图片路径：本地能看，线上 404

Markdown 图片路径是另一个重灾区。AI 写文档时经常用相对路径：

![架构图](./images/arch.png)

本地用 Typora 或者 Sublime 看 Markdown 的时候，图片能正常显示。但 MkDocs 构建后，./images/相对于当前页面文件的路径可能就变了。如果开了use_directory_urls（默认开启），页面 URL 会变成/page/而不是/page.html，相对路径的基准就变了。

CI 构建不会检查图片是否存在，mkdocs build默认也不校验图片路径。结果就是线上图片全部 404，但 CI 全绿。这种问题在验收时才会被发现，但那时候已经晚了。

提示：在mkdocs.yml里开启strict: true并且配合mkdocs-linkcheck插件，可以在构建阶段抓出一部分死链，但图片路径的校验需要额外配置。

4. 需求验收断层：AI 不懂"验收标准"这件事

4.1 验收标准是隐性的，AI 读不到

需求验收的标准，很多时候不在需求文档里，而在需求方的脑子里、在团队的默契里、在过往的沟通记录里。比如"发布流程要简单"，什么叫简单？三步以内叫简单，还是不需要登录叫简单？AI 不知道，它只能猜。

我见过一个案例：团队让 AI 写一个发布流程的 CI 配置，AI 写了一个包含 8 个 job 的复杂流水线，每个 job 都有详细的步骤。技术上完美，但需求方要的是"一键发布"。AI 把"完整"理解成了"专业"，把"简单"理解成了"详尽"。CI 全绿，但需求方要的"一键"根本没实现。

4.2 从"能跑"到"好用"之间隔着人的判断

AI Coding 的产出，默认停在"能跑"这个层面。它能生成一个能构建、能部署、能通过测试的项目，但"好用"需要人来判断。发布流程尤其如此，因为发布流程的"好用"标准非常主观：

• 发布失败时，错误信息够不够清楚？
• 回滚方不方便？
• 发布通知发到哪里，格式对不对？
• 发布记录能不能追溯？

这些没有一个是 CI 能验证的。CI 只能告诉你"发布脚本执行成功了"，但发布脚本执行成功不等于发布流程好用。

4.3 一个真实的验收翻车复盘

说个我自己的翻车经历。有一次我用 AI 辅助写了一个 MkDocs 文档站的发布流程，CI 配置得漂漂亮亮，GitHub Actions 全绿，Pages 部署成功。我信心满满地交给需求方验收，结果被打回来三个问题：

第一，文档首页的导航结构不对。AI 按照它理解的逻辑生成了导航，但需求方要的是按照产品模块划分，不是按照文档类型划分。这个 CI 完全看不出来。

第二，搜索功能没配。MkDocs Material 主题自带搜索，但需要在mkdocs.yml里配置search插件和语言。AI 生成的配置里漏了这一项，CI 不报错，但用户搜不到东西。

第三，移动端显示有问题。AI 生成的表格在窄屏上溢出，CI 不检查响应式布局。

这三个问题，没有一个能被 CI 抓到。这就是"CI 全绿但验收不过"的典型现场。

5. 把验收标准前置到 CI 里的可行做法

5.1 用 checklist 把隐性标准显性化

既然 AI 读不到隐性标准，那就把它写出来。我现在的做法是，在项目根目录放一个ACCEPTANCE.md，把需求方的验收标准一条条列出来。比如：

## 验收清单 - [ ] 首页导航按产品模块划分，不超过 5 个一级菜单 - [ ] 搜索功能可用，支持中文 - [ ] 所有代码块有语法高亮 - [ ] 移动端表格不溢出 - [ ] 发布流程三步以内完成

这个文件不参与构建，但它是给 AI 看的。每次让 AI 改东西之前，把这份清单贴给它，让它对照着改。实测下来，AI 的产出质量会明显提升，因为它有了明确的判断依据。

5.2 在 CI 里加内容校验步骤

CI 虽然不能验证"需求对不对"，但可以验证一些"内容层面的硬性要求"。比如：

- name: Check content requirements run: | # 检查是否有空的章节 if grep -rn "^## $" docs/; then echo "发现空标题" exit 1 fi # 检查图片路径是否存在 python scripts/check_images.py # 检查是否有 TODO 遗留 if grep -rn "TODO" docs/; then echo "发现未完成的 TODO" exit 1 fi

这些检查很土，但很有效。AI 生成的文档经常有空的章节标题、失效的图片路径、遗留的 TODO 标记，这些都能在 CI 阶段抓出来。

5.3 用预览环境做人工验收的"预演"

GitHub Actions 可以配置 PR 预览环境，每次提交 PR 时自动部署一个临时站点。这样需求方可以在合并之前就看到效果，而不是等合并上线后才发现问题。

- name: Deploy preview if: github.event_name == 'pull_request' uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./site destination_dir: preview/pr-${{ github.event.number }}

这个预览环境是人工验收的第一道关。需求方在预览环境上点一遍，确认没问题了再合并。这样就把"验收"从"上线后"提前到了"合并前"，返工成本大大降低。

6. AI Coding 场景下的验收工作流重构

6.1 把"AI 生成"和"人工验收"拆成两个独立环节

我现在的工作流是这样的：AI 负责生成初稿，我负责验收和修改。这两个环节严格分开，不混在一起。AI 生成完之后，我不会直接提交，而是先自己过一遍，对照验收清单逐条检查。

这个习惯看起来简单，但能避免 80% 的翻车。因为 AI 生成的内容有一种"看起来都对"的迷惑性，你不主动去挑刺，很容易就放过去了。

6.2 验收清单要跟着需求走，不能一劳永逸

验收清单不是写一次就完事的。每次需求变更，清单也要更新。比如需求方突然说"文档要支持暗色模式"，那清单里就要加一条"暗色模式下代码块对比度正常"。AI 不会主动想到这些，只有你把标准写清楚，它才能照着做。

6.3 建立"验收失败"的复盘机制

每次验收失败，都值得记录一下：是什么问题、CI 为什么没抓到、下次怎么预防。我自己的复盘记录里，排名前三的验收失败原因是：内容与需求不符、交互体验问题、边界情况未处理。这三个原因，没有一个能靠 CI 解决，全靠人工验收。

但复盘的价值在于，你会发现某些验收失败是重复出现的。比如"AI 生成的表格默认值写错"这个问题，我遇到过至少五次。后来我就在验收清单里加了一条"所有默认值必须与配置文件核对"，这个问题就再也没出现过。

7. 几个能立刻用上的实操技巧

7.1 让 AI 先复述需求再动手

这是我从一位前辈那里学来的技巧。让 AI 写东西之前，先让它用自己的话复述一遍需求，你确认它理解对了再让它动手。比如：

你先别写代码，用三句话告诉我你理解的发布流程是什么样的。

AI 复述的过程中，你就能发现它哪里理解偏了。这个技巧能挡掉一大半的"方向性错误"。

7.2 用 Markdown 语法检查工具兜底

markdownlint是个好东西，能抓出很多格式问题。配合 GitHub Actions 用：

- name: Lint Markdown uses: avto-dev/markdown-lint@v1 with: args: 'docs/'

它能检查标题层级、列表缩进、代码块语言标注等。虽然管不了内容，但能保证格式规范，减少低级错误。

7.3 发布前跑一遍"用户视角"的检查

发布之前，我会用无痕模式打开站点，假装自己是一个第一次来的用户，从头到尾点一遍。重点看：导航能不能找到想要的东西、搜索能不能搜到、代码块能不能复制、链接能不能点。这个检查花不了十分钟，但能抓到很多 CI 抓不到的问题。

7.4 把验收标准写进 PR 模板

在.github/pull_request_template.md里放一份验收清单，每次提 PR 的时候自动带出来：

## 验收清单 - [ ] 功能符合需求描述 - [ ] 文案准确无误 - [ ] 移动端显示正常 - [ ] 搜索功能可用 - [ ] 无遗留 TODO

这样每次提 PR 都会提醒自己对照检查，形成习惯之后，验收通过率会明显提升。

8. 我个人的几点体会

用 AI Coding 这一年多，我最大的体会是：AI 把"写"这件事的门槛降到了零，但把"验收"这件事的重要性提到了最高。以前写代码慢，但写的过程中人会不断思考，很多问题在写的时候就发现了。现在 AI 几秒钟生成一大段，人容易跳过思考直接提交，问题就留到了验收环节。

CI 是个好东西，但它只是个"守门员"，守的是技术底线，不是需求底线。真正决定验收能不能过的，是人对需求的理解和对细节的把控。AI 可以帮你写，但不能帮你判断"这是不是对的"。

所以我的建议是：把 CI 当成第一道防线，把人工验收当成最后一道防线，中间再加一道"AI 复述需求"的预检。三道防线下来，翻车概率会低很多。至于那些 CI 抓不到的内容问题、体验问题、边界问题，只能靠人一条条去抠。这不是 AI 的锅，这是"验收"这件事本身的性质决定的——它需要理解，而理解是人的事。