模块 01第 1 学期 · 基础

AI 辅助的工程工作流

登录后可在不同设备间同步进度。在此之前，进度只保存在当前浏览器中。

为什么重要

DORA 2025 年的研究把 AI 描述为一个放大器：它落在什么样的体系里，就放大什么。小批量交付、有测试、反馈快的团队会变得更快；没有这些的团队，只会更快地把 bug 发出去。这个模块先把体系搭好，再谈引入更多 AI。

学习目标

  1. 写出 AI 可以照着实现的需求规格（spec）和验收测试。
  2. 做好上下文工程：规则文件、架构说明、示例、约束。
  3. 以小而可评审的批次工作，用 git 作为安全网。
  4. 系统地评审 AI 的产出，并让 AI 证明它的说法。
  5. 用 DORA 的五项指标衡量交付。

课程内容

1.1 先写 spec，再写 prompt

一个好的 AI 任务包含：目标、上下文、约束、接口、验收标准、不在范围内的事项。

GOAL: Users can reset their password by email.
CONTEXT: Next.js app router, Supabase auth, Resend for email. See /docs/architecture.md.
CONSTRAINTS: Token single-use, expires in 30 min, stored hashed. Rate limit 5 requests/hour per email and per IP. Same response whether or not the email exists.
ACCEPTANCE: tests in /tests/reset.spec.ts must pass (write them first).
OUT OF SCOPE: SMS reset, UI redesign.

1.2 上下文工程

  • 仓库级规则文件（AGENTS.md 模板），写明 AI 每次都必须遵守的标准。
  • /docs/architecture.md：组件、数据流、信任边界。
  • /docs/decisions/：ADR（架构决策记录），免得 AI 反复推翻已经定下的选择。
  • 给 AI 指向代码库里一个好的现有示例；它会忠实地照搬模式，不管好坏。

1.3 小批量与 git 纪律

  • 一个功能一个分支；一个关注点一次提交。
  • 每次和 AI 协作前先提交，这样你可以用 git diff 查看它改动的一切，用 git restore 撤销任何你不满意的改动。
  • 绝不允许 agent 在未经批准的情况下执行 git push --force、对生产环境跑迁移，或执行删除命令。
  • 在 DORA 识别出的所有手段中，小批量变更是同时提升速度和稳定性最有效的一个。

1.4 测试即规格

为 AI 时代调整过的测试金字塔：

  • 单元测试：纯逻辑（定价、资格判定、校验）。
  • 集成测试：在 Docker 里跑真实数据库，真实查询，真实的 RLS 策略。
  • 端到端测试：用 Playwright 覆盖关键路径（注册、支付、核心操作）。
  • 安全测试：针对“用户 A 无法读取用户 B 的数据”的授权测试。这是你会写的最有价值的测试。
  • Evals（评测）：用于 LLM 功能（见 06 · AI 与 Agent 安全）。

规则：测试由你自己写或亲自评审；实现交给 AI。如果测试和实现都由 AI 来写，它可能以同样的方式把两者都写错。

1.5 评审 AI 的产出

评审清单（贴进你的 PR 模板）：

  1. 每个端点是否都检查了谁在调用，以及对方是否拥有该资源？
  2. 是否有任何密钥、key 或 token 出现在服务端环境变量之外？
  3. 是否有对外调用没有设置超时？
  4. 是否有数据库查询写在循环里？
  5. 是否引入了新依赖？它真的存在吗？有人维护吗？版本锁定了吗？
  6. 错误是被处理、记录并上报了，还是被吞掉了？
  7. 这个改动可逆吗？有迁移吗？向后兼容吗？
  8. 是否改动了任务范围之外的文件？

让 AI 证明它的说法：“运行测试，把输出贴出来。”“给我看 EXPLAIN 执行计划。”“给出能证明用户 A 访问用户 B 的记录会得到 403 的 curl 命令。”

1.6 衡量交付：DORA 的五项指标

分组 指标
吞吐量 变更前置时间；部署频率；失败部署的恢复时间
不稳定性 变更失败率；部署返工率

DORA 提醒不要把这些指标变成考核目标（古德哈特定律）。用它们来找瓶颈。

1.7 AI 会跳过的质量基本功

CI 中的 lint 和格式化、TypeScript 严格模式、无障碍（语义化 HTML、表单标签、键盘导航、对比度达到 WCAG 2.2 AA），以及在每个边界用 schema 库（Zod、Valibot）做输入校验。

实验 1：用专业的方式构建一个功能

用 spec 模板构建“重置密码”或“邀请队友”功能。

  1. 先写 spec 和测试（AI 可以帮忙起草，由你批准）。
  2. 让 AI 在分支里实现。
  3. 用评审清单检查；记录发现的每一个问题。
  4. 提交 PR；CI 必须运行 lint、类型检查和测试。

完成标准

AI 提示词包

  • “在写代码之前，先列出这个 spec 的边界情况和失效模式。先不要实现。”
  • “写出在缺少授权检查时会失败的测试。”
  • “以一个挑剔的资深工程师身份评审这个 diff。只列问题，按严重程度排序。”