转写说明

本文基于已校验的公开原文进行结构化转写与事实梳理，非原文转载。 转写保留可核验的技术事实，并将工程建议与来源观点明确分开。

核心结论

测试先行（Test-Driven Development，TDD）在 AI 协作项目中的核心价值在于把“改动必须可验证”固化为可机器执行的协作规则。TDD 不是先写代码再补测试，而是遵循 Red-Green-Refactor 循环：先写一个会失败的测试，运行确认失败原因，再写最少代码让测试通过，最后在测试全绿的前提下重构。

在 AI 参与编码的背景下，TDD 克制了 AI 写代码容易“顺手改多、证据缺失、回归隐蔽”的问题。测试作为契约要求 AI 在动手前明确期望行为，失败输出作为证据防止声称修复却未复现 bug，回归被即时捕获则依赖每次改完跑全量测试。

该项目的 TDD 治理并非单点规则，而是由入口规则（AGENTS.md）决定触发时机、专项 skill 决定执行步骤、门禁层决定是否被绕过、文档层提供验收引用、质量门禁决定最终通过、失败证据决定是否真正先测后写。这六层结构形成完整闭环。

能力机制

项目的前端测试栈基于 Vitest，配合 @testing-library/react、@testing-library/jest-dom 和 jsdom。Vitest 配置位于 web/vitest.config.ts，启用 jsdom 环境并引入全局测试工具和匹配器扩展。

测试文件与被测源码放在同一目录而非独立的 __tests__/ 目录。这种组织方式使 AI 在修改源码时能直接看到同目录的测试约束，降低查找测试的跳转成本。

规则落地采用 Skill、门禁、文档三层互锁机制。Skill 层定义即时行为指令，通过 .agents/skills/test-driven-development/SKILL.md 承载，负责执行 Red-Green-Refactor 循环的具体步骤。门禁层提供机器兜底，通过 scripts/check-frontend-tdd.mjs 在提交前检查逻辑文件是否带同目录测试，fix 类提交还必须同时变更测试文件。文档层保留上下文与验收标准，引用 Skill 和门禁而不重复规则，由 docs/harness/frontend-testing.md 等文件承载。

TDD 触发条件按代码改动性质判定而非显式触发。新增功能、新组件、新工具函数、修复 bug、修改行为或交互、重构这五类情况必须走 TDD。纯样式或布局改动、配置改动、类型声明改动、文档改动不强制单元测试。

快速开始

质量门禁聚合命令位于根目录 package.json，通过 check:all 脚本串联多项检查：

1

"check:all": "npm run check:harness && npm run check:frontend-tdd && npm run format:check && npm run lint:check && npm run stylelint:check && npm run test --workspace=web && npm run build:web"

TDD 专检命令 check:frontend-tdd 对本次 git 变更中 web/src/** 的逻辑文件检查同目录是否存在 *.test.ts(x) 文件。该检查被挂在 husky 的 pre-commit 和 pre-push 钩子上。

TDD 执行的完整流程包括：读取 frontend-context.md、frontend-rules.md、test-driven-development/SKILL.md 获取上下文；根据需求或 bug 写最小测试；运行单文件测试确认 Red 失败原因是行为缺失或 bug 存在而非语法错误；编写最小实现让测试通过；再次运行测试确认 Green 并检查其他测试未被破坏；可选地在测试全绿下重构；最后运行 check:all 通过完整质量门禁。

适用边界

该方案适用于 AI 参与编码的开发团队。其价值在于将“可验证”前置为默认动作，使 AI 每次改代码前都必须先回答期望行为是什么。

在实践中需注意三个边界条件。首先，TDD 触发按改动性质判定不看 prompt 措辞，用户未明确提及测试相关词汇时仍需按代码改动类型判断是否执行 TDD。其次，必须保留 Red 失败证据，修复 bug 时需保存测试失败的命令输出或截图作为凭据，否则不算真正完成 TDD。第三，Mock 使用需克制，项目目前仅对浏览器 API、网络、时间等边界进行 mock，工具函数测试使用真实实现，避免为测试专门加生产方法或“为了保险”乱 mock。

四个典型场景覆盖了新增工具函数、修复 bug、组件行为变化、重构。项目提供的示例 GitHub 仓库包含完整的 Vitest 配置和测试文件组织结构。

核验清单

检查 web/vitest.config.ts 是否正确配置 jsdom 环境和全局测试工具。验证测试文件与被测源码是否同目录放置。确认 .agents/skills/test-driven-development/SKILL.md 存在且定义完整的 Red-Green-Refactor 流程。检查 scripts/check-frontend-tdd.mjs 是否对 web/src/** 逻辑文件实现同目录测试检查并排除非逻辑文件。验证 husky 钩子是否正确挂载 TDD 专检命令。确认 check:frontend-tdd 脚本在 package.json 中正确定义且与 check:all 串联。检查项目是否建立三层互锁机制（Skill 层、门禁层、文档/计划层）而非仅依赖单一 Skill 文件。验证 TDD 触发条件文档是否明确区分必须走 TDD 与不强制单元测试的场景分类。

来源与核验

  • 原始文章
  • 页面事实以原始来源及其引用的官方资料为准；版本、星标和模型能力会随时间变化。
  • AI Stack 不公开抓取到的全文快照，只发布独立转写与来源入口。

站内链接

相关文章