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/checkoutv4 - uses: actions/setup-pythonv5 with: python-version: 3.11 - run: pip install mkdocs mkdocs-material - run: mkdocs build --strict - uses: actions/upload-pages-artifactv3 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 能否覆盖功能正确性功能是否符合需求描述否内容准确性文案、数据、流程是否真实否交互体验用户操作是否顺畅部分E2E 测试可覆盖一点边界处理异常情况是否合理部分单元测试可覆盖一点你看CI 能碰到的只有后两个维度的一小部分前两个维度完全靠人工。而 AI Coding 恰恰最容易在前两个维度出问题因为它不理解业务上下文。3. MkDocs 构建成功背后的内容陷阱3.1 Markdown 语法正确不代表文档可用MkDocs 用的是 Python-Markdown 或者 Material 主题自带的解析器它对 Markdown 语法的容忍度其实挺高的。你写个表格列数对不齐它也能渲染你写个链接路径写错了它可能只是警告。--strict模式能抓出一部分问题但抓不出内容问题。举个具体的例子。Markdown 表格复制到 Excel 是很多人的需求AI 生成的表格经常出现这种情况| 参数 | 说明 | 默认值 | |------|------|--------| | timeout | 超时时间 | 30 | | retry | 重试次数 | 3 |看起来没问题对吧但如果你的实际配置里timeout默认是 60 秒AI 写了 30CI 照样全绿文档照样构建成功但用户照着配就出问题了。这种错误 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 图片路径本地能看线上 404Markdown 图片路径是另一个重灾区。AI 写文档时经常用相对路径本地用 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-pagesv3 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-lintv1 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 的锅这是验收这件事本身的性质决定的——它需要理解而理解是人的事。